mods/wiki/doc/PluginMetaFiles

   1
   2 what plugin .meta files are for
   3 -------------------------------
   4
   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
   9 data in some form.
  10
  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.
  16
  17
  18 fields
  19 ------
  20
  21 Currently known and interpreted fields (most of them are optional)
  22 and possible values are:
  23
  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-
  28                  specific
  29
  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
  33               for example:
  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
  41                 "database"   - app
  42                 "auth"       - app
  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)
  51
  52   hooks:      used ewiki plugin hooks as comma separated list,
  53                 "page"
  54                 "action"
  55                 ...
  56               see also INTERNALS and API documentation
  57
  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:)
  61
  62   id:         identifier for this plugin
  63                - replaces basename of the current file
  64                - not implemented yet
  65
  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
  70               described
  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
  75
  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,
  83                 user
  84               We use the plugins/ subdirectory name alternatively, but
  85               if omitted the plugin could not appear in plugin listings.
  86
  87   priority:   how important is this plugin - if it's included/loaded
  88               by default:
  89                 "core"           - always
  90                 "required"       - always
  91                 "standard"       - enabled
  92                 "default"        - enabled
  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-
 103               loaded versions.
 104                - this would probably be served better by numeric
 105                  importance levels (0..10), but hey
 106
 107   title:      shown by most pluginmanagers, informational
 108   decription:
 109
 110   author:     informational fields for contributed plugins
 111   homepage:
 112   license:
 113   copyright:
 114
 115   url:        download page for new plugin versions
 116
 117   version:    contributed plugins or from different project/vendor
 118               sometimes contain a version number
 119
 120   update:     URL of actual plugin .php file, best if accompanied
 121               by .meta file; used for automatic updates
 122
 123   sort:       some plugins must be loaded in a certain order to
 124               function properly (e.g. database interface before most
 125               others)
 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
 130                 upgrade.php)
 131               rarely needed, rarely present, most pluginmanagers
 132               already take care of the database plugins themselves
 133
 134   funcs:      for dependency/conflict checking, this entry lists
 135               all defined functions
 136
 137   config:     list of configuration constants, variables;
 138               description of multi-line format in next paragraph
 139
 140 You can add fields as you wish, for some plugins special values
 141 (like "*") are sometimes used.
 142
 143
 144 config: field
 145 -------------
 146
 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.
 151
 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 //
 156 comment may follow.
 157
 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
 162
 163 Take care not to have spaces before or after the equal sign.
 164
 165
 166 sort: ordering
 167 --------------
 168
 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:
 174
 175
 176   -200    non-ewiki additions
 177     ..
 178   -100    minimum for ewiki plugins
 179     ..
 180    -50    higher-up interfaces, pre-dependencies
 181     ..
 182      0    almost all plugins (the zero is implicit, plugins are
 183           loaded unordered normally)
 184     ..
 185     50    database backend
 186     ..
 187     80    binary module (mostly auto-initiated in core script)
 188     ..
 189    100    ewiki core
 190     ..
 191
 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
 194 instead.
 195
 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
 199 preferences.
 200
 201
 202 example
 203 -------
 204
 205 As example consider following .meta file:
 206 +--------------------------------------------
 207 |api: ewiki
 208 |type: intercept
 209 |hooks: handler, page, edit_save
 210 |category: blocks
 211 |page: VirtualPageName
 212 |title: module-name
 213 |description: adds interesting features
 214 |config:
 215 |  PLUGIN_SETTING=1|0  // enables it
 216
 217
 218 notes
 219 -----
 220
 221 future:
 222   .meta plugin data can later be reimported into plugin files'
 223   topmost comment section, if they get prefixed with an "@",
 224   like for example:
 225    /*
 226     *  @api: ewiki
 227     *  @title: ...
 228     */
 229
 230
 231 tools
 232 -----
 233
 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).
 238
 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
 247
 248
 249 changelog
 250 ---------
 251
 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:"
 259