2 what plugin .meta files are for
3 -------------------------------
5 Plugins in ewiki have traditionally been just an asorted collection
6 of PHP include scripts. To accomodate real plugin management (using
7 the PluginLoader or the ConfigurationWizard, WikiInstaller, mkxpi,
8 INI-configurations and other stuff) we had to provide the necessary
11 In-plugin (within comment fields) or centralized (in a big db file)
12 listings have been abandoned in favour of accompanying .meta files.
13 The format is a RFC822/HTTP/VCARD-like list of name:value-pairs in
14 a file with the .meta extension after the basename. This sort of
15 file is easier and faster to parse than XML-style data containers.
21 Currently known and interpreted fields (most of them are optional)
22 and possible values are:
24 api: just "ewiki" or "PHP" for us
25 - could signalize an incompatible plugin, if other CMS
26 suddenly adopted this .meta file scheme
27 - a value of "PHP" says that the plugin is NOT ewiki-
30 type: general description of what the contained code does
31 - this field is NOT in ewiki-specific terminology
32 - eventually not useful in itself, informational
34 "functions" - collection of (random) functions
35 "variables" - variable definitions
36 "data" - constants, large variables, etc.
37 "intercept" - handlers and interrupting control code
38 "mangle" - on strings or data hashes
39 "transform" - html conversion
40 "link" - page names / data mangling
43 "input" - form fields or so
44 "listing" - (html) lists of page names
45 "special" - unspecific
46 "virtual" - the according .php script is ignored,
47 and "R" only the .meta data important
48 "api" - itself provides an interface, remote API
49 sometimes this field just simply contains the name of
50 an ewiki hook (not recommended)
52 hooks: used ewiki plugin hooks as comma separated list,
56 see also INTERNALS and API documentation
58 page: occoupied plugin hooks for the given type, if any,
59 action: comma separated
60 list: (possible field names depend on what was set as type:)
62 id: identifier for this plugin
63 - replaces basename of the current file
66 depends: some pluginmanagers can automatically load other
67 conflicts: plugins or include scripts, if that's a requirement
68 for the current function
69 recommends: another plugin which makes sense in conjunction to the
71 provides: virtual plugin identifier, which other plugins may depend
72 upon (or conflict with)
73 delivers: like provides:, but that ONLY one plugin may deliver it,
74 and all others so become conflicting
76 category: plugins are grouped by structure of the plugins/
77 directory, but for some pluginmanagers a more
78 descriptive and divergent classification is possible
79 using this field and its values (more possible):
80 - action, admin, appearance, authentication, aview, database,
81 edit, extension, feature, filter, fragments, hypertext,
82 library, markup, meta, mpi, old, optimation, page, spam,
84 We use the plugins/ subdirectory name alternatively, but
85 if omitted the plugin could not appear in plugin listings.
87 priority: how important is this plugin - if it's included/loaded
93 "important" - often is
94 "recommended" - should be
95 "optional" - user decided
96 "extra" - ranks higher than "bonus"
97 "bonus" - super-optional gimmicks
98 "rare" - too special for most people
99 "deprecated" - NOT recommended or old
100 "never" - unused, can be enabled only by hand
101 "auto" - a pure dependency
102 WikiInstaller uses this to make differently feature-
104 - this would probably be served better by numeric
105 importance levels (0..10), but hey
107 title: shown by most pluginmanagers, informational
110 author: informational fields for contributed plugins
115 url: download page for new plugin versions
117 version: contributed plugins or from different project/vendor
118 sometimes contain a version number
120 update: URL of actual plugin .php file, best if accompanied
121 by .meta file; used for automatic updates
123 sort: some plugins must be loaded in a certain order to
124 function properly (e.g. database interface before most
126 - gives a relative sequence number
127 - default for all other plugins is 0
128 - range from -100 to +100 for ewiki plugins,
129 outside more for general PHP additions (like
131 rarely needed, rarely present, most pluginmanagers
132 already take care of the database plugins themselves
134 funcs: for dependency/conflict checking, this entry lists
135 all defined functions
137 config: list of configuration constants, variables;
138 description of multi-line format in next paragraph
140 You can add fields as you wish, for some plugins special values
141 (like "*") are sometimes used.
147 The only non-string field is "config:", as it is made up of
148 multiple lines, which describes constants and variables with
149 possible configuration settings. This is mostly used for
150 presenting <form>s which config.php/.ini fiels generated from.
152 Constants are detected, because they are all-uppercase, and
153 configuration variables by a leading dollarg sign. A equal
154 sign follows with either just one default value, or nothing,
155 or a dash | separated list of allowed values. Finally a //
158 CONSTANT_NAME=value // comment, help, info
159 $ewiki_config["name"]= // default is empty string
160 ANOTHER_OPTION=1|2|3|4|5 // possible values
161 OR_EVEN=yes=1|never=0 // entitled, first is default
163 Take care not to have spaces before or after the equal sign.
169 Some plugins must be loaded at certain positions before or with
170 others. Especially the database plugins need to be present
171 before the core script initiates the registered _binary() part.
172 Therefore the sort: field pre-orders loading of them. Currently
173 following ranges and points are defined:
176 -200 non-ewiki additions
178 -100 minimum for ewiki plugins
180 -50 higher-up interfaces, pre-dependencies
182 0 almost all plugins (the zero is implicit, plugins are
183 loaded unordered normally)
187 80 binary module (mostly auto-initiated in core script)
192 Plugins of course may be loaded after +100 and before -100, but
193 generally this should be avoided and the ["init"] hook be used
196 Ordering of plugins must be fine-tuned by users. Registration of
197 action plugins for example always influences the order they are
198 displayed in later. The sort mechanism cannot handle any user
205 As example consider following .meta file:
206 +--------------------------------------------
209 |hooks: handler, page, edit_save
211 |page: VirtualPageName
213 |description: adds interesting features
215 | PLUGIN_SETTING=1|0 // enables it
222 .meta plugin data can later be reimported into plugin files'
223 topmost comment section, if they get prefixed with an "@",
234 There are a few support scripts in the "dtools" package (CVS),
235 which can be useful, if you'd like to tweak defaults or patch
236 descriptions, for some reason??? (doesn't make sense except
237 if you'd like to help out).
239 - "genmeta" created most initial description files from the
240 earlier FEATUREDB and SetupWizard + WikiInstaller
241 - "editmeta.php" can tweak various important fields for all
242 (200+) plugins at once
243 - "metafiles.php" contains general utility code
244 - "updatemeta" can analyze plugins and updates (=does not
245 overwrite) according .meta descriptions - functions, hooks,
246 and general informations
252 The field names and values have been ravamped multiple times in their
253 initial design phase.
254 - "priority:" was called "inclusion:" before
255 - "type:" changed its semantics and possible values
256 - "sort:" was introduced rather late
257 - "name:" has been removed in favor of "id:"
258 - "section:" has been rejected in favour of "category:"