HFS: plugins design

From rejetto wiki
Jump to: navigation, search

This document is a plan for the plugin systems for HFS to come.

The system aims to ease and organize the customization of features in HFS.

Main design notes

Every plugin is an XML containing macros scripts. In case the design extends to multifile system, the file will actually be a ZIP archive, with a plugin.xml file in its root with the same content of the just mentioned XML. This description may refer to some tags and details explained visible in the #XML format section.

In both cases, being it a plain XML, or a ZIP archive with an XML inside, the file has .hfsplugin extension. Such extension must be registered in the system, so that HFS handles it (and install it if needed) when the user double-clicks on it.

All plugins are kept in memory in a sorted list, complying to tag <order>. The list should be visible to the user in a specific dialog, where the user can disable/remove plugins.

<tpl> and <events> should be applied on-the-fly, and never change the content of the template or of the events scripts file.

XML format

Note: {curly braces} here have nothing to do with those used with {.macros.} but just refers to user defined content.

<?xml version="1.0" encoding="utf-8"?>
<hfs
  required_build="{optional: minimum hfs build number requried for this plugin to work}"
  max_build="{optional: maximum hfs build number supported by this plugin}">
        <plugin
          name="{name of the plugin}"
          version="{displayed version}"
          progressive="{progressive version number}"
          type="{optional: forget }"
          icon="{optional: relative path to image file. gif/bmp supported}">
                <contact name="{author's name}" email="{author's email}" otherdetail="{all attributes of this tag should be displayed in an appropriate place}" />
                <update url="{url for retrieving latest version}" />
                <order>
                <!-- this section forces specific order between this and another plugins -->
                        <other place="{before|after}" name="{other plugin's name}" />
                        <other ... />
                </order>
                <introduce showOptions="{before|after|no}">
                        {message to show before installation}
                </introduce>
                <install>
                        {script to execute at installation time}
                </install>
                <uninstall>
                        {script to execute at uninstallation time}
                </uninstall>
                <events>
                        {text to  be appended to the events script file}
                </events>
                <tpl>
                        {text to be used as diff template}
                </tpl>
                <options>
                        <onchange>
                               {script to execute when options are changed}
                        </onchange>
                        <option
                          name="{the name}"
                          help="{longer description, for when the name is not clear enough}"
                          type="{yesno|number|choose|long text|text line}"
                          restriction="{if number:min-max; if chooose:value1|value2; if text:regexp}" />
                        <option ... />
                </options>
        </plugin>
</hfs>


Details

Attribute plugin.type accepts just one value at the moment. forget means this is not a real plugin, but only the 'install' tag must be executed, while the rest is discarded.

Priorities

these things can be implemented in a second moment:

  • <contact>
  • <plugin icon="">
  • <update>
  • <options>

Doubts and ideas

<tpl urlmask="{the diff tpl is applied only if this mask is matched by the url}">
NO. this should be easily achieved by using commands inside the diff tpl itself.
maybe we need a way to decide order separately for <tpl> and <events>.
try to make plugins be also full templates

Implementation details

the eventScripts will work as head of a linked list, where the link is the over property.