Plugin metadata

Plugin metadata is made possible in the form of specially formed comments in plugin files. The extensible syntax allows developers to either embed data directly into plugins, or include other files for longer metadata sections.

Metadata blocks hold basic plugin information, installation and removal schemas, upgrade instructions, and language strings, and can be extended to include other data.

Format and syntax

The basic format for metadata blocks is as follows:

/**!block**
... data goes here ...
**!*/

Blocks can also have attributes; all attributes must be double-quoted and followed by a semi-colon:

/**!block var1="foo"; var2="bar"; **
... data goes here ...
**!*/

Enano blocks

Enano uses several different blocks in plugins officially.

Info - basic plugin information

The !info block must be at the top of every plugin. It is in JSON format.

/**!info**
{
  "Plugin Name"  : "Gorilla Paste",
  "Plugin URI"   : "http://enanocms.org/plugin/gorilla",
  "Description"  : "For The Toughest Pasting Jobs On Earth.™ The pastebin, Enano style.",
  "Author"       : "Dan Fuhry",
  "Version"      : "0.1.1",
  "Author URI"   : "http://enanocms.org/",
  "Version list" : ['0.1', '0.1.1']
}
**!*/

All of the keys above are required, except for "Version list" if your plugin does not depend on its own database modifications.

Install and uninstall - database modifications

These two blocks are syntactically equivalent except for the name.

The uninstall block should reverse any changes your plugin makes to the site's database - even if this means losing data. The user is sternly warned before the Uninstall function is invoked.

The only supported attribute for these blocks is "dbms", which can be either "mysql" or "postgresql".

/**!install dbms="mysql"; **
CREATE TABLE {{TABLE_PREFIX}}pastes(
  paste_id int(18) NOT NULL auto_increment,
  paste_title text DEFAULT NULL,
  paste_text text NOT NULL DEFAULT '',
  paste_author int(12) NOT NULL DEFAULT 1,
  paste_author_name varchar(255) NOT NULL DEFAULT 'Anonymous',
  paste_author_ip varchar(39) NOT NULL,
  paste_language varchar(32) NOT NULL DEFAULT 'plaintext',
  paste_timestamp int(12) NOT NULL DEFAULT 0,
  paste_ttl int(12) NOT NULL DEFAULT 86400,
  paste_flags int(8) NOT NULL DEFAULT 0,
  paste_parent int(18) NOT NULL DEFAULT 0,
  PRIMARY KEY ( paste_id )
) ENGINE=`MyISAM` CHARSET=`UTF8` COLLATE=`utf8_bin`;
 
**!*/
 
/**!install dbms="postgresql"; **
CREATE TABLE {{TABLE_PREFIX}}pastes(
  paste_id SERIAL,
  paste_title text DEFAULT NULL,
  paste_text text,
  paste_author int NOT NULL DEFAULT 1,
  paste_author_name varchar(255) NOT NULL DEFAULT 'Anonymous',
  paste_author_ip varchar(39) NOT NULL,
  paste_language varchar(32) NOT NULL DEFAULT 'plaintext',
  paste_timestamp int NOT NULL DEFAULT 0,
  paste_ttl int NOT NULL DEFAULT 86400,
  paste_flags int NOT NULL DEFAULT 0,
  paste_parent int NOT NULL DEFAULT 0,
  PRIMARY KEY ( paste_id )
);
 
**!*/

Upgrades

This is where the going can get a little tricky: providing a way for plugins to be automatically upgraded when you release a new version with fresh database modifications.

Enano uses an incremental upgrade system. This means you don't have to spend hours maintaining new database revisions, but you do have to give Enano a list of every version of your plugin (or at least every version that has database changes) and then specify the "from" and "to" version numbers in every upgrade block. This way, a user can upgrade across multiple versions seamlessly.

An example:

/**!info**
{
  // ...
  'Version list' : ['0.1', '0.2', '0.5', '1.0']
}
**!*/
 
/**!upgrade from="0.1"; to="0.2"; dbms="mysql"; **
ALTER TABLE {{TABLE_PREFIX}}foo_table ADD COLUMN bar_column varchar(32) NOT NULL DEFAULT '';
**!*/
 
/**!upgrade from="0.2"; to="0.5"; dbms="mysql"; **
ALTER TABLE {{TABLE_PREFIX}}foo_table ADD COLUMN baz_column varchar(32) NOT NULL DEFAULT '';
**!*/
 
/**!upgrade from="0.5"; to="1.0"; dbms="mysql"; **
ALTER TABLE {{TABLE_PREFIX}}foo_table ADD COLUMN quux_column varchar(32) NOT NULL DEFAULT '';
**!*/

Language strings - allow translations of your plugin

Language strings are done all in one block, not multiple blocks by language. They are done in the same JSON format that Enano language files are in, but with one additional level for including multiple languages.

/**!lang**
{
  eng: {
    categories: ['meta', 'myplugin'],
    strings: {
      meta: {
        myplugin: 'My plugin'
      },
      myplugin: {
        foo: 'Foo',
        bar: 'Baz'
        // ...
      }
    }
  }
}
**!*/

The string "foo" under "myplugin" can then be fetched in the following ways:

// PHP
echo $lang->get('myplugin_foo');

// Javascript:
load_component('l10n'); // only need to do this once
alert($lang.get('myplugin_foo'));

For more information on how to use language strings, see the Localization API.

Categories: (Uncategorized)