HFS: plugins design: Difference between revisions

From rejetto wiki
Jump to navigation Jump to search
 
(11 intermediate revisions by 2 users not shown)
Line 1: Line 1:
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.
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.
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.
Line 23: Line 28:
           version="{displayed version}"
           version="{displayed version}"
           progressive="{progressive version number}"
           progressive="{progressive version number}"
           icon="{optional: gif/bmp supported}">
          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}" />
                 <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}" />
                 <update url="{url for retrieving latest version}" />
Line 31: Line 37:
                         <other ... />
                         <other ... />
                 </order>
                 </order>
                 <introduce>
                 <introduce showOptions="{before|after|no}">
                         {message to show before installation}
                         {message to show before installation}
                 </introduce>
                 </introduce>
Line 37: Line 43:
                         {script to execute at installation time}
                         {script to execute at installation time}
                 </install>
                 </install>
                <uninstall>
                        {script to execute at uninstallation time}
                </uninstall>
                 <events>
                 <events>
                         {text to  be appended to the events script file}
                         {text to  be appended to the events script file}
Line 43: Line 52:
                         {text to be used as diff template}
                         {text to be used as diff template}
                 </tpl>
                 </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>
         </plugin>
</hfs>
</hfs>
</pre>
</pre>
==== 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 ===
=== Priorities ===
Line 52: Line 76:
* <plugin icon="">
* <plugin icon="">
* <update>
* <update>
* <options>


=== Doubts and ideas ===
=== Doubts and ideas ===
Line 57: Line 82:
: NO. this should be easily achieved by using commands inside the diff tpl itself.
: 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>.
; maybe we need a way to decide order separately for <tpl> and <events>.
; try to make plugins be also full templates


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

Latest revision as of 13:36, 17 December 2011

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.