Merge branch 'bug_538_ignore_global_actions_in_standby'

[enigma2.git] / doc / PLUGINS

diff --git a/doc/PLUGINS b/doc/PLUGINS
index c383997ea5e5601fd3df1e058347b340e2a75309..c397e09c83dc3f02a85b8d1cbadba5a49c847cf1 100644 (file)
--- a/doc/PLUGINS
+++ b/doc/PLUGINS
@@ -26,8 +26,8 @@ def Plugins(**kwargs):
                fnc=main)"
 
 Basically, you're writing a "python module", which is called
                fnc=main)"
 
 Basically, you're writing a "python module", which is called

-Plugins.ourSmallTest.plugin. This corresponds to the
-Plugins/ourSmallTest/plugin.py file.
+Plugins.DemoPlugins.OurSmallTest.plugin. This corresponds to the
+Plugins/DemoPlugins/OurSmallTest/plugin.py file.

 
 This module must define a single function called "Plugins". The functions is
 called for every Plugin, and should return (a list of)
 
 This module must define a single function called "Plugins". The functions is
 called for every Plugin, and should return (a list of)


@@ -76,6 +76,27 @@ stands for "keyword arguments") collects all addition keyword arguments
 parameter, and probably more in the future. You must ignore all additional
 keywords which you don't need!
 
 parameter, and probably more in the future. You must ignore all additional
 keywords which you don't need!
 

+skins
+=====
+
+Generally, you can include the skin in your Screens by having a static (or
+non-static, if you really want) variable "skin", for example:
+
+class OurSmallTestScreen(Screen):
+       skin = "<skin>...</skin>"
+       def __init__(self, session):
+               Screen.__init__(self, session)
+               ...
+
+However, users can override the skin from their skin.xml. Note that the
+Screen's name (unless you override this, which is possible) is used for
+determining which skin is used. Thus, if you're choosing generic skin names
+like "TheScreen", it's likely to cause namespace clashes.
+
+Thus, please use skin names (i.e. Screen-names, unless you're overriding the
+skin name) which are unique enough to not clash. In doubt, prepend the
+pluginname like in our example.
+

 autostarting plugins
 ====================
 
 autostarting plugins
 ====================
 


@@ -91,6 +112,31 @@ def autostartEntry(raeson, **kwargs):
        elif reason == 1:
                print "shutdown"
 
        elif reason == 1:
                print "shutdown"
 

+autostart plugins should always be configurable, and should default to an
+OFF state!
+
+Configuration
+=============
+
+Speaking about configuration, plugins must live in 
+
+config.plugins.<PluginName>
+
+and nowhere else!
+
+You are, however, free to change settings which are already existing. If you
+
+Dependencies
+============
+
+Plugin dependencies (one plugin requires another plugin) should generally be
+avoided, but are possible. If there are dependencies, the .ipk file must
+list them.
+
+If possible, make them optional. If your plugin doesn't support one feature
+because another plugin isn't installed, that's fine (but should be noted in
+the docs).
+

 Categories
 ==========
 
 Categories
 ==========
 


@@ -99,3 +145,17 @@ Currently defined categories are:
 * DemoPlugins: Plugins fore pure demonstration purposes
 * Extensions: User interface extensions
 * SystemPlugins: Hardware specific plugins
 * DemoPlugins: Plugins fore pure demonstration purposes
 * Extensions: User interface extensions
 * SystemPlugins: Hardware specific plugins

+
+Plugin Names
+============
+
+A plugin name:
+ - should always start with a Uppercase letter,
+ - must not start with the word "Dream",
+ - nor end with "Plugin",
+ - should be unique even across Categories,
+ - must be understandable by english speaking people,
+   (unless it's a geographically restricted plugin)
+ - is not user changeable (that is, the user is not allowed to rename the
+   plugin directory)
+ - shouldn't be a generic word