moin-2.0 / docs / devel / plugins.rst

Miks Kalniņš 0835a8d 




















Miks Kalniņš 90d51b5 



























Miks Kalniņš 0835a8d 






















































































Miks Kalniņš c19fa25 

.. warning::

   Partly implemented and need more work.
   
===========
Plugins
===========

*******************
Plugin development
*******************

Creating custom plugins
=======================
The best way to create a plugin is by making a seperate Python package.

.. tip:: You can use ExamplePlugin package located in :file:`contrib` directory as a starting point.

Plugin system is besed on OO principes and uses `Python ABCs <http://docs.python.org/library/abc.html>`_ . All plugin types must implement their specific base
class provided by MoinMoin package. All base classes are currently located in :keyword:`MoinMoin.plugin` module.

Distribution / Installation / Discovery / Loading
==================================================
Plugins must be on sys.path so that they can be imported. The most convient method of distribution is creating a package.
List of plugin packages which should be loaded is stored in configuration under key ``plugins_enabled``.

Example configuration:

.. code-block:: python 

    from wikiconfig import *
    
    class LocalConfig(Config):
        plugins_enabled = [
            "ExampleMoinPlugin",
            "MoinMoin.themes.foobar",
            "MoinMoin.themes.modernized",
            "MoinMoin.storage.stores.fs",
            "MoinMoin.auth",
        ]
    MOINCFG = LocalConfig

Signals
========
.. todo:: Give more information about signals

Plugin Configuration
====================
.. todo:: Describe how configuration is handled and give some examples.

Examples
========

As of now there aren't too many examples. There is an example plugin located in :file:`contrib/ExamplePlugin`.
Also most of the plugin types have inbuilt plugins in :keyword:`MoinMoin` package itself and you can use them as reference.

**************************
Plugin system development
**************************

Notes
========

New code
------------
If possible new modules which are implemented as plugins shouldn't use wrappers as it's extra code and complexity which is not needed. Wrappers as they are used now is a simple way out of a lot of refactoring to make already written functionality into something that fits with the plugin system.

Plugin loading/config chicken-egg problem
-----------------------------------------------------
For now I'm solving it by moving some of the function calls out of config. To be it seems very logical that config doesn't call mayor app functions when it's made (util functions are fine) and those are all called when config has been parsed/initialized.

Blueprints
-------------
At the moment already defined themes have higher priority than those defined in Blueprint Plugin package. For example if blueprint tries to render "index.html" template and it has it in "BlueprintPlugin/templates/index.html" folder, it will still render the default "index.html" template found in MoinMoin template directory. I think I can "fix" it by changing theme code a bit (the render_template method which I already changed in themes plugin implementation). Another way is to simply prefix templates in Blueprint packages. Basically have to chose which have higher priority, as it is now, it makes sense considering how themes work.

Metadata
------------
Currently we have no way to read it without initializing the plugin itself. This should be fixed somehow later on.

Translations
---------------
Should be handled by plugin authors, Moin should expose helper functions and provide examples to make it easier for plugin authors.

Plugin loading
------------------
So far it works more or less like this:

 #. Admin provides list of enabled plugin packages.
 #. System loads all of these packages.
 #. System initializes all clasess which implement PluginBase, giving as parameter their config.

You can quite easily add more layers of who enables what especially if you have layered configuation.

TO-DO
====
 * Write the rest of the wrappers, not all inbuilt functionality have wrappers. Finish writting those so all already written code can be used in configuration.
 * Finish the rest of the plugin types
 * Slowly move away from wrappers around already supported classes and integrate plugin system more tightly with the core code. This requires quite a lot refactoring.
 * If new plugin types are introduced or new code "modules" which could become type of a plugin, they shouldn't use wrappers, but instead have most of the code in the plugin base class.
 * More configuraton, plugin examples are needed. Still a good reference is inbuilt plugins.
 * i18n helper functions just to make it easier for plugin authors to implement i18n. (Some examples would also help) 
 * Refactor startup code, right now the code seems very non-lineral and all over the place which means there are sometimes problems accessing things which are not initialized yet. There should be a clear pipeline of what starts after what and where.
 * Need more core plugin system tests.
 * Refactor theme code, it should be more straight forward.
 * Introduce a plugin container so you don't have to rewrite all the meta information if it stays the same accross multiple plugin types in a plugin package.
 * Add signals to the core code. Some good examples which need to be added:
   - Stores are ready (plugins can write stuff to store)
   - App has been created and can be accessed.
 * Some day we could have nice web interface for site admins to enable/disable plugins.
 * Maybe ACL helper functions for plugins, need more research.

Plugin types and other functionality
---------------------------------------------
Done:

 * Auth
 * Themes
 * Stores
 * Blueprints
 * Serialized items
    - Not tested but should be doable with most plugins, need a way to initiate the process (Could be Blueprint or Commandline Script)

On hold:

 * Items
    - Too volatile, more than one person working on them at the moment.

Not done:

 * Adding signals to moinmoin core code where it makes sense
 * Commandline Scripts
 * Other mimitype support plugins
 * Converters/macros
 * Other implementation of groups/dicts/etc. (low priority)
    - Need more info
 * Backend (low priority)
 * Notifications (low priority)
 
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.