release v0.3.2

v0.3.2/plugins/plugin-interface.txt

@@ -0,0 +1,73 @@
+The following directory structure is required:
+	- python code: plugins/PLUGINNAME/PLUGINNAME.py (all lower case is recommended)
+	- language file: plugins/PLUGINNAME/language.hdf
+	- clearsilver templates: plugins/PLUGINNAME/*.cs
+	- icon (128x128px recommended): plugins/PLUGINNAME/plugin_icon.png
+	- css stylesheets (optional): plugins/PLUGINNAME/PLUGINNAME.css
+
+
+Python code interface:
+	- create a class with the same name as the plugin - it must inherit CryptoBoxPlugin
+	- function "do_action":
+		- this function will get called whenever this plugins is involved in a request
+		- all arguments should be optional (e.g. for displaying a form without previous input values)
+		- the argument "store" should be used to process a form submission (just a recommendation)
+		- if the processing failed for some reason (invalid input, ...), it should manually set
+		  "Data.Warning" or "Data.Success") to a value of your choice (preferably
+		  you may want to use messages of the namespace of your plugin
+		  (e.g. "Data.Plugins.PLUGINNAME.WarningMessage.InvalidInput"))
+		- the return value should be the name of the template that should be displayed after processing
+		  (a template file in the plugin directory takes precedence over global template files)
+			- the return value may also be a dictionary with the following elements:
+				* template: the name of the template file (mandatory)
+				* generator: a generator object ("yield") - its content will replace every
+				  occurrence of "<!-- CONTENT_DUMMY -->" in the template (useful for pages that
+				  are displayed step by step (as for formatting of filesystems))
+			- the return value may also be a dictionary with the following elements:
+				* plugin: the name of a plugin
+				* values: a dictionary of variables that should be defined for this plugin
+			- an empty (e.g. None) return value can be used to go to the default page ("disks"
+			  or "volume_mount" (for volume plugins))
+	- function "get_status":
+		- returns a string, that describes a state connected to this plugin (e.g. the current date and
+		  time (for the "date" plugin))
+	- function "handle_event(event, event_info)":
+		- may be overridden to specify event handling (e.g. "bootup", "shutdown")
+		- see src/cryptobox/plugins/base.py for details
+	- the class variable "plugin_capabilities" must be an array of strings (supported: "system" and
+	  "volume")
+	- the class variable "plugin_visibility" may contain one or more of the following items:
+	  menu/preferences/volume. This should fit to the 'plugin_capabilities' variable.
+	  An empty list is interpreted as an invisible plugin.
+	- the class variable "request_auth" is boolean and defines, if admin authentication is necessary
+	  for this plugin
+	- the class variable "rank" is an integer in the range of 0..100 - it determines the order
+	  of plugins in listings (lower value -> higher priority)
+	- volume plugins contain the attribute "device" (you may trust this value - a volume plugin will
+	  never get called with an invalid device)
+	- the python module which contains the plugin's class should also contain a class called
+	  'unittests' - it should inherit WebInterfaceTestClass.WebInterfaceTestClass
+
+
+Language file structure:
+	- the content of the language file will be added to the hdf dataset below "Lang.Plugins.PLUGINNAME"
+	  (this avoids namespace conflicts)
+	- the following top level settings _must_ be defined:
+		Name (a short description)
+		Link (the visible text for links to this plugin)
+	- all warnings, hints and success messages should be stored below WarningMessage.???
+	  (resp. AdviceMessage or SuccessMessage)
+
+
+Clearsilver template:
+	- heading:
+		- non-volume plugins: "<h1>" 
+		- volume plugins: "<?cs var:plugin_heading ?>" (very important - otherwise
+		  embedding of plugins breaks (see 'volume_properties'))
+	- the title should be followd by '<?cs call:handle_messages() ?>'
+	- usually you should supply some helpful information afterwards (only displayed
+	  if the user enabled inline-help before):
+	  	"<?cs call:show_help(Lang.Plugins.PLUGINNAME.Help.Text) ?>"
+	- links to the plugin (e.g. in form headers) could look like the following:
+		<?cs call:link("PLUGINNAME",'','','','') ?>
+