cryptonas-branches/pythonrewrite/plugins/plugin-interface.txt

The following directory structure is required:
	- python code: plugins/PLUGINNAME/PLUGINNAME.py (all lower case is recommended)
	- language files: plugins/PLUGINNAME/lang/(en|de|??).hdf
	- clearsilver templates: plugins/PLUGINNAME/*.cs


Python code interface:
	- create a class with the same name as the plugin - it must inherit CryptoBoxPlugin
	- function "doAction":
		- 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 the
		  "Data.Warning" (resp. "Data.Error" or "Data.Success") to a value of your choice (preferably
		  you may want to use messages of your namespace (e.g. "Plugins.PLUGINNAME.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))
			- an empty (e.g. None) return value can be used to go to the default page (now: the
			  plugin overview)
	- function "getStatus":
		- returns a string, that describes a state connected to this plugin (e.g. the current date and
		  time (for the "date" plugin))
	- the class variable "pluginCapabilities" must be an array of strings (supported: "system" and
	  "volume")
	- the class variable "requestAuth" 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)
	- the class variable "enabled" is boolean and detemines the default availability of the plugin
	- volume plugins contain the attribute "device" (you may trust this value - a volume plugin will
	  never get called with an invalid device)


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 values _must_ be defined:
		Name (a short description)
		Link (the visible text for links to this plugin)
		Rank (defines the order of the plugins displayed (0..100))
	- all warnings, error and success messages should be stored below WarningMessage.???
	  (resp. ErrorMessage or SuccessMessage)


Clearsilver template:
	- should start with a "<h1>" tag (volume plugins: "h2")
	- links to the plugin (e.g. in form headers) could look like the following:
		<?cs call:link("plugins/PLUGINNAME",'','','','') ?>
	- volume plugins must include "show_volume_[header|footer]" (see examples)