added mixin definitions

docs/extend/plugins.md

@@ -6,7 +6,7 @@ title: Plugins
 
 The InvenTree server code supports an extensible plugin architecture, allowing custom plugins to be integrated directly into the database server. This allows development of complex behaviours which are decoupled from core InvenTree code.
 
-InvenTree builtin plugins are located in the directory `./InvenTree/plugin/builtin`.  
+InvenTree built-in plugins are located in the directory `./InvenTree/plugin/builtin`.  
 Custom plugins should be placed  in the directory `./InvenTree/plugins`.
 
 Plugins are discovered and loaded when the server is started.
@@ -26,7 +26,7 @@ InvenTree supports decoding of arbitrary barcode data via a **Barcode Plugin** i
 
 InvenTree can generate native QR codes to represent database objects (e.g. a single StockItem). This barcode can then be used to perform quick lookup of a stock item or location in the database. A client application (for example the InvenTree mobile app) scans a barcode, and sends the barcode data to the InvenTree server. The server then uses the **InvenTreeBarcodePlugin** (found at `/InvenTree/plugins/barcode/inventree.py`) to decode the supplied barcode data.
 
-Any third-party barcodes can be decoded by writing a matching plugin to decode the barcode data. These plugins could then perform a server-side action, or render a JSON response back to the client for further action.
+Any third-party barcodes can be decoded by writing a matching plugin to decode the barcode data. These plugins could then perform a server-side action or render a JSON response back to the client for further action.
 
 Some examples of possible uses for barcode integration:
 
@@ -61,16 +61,107 @@ For an example of a very simple action plugin, refer to `/InvenTree/plugin/built
 
 Integration Plugins provide a wide area of deep integration into the interface of InvenTree.
 
+For an example of a pretty much full Integration Plugin, refer to `/InvenTree/plugin/samples/integration/sample.py`
+
+#### Plugin Options
+
+Some metadata options can be defined as constants in the plugins class.
+
+python
+```
+PLUGIN_SLUG = None  # Used in URLs, setting-names etc. when a unique slug as a reference is needed -> the plugin name is used if not set
+PLUGIN_TITLE = None  # A nice human friendly name for the plugin -> used in titles, as plugin name etc.
+
+AUTHOR = None  # Author of the plugin, git commit information is used if not present
+PUBLISH_DATE = None  # Publishing date of the plugin, git commit information is used if not present
+VERSION = None  # Version of the plugin
+WEBSITE = None  # Website for the plugin, developer etc. -> is shown in plugin overview if set
+```
+
+
 #### Mixins
 
-Common usecases are covered by pre-supplied modules in the form of Mixins (similar to how (https://docs.djangoproject.com/en/3.2/topics/class-based-views/mixins/)[django] does it).
+Common use cases are covered by pre-supplied modules in the form of mixins (similar to how (https://docs.djangoproject.com/en/3.2/topics/class-based-views/mixins/)[django] does it). Each mixin enables the integration into a specific area of InvenTree. Sometimes it also enhances the plugin with helper functions to supply often used functions out-of-the-box.
 
-##### SettingsMixin
+##### Basic Mixin Functions
 
-##### UrlsMixin
+All mixins are registered with the plugin on start-up so you can access all added mixins as a dict with the `plugin.registered_mixins` property that is added to each plugin.
 
-##### NavigationMixin
+The function `plugin.mixin_enabled(key)` returns if a mixin is present in a plugin and configured correctly.
 
-##### AppMixin
+##### Initialisation
 
-For an example of a pretty much full Integration Plugin, refer to `/InvenTree/plugin/samples/integration/sample.py`
+Each mixin must call `super().__init__()` in it's `__init__` function and register itself with a call to `self.add_mixin()`. Check out the built-in mixins for examples.
+
+python
+```
+def __init__(self):
+    super().__init__()
+    self.add_mixin('settings', 'has_settings', __class__)
+```
+
+##### Meta Options
+
+Each mixin can define additional options as a Meta subclass. These are used to describe the mixin.
+
+
+#### SettingsMixin
+
+Use the class constant `SETTINGS` for a dict of settings that should be added as global database settings.  
+The dict must be formatted similar to the following sample. Take a look at the settings defined in `InvenTree.common.models.InvenTreeSetting` for all possible parameters.
+
+
+```
+SETTINGS = {
+    'PO_FUNCTION_ENABLE': {
+        'name': _('Enable PO'),
+        'description': _('Enable PO functionality in InvenTree interface'),
+        'default': True,
+        'validator': bool,
+    },
+}
+```
+
+!!! note "Use carefully"
+    All global and user settings are exposed to the frontend code and can be read out via the browsers developer tools. You can protect a setting from export by adding `'protected': True` to sensitive settings.
+    You can access settings in frontend JS code under the global variable `global_settings`.
+
+This mixin defines the helper functions `plugin.get_setting` and `plugin.set_seting` to access all plugin specific settings.
+
+
+#### UrlsMixin
+
+Use the class constant `URLS` for a array of URLs that should be added to InvenTrees URL paths or override the `plugin.setup_urls` function.  
+The array has to contain valid URL patterns as defined in the (https://docs.djangoproject.com/en/3.2/topics/http/urls/)[django documentation].
+
+python
+```
+URLS = [
+    url(r'increase/(?P<location>\d+)/(?P<pk>\d+)/', self.view_increase, name='increase-level'),
+]
+```
+
+The URLs get exposed under `/plugin/{plugin.slug}/*` and get exposed to the template engine with the prefix `plugin:{plugin.slug}:` (for usage with the (https://docs.djangoproject.com/en/3.2/ref/templates/builtins/#url)[url tag]).
+
+
+#### NavigationMixin
+
+Use the class constant `NAVIGATION` for a array of links that should be added to InvenTrees navigation header.  
+The array must contain at least one dict that at least define a name and a link for each element. The link must be formatted for a URL pattern name lookup - links to external sites are not possible directly. The optional icon must be a class reference to an icon (InvenTree ships with fontawesome 4 by default).
+
+python
+```
+NAVIGATION = [
+    {'name': 'SampleIntegration', 'link': 'plugin:sample:hi', 'icon': 'fas fa-box'},
+]
+```
+
+The optional class constants `NAVIGATION_TAB_NAME` and `NAVIGATION_TAB_ICON` can be used to change the name and icon for the parent navigation node.
+
+
+#### AppMixin
+
+If this mixin is added to a plugin the directory the plugin class is defined in is added to InvenTrees `INSTALLED_APPS`.
+
+!!! warning "Danger Zone"
+    Only use this plugin if you have an understanding of djangos (https://docs.djangoproject.com/en/3.2/ref/applications/)[app system]. Plugins with this mixin are deeply integrated into InvenTree and can cause difficult to reproduce or long-running errors. Use the built-in testing functions of django to make sure your code does not cause unwanted behaviour in InvenTree.