Pluggable

From Habari Project

Jump to: navigation, search

This page provides documentation of the pluggable xml format, which is used by both themes and plugins. For plugins, the file containing this xml should be named pluginname.plugin.xml. For themes, it can simply be theme.xml.

The XSD for pluggable is available, and there is also a tool to validate your xml.

Contents

Schema

This documentation provides a hierarchical overview of the schema, used by both plugins and themes. Not all elements are required.

name

Required: Names the plugin or theme.

license

Required: Licenses the plugin or theme. The required url attribute should point to the full license.

author

Required: Identifies the author(s) of the plugin or theme. Multiple authors can be named, with each having a required url attribute pointing to their website. Pointing the url to http://habariproject.org is okay too.

copyright

Optional: Provides a copyright notice for the plugin or theme.

version

Required: Identifies the version of the plugin or theme, usually as a version number. (Ex. 1.4)

help

Optional: Provides helpful information for plugin usage. It's displayed in the plugin admin.

<help>
  <value>
    <![CDATA[
      <p>
        This is the default helpful text for the plugin. It shows on the plugin page as 
        the common (?) help select drop down.
      </p>
      <p> 
        It might tell the user what they will need to use the plugin, or general help.
      </p>
    ]]>
  </value>
  <value xml:lang="es-es"><![CDATA[Esto es útil cosas.]]></value>
</help>
<help name="Configure">
  <value>
    <![CDATA[
      <p>
        This is more helpful stuff. This text will only show under the 'Configure' action, 
        which is commonly used within action_plugin_ui(). Any action can be used, with 
        'Configure' being a common example. Multiple actions are allowed.
      </p>
      <p>
        The main help is still available within 'Configure', as the standard (?) drop down, 
        whereas this will show there without user intervention.
      </p>
    ]]>
  </value>
  <value xml:lang="es-es"><![CDATA[Esto es más útil cosas.]]></value>
</help>
  • Note: This is parsed as of Habari 0.7, with help() being used previously.
  • Note: Most plugins will simply have a single <help>, without a name attribute.
  • Note: The default <help> is what shows in the (?) button.

guid

Optional: Provides a UUID identifying the plugin or theme.

downloadurl

Optional: Specifies a URL where the plugin or theme may be downloaded.

url

Required: Specifies a URL where more information can be obtained about a plugin or theme.

description

Required: Briefly describes the plugin or theme. Multiple descriptions can be specified, allowing for Translation.

requires

Optional: Provides a list of features which the plugin or theme requires to run. If one or more of these features are not present, the plugin or theme can not be enabled.

feature

Required: Lists a feature which the plugin requires. Features are provided by the Habari core or other plugins/themes. An optional url attribute can be included to provide a reference for that feature. Suitable reference locations are available on the wiki.

<requires>
  <feature url="http://wiki.habariproject.org/en/feature/podcast">podcast</feature>
</requires>

recommends

Optional: Provides a list of features which the plugin or theme recommends. These features are not required, but the plugin/theme will leverage them if they are present.

<recommends>
  <feature url="http://wiki.habariproject.org/en/feature/podcast">podcast</feature>
</recommends>

feature

Required: Lists a feature which the plugin recommends. See feature.

provides

Optional: Provides a list of features which the plugin or theme. These features are implemented by the plugin or theme, and can be leveraged by other plugins or themes.

<provides>
  <feature url="http://wiki.habariproject.org/en/feature/podcast">podcast</feature>
</provides>

feature

Required: Lists a feature which the plugin provides. See feature.

conflicts

Optional: Provides a list of features which the plugin or theme does not work with. If other active plugins or themes provide this feature, the plugin will not be allowed to activate.

<conflicts>
  <feature url="http://wiki.habariproject.org/en/feature/podcast">podcast</feature>
</conflicts>

feature

Required: Lists a feature which the plugin conflicts with. See feature.

Translation

Many elements within the schema, including the description field, allow for inline translation. To provide this translation, simply create multiple instances of the element, each with a different translation. The first instance does not need a language attribute and should be written in the primary language, while other instances should specify the language using the xml:lang attribute.

<description><![CDATA[This is the description for the resurrection theme.]]></description>
<description xml:lang="es-es"><![CDATA[Esta es la descripción de la resurrección tema.]]></description>
Personal tools