Plugins¶
Contents:
Getting started¶
Things you should know:
- Each plugin is a subclass one of the plugin types.
- A .py file can contain multiple plugins.
- If you have a folder structure the main foler must be a python module.
Plugins are loaded dynamically by traversing the core plugin path and the extraPluginPath, each .py file is checked for any of the plugin type classes.
Basic folderstructure:
<extraPluginFolder>-+
|
+-<My Plugin Folder>-+
|
+- __init__.py (empty file)
|
+- <My Plugin .py>
|
+- <more .py that the plugin needs> (optional)
|
+- <folder with libarys> (optional)
|
+- pluginRootLibarys (optional)
Note
Not all .py files are checked. Files that start with ‘__’ or files that are in a folder called pluginRootLibarys are not checked for plugins.
A simple notification plugin¶
The file structure for this would look like:
<extraPluginFolder>-+
|
+-Printer-+
|
+- __init__.py
|
+- Printer.py
Contents of printer.py
:
from xdm.plugins import * # by using this one import line you have everything a plugin will need from XDM
class Printer(Notifier): # subclass Notifier
def sendMessage(msg, element=None)
print msg
return True
This is absolutely sufficient for a Notifier plugin.
Adding configuration¶
To create settings simply fill the _config attribute of your plugin class:
from xdm.plugins import * # by using this one import line you have everything a plugin will need from XDM
class Printer(Notifier): # subclass Notifier
_config = {'add_message': 'my print plugin'}
def sendMessage(msg, element=None)
print msg
return True
This will create a text field in on the settings page and the default value is my print plugin.
Each type of default value will determine the input field in the settings
str: | Text input field |
---|---|
bool: | Checkbox |
int / float: | Number input field |
Note
Only these type are allowed as config values!
To get the config value access the c
object of you plugin and then the attribute with the name of your config.
from xdm.plugins import *
class Printer(Notifier):
_config = {'add_message': 'my print plugin'}
def sendMessage(msg, element=None)
userAddition = self.c.add_message # just make sure its the same spelling as the key in the config
print msg + userAddition
return True
Note
self.c
is only available after the __init__() of Plugin.
It was never explained how the add_message is used, to change that we use the config_meta
attribute.
from xdm.plugins import *
class Printer(Notifier):
_config = {'add_message': 'my print plugin'}
# add_message: same key as in _config
config_meta = {'add_message': {'human': 'Additional text', # a more human friendly name
'desc': 'This text will be added after every printed message'}}
# the description will be a tooltip on the input field
def sendMessage(msg, element=None)
userAddition = self.c.add_message
print msg + userAddition
return True
More info on Plugin configuration
Reserved attributes¶
Following class / instance attributes are reserved and are not to be set by a plugin!
- c
- The configuration manager
- hc
- The hidden configuration manager
- type
- The class name e.g. Printer
- _type
- Its the plugin type name e.g. Downloader
- instance
- The instance name
- name
- The class name and instance name e.g. Printer (Default)
More info see Plugin
Plugin Types¶
- DownloadType
- A simple description of a download type.
- Downloader
- These plugins provider the connection to the downloader programs
- Indexer
- These plugins provide connection to the sites that have information on releases
- Notifier
- These plugins provide means to send notification to third party services or other program’s on certain events
- Provider
- These plugins connect to databases and create elements based on the media type they work for.
- PostProcessor
- These plugins move rename or do whatever they like with a given path and element.
- System
- Well there is only one of this kind and maybe there will never be more. The system config is a plugin of this type
- DownloadFilter
- These plugins can filter found downloads as they wish.
- SearchTermFilter
- These plugins can add or remove search terms, before they are used by the Provider
- MediaAdder
- These plugins can add elements. From various sources e.g. Trakt.tv watchlist.
- MediaTypeManager
- These plugins are the core of XDM. These plugins define the structure of a media type and provide functions to save and store them. The look is also defined here.
PluginRootLibarys¶
If you need to include a library that expects to by installed system wide, therefore being in the python path can be used when put in a folder called pluginRootLibarys. The absolute path of that folder is added to the python path.
Note
An info level message when the path is added it created.
Plugin¶
-
class
xdm.plugins.bases.
Plugin
(instance=None)¶ Plugin base class. loads the config on init
-
_getUseConfigsForElementsAsWrapper
(element)¶ Gets the the config value for given element
-
addMediaTypeOptions
= True¶ Defines if options defined by a MediaType should be added to the plugin.
Note
This is ignored for plugins of the type MediaTypeManager and System since it’s never done for them.
- bool
True
: this will add all configurations defined by a MediaTypeFalse
: No configurations are added
- list
- a list of MediaType identifiers e.g.
['de.lad1337.music', 'de.lad1337.games']
, this will add only options from the MediaType with the given identifier - str
- only str value allowed is
runFor
, this will only add runFor options to the plugin.
-
config_meta
= {}¶ Meta information on the the config keys
-
getConfigHtml
()¶ The return value of this function is simply injected in the config panel
default is a html comment: <!– nothing here –> you can use this to add dynamic javascript and/or add additional html
Note
The container this is added in is hidden with inline css. to make use of the html use javascript
-
single
= False¶ if True the gui will not give the option for more configurations. but there is no logic to stop you do it anyways
-
useConfigsForElementsAs
= 'Category'¶ MediaTypeManager can add configurations for elements. this defines how this configuration is used. This string will be used for:
- It will be added to the configurations name.
- A function will be created named
get<useConfigsForElementsAs_value>()
e.g. getCategory()
-
version
= '0.1'¶ version string. may only have a major and a minor version number
-
xdm_version
= (0, 0, 0)¶ this is the greater or equal XDM version this plugin needs to function
Note
By default this is (0, 0, 0) but the json builder will return the current version of XDM if it is not specifically set.
-