Metadata-Version: 1.1
Name: django-simple-plugins
Version: 0.1.3
Summary: A simple yet powerful and configurable tool for adding plugins to your Django project.
Home-page: https://github.com/pistacchio/django-simple-plugins
Author: Gustavo Di Pietro
Author-email: pistacchio@gmail.com
License: MIT License
Description: Django Simple Plugins
        =====================
        
        Django Simple Plugins is an app for Django that provides a simple yet
        flexible system to add a plugin layer to your project. Works with Django
        1.7
        
        Installation
        ~~~~~~~~~~~~
        
        Install Django plugins with pip:
        
        .. code:: sh
        
            pip install django-simple-plugins
        
        Add 'plugins' to the list of installed apps in your ``settings.py``
        file:
        
        .. code:: python
        
            ...
            'plugins',
            ...
        
        Add a ``PLUGINS_DIR`` setting to your ``settings.py`` with the directory
        where you are going to store your plugins. For instance:
        
        .. code:: python
        
            ...
            PLUGINS_DIR = os.path.join(BASE_DIR, 'my_plugins')
            ...
        
        Add the plugins urls to your ``urls.py`` file:
        
        .. code:: python
        
            ...
            urlpatterns = patterns('',
                url(r'^admin/', include(admin.site.urls)),
                url(r'^plugins/', include('plugins.urls')),
            )
            ...
        
        Execute ``./manage.py migrate``
        
        Writing your first plugins
        ~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        As a very simple example, imagine that we want to delegate the "greet
        user" functionality to a plugin system. You want something a bit fancier
        than this:
        
        .. code:: python
        
            def greet(request):
                greeting = 'Hello ' + request.user.username
                return HttpResponse(greeting)
        
        For example, based on who the user is, you want a greeting like "Hello
        mighty Superman" or "Hello mighty, super Batman".
        
        .. code:: python
        
            import plugins
        
            def greet(request):
                adjectives = plugins.execute_plugins(type='GREETING', context={
                    'username': request.user.username
                }, initial_input=[])
                greeting = 'Hello %s %s' % (', '.join(adjectives), request.user.username)
                return HttpResponse(greeting)
        
        We want to define a series of plugins of type "GREETING" that return a
        list of adjective based on a context that provides the username.
        
        Let's write the first plugin. In the directory defined by
        ``PLUGINS_DIR`` add the file ``greeter_plugin_1.py`` with this content:
        
        .. code:: python
        
            plugin_type = 'GREETING'
            verbose_name = 'Greeting plugin 1 - Mighty'
        
            def run(options, context, input):
                if context['username'] in options['mighty_users']:
                    input += 'mighty'
        
                return input
        
        Each plugin *must* define a ``plugin_type`` and a ``run()`` function.
        They *can* define a ``verbose_name`` Each run function is pass the
        options passed by the configuration (see below), an optional context and
        an input. Since the plugins are executed in a chained fashion, the first
        plugin to be executed is passed the ``initial_input`` (in our case
        ``[]``) or ``None``. The subsequent plugins are passed the return value
        of the previous plugins.
        
        Let's write the others:
        
        .. code:: python
        
            # greeter_plugin_2.py
            plugin_type = 'GREETING'
            verbose_name = 'Greeting plugin 2 - Super'
        
            def run(options, context, input):
                if context['username'] in options['super_users']:
                    input += 'super'
        
                return input
        
        .. code:: python
        
            # greeter_plugin_3.py
            plugin_type = 'GREETING'
        
            def run(options, context, input):
                if context['username'] in options['stinky_users']:
                    input += 'stinky'
        
                return input
        
        .. code:: python
        
            # goodbye_plugin_1.py
            plugin_type = 'GOODBYE'
        
            def run(options, context, input):
                pass
        
        Visiting the admin page, we have a list of our plugins conveniently
        grouped by plugin type.
        
        .. figure:: http://i.imgur.com/fVG7WZe.png
           :alt: Screenshot 1
        
           Screenshot 1
        Three things to notice. We don't want to insult our users, so we can
        disable the third plugin and it will be skipped. If you don't provide a
        ``verbose_name``, the file name will be used (see ``greeter_plugin_3``).
        Finally, the plugins are *sortable*. You can drag them to arrange the
        order of execution. For example, If you'd like to have "super, mighly
        Batman" instead of "mighty, super batman", just drag the Super plugin
        before the other:
        
        .. figure:: http://i.imgur.com/9lcG8Eb.png
           :alt: Screenshot 2
        
           Screenshot 2
        We only have one last thing to do. As you might have noticed, we read
        some parameter from the ``options`` dictionary. In the admin interface
        you can specify a JSON string that will be passed as a dictionary to the
        plugin. For instance:
        
        .. figure:: http://i.imgur.com/8Z8x9YT.png
           :alt: Screenshot 2
        
           Screenshot 2
        
        
Platform: UNKNOWN
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
