custom_plugins.txt

You have three options to extend Django CMS: Custom plugins, plugin context
processors, and plugin processors.

Custom Plugins
==============

Suppose you have the following gallery model::

	class Gallery(models.Model):
		name = models.CharField(max_length=30)

	class Picture(models.Model):
		gallery = models.ForeignKey(Gallery)
		image = models.ImageField(upload_to="uploads/images/")
		description = models.CharField(max_length=60)

And that you want to display this gallery between two text blocks.

You can do this with a CMS plugin. To create a CMS plugin you need two
components: a CMSPlugin model and a cms_plugins.py file.

Plugin Model
------------

First create a model that links to the gallery via a ForeignKey field::

	from cms.models import CMSPlugin

	class GalleryPlugin(CMSPlugin):
		gallery = models.ForeignKey(Gallery)

Be sure that your model inherits the CMSPlugin class.
The plugin model can have any fields it wants. They are the fields that
get displayed if you edit the plugin.

cms_plugins.py
--------------

After that create in the application folder (the same one where models.py is) a cms_plugins.py file.

In there write the following::

	from cms.plugin_base import CMSPluginBase
	from cms.plugin_pool import plugin_pool
	from models import GalleryPlugin
	from django.utils.translation import ugettext as _

	class CMSGalleryPlugin(CMSPluginBase):
		model = GalleryPlugin
		name = _("Gallery")
		render_template = "gallery/gallery.html"

		def render(self, context, instance, placeholder):
			context.update({'gallery':instance.gallery,
							'object':instance,
							'placeholder':placeholder})
			return context

	plugin_pool.register_plugin(CMSGalleryPlugin)


CMSPluginBase itself inherits from ModelAdmin so you can use all the things (inlines for example) you would
use in a regular admin class.


For a list of all the options you have on CMSPluginBase have a look at the plugin reference


Template
--------
Now create a gallery.html template in ``templates/gallery/`` and write the following in there.
::

	{% for image in gallery.picture_set.all %}
		<img src="{{ image.image.url }}" alt="{{ image.description }}" />
	{% endfor %}

Now go into the admin create a gallery and afterwards go into a page and add a gallery plugin and some
pictures should appear in your page.

Limiting Plugins per Placeholder
--------------------------------

You can limit in which placeholder certain plugins can appear. Add a ``CMS_PLACEHOLDER_CONF`` to your ``settings.py``.

Example::

	CMS_PLACEHOLDER_CONF = {
		'content': {
			"plugins": ('ContactFormPlugin','FilePlugin','FlashPlugin','LinkPlugin','PicturePlugin','TextPlugin'),
			"extra_context": {"width":940},
			"name": gettext("content")
		},

		'right-column': {
			"plugins": ('ContactFormPlugin','TextPlugin', 'SimpleGalleryPublicationPlugin'),
	        "extra_context": {"width":280},
			"name": gettext("right column")
			"limits": {
				"global": 2,
				"TeaserPlugin": 1,
				"LinkPlugin": 1,
			},
		},

"**content**" and "**right-column**" are the names of two placeholders. The plugins list are filled with
Plugin class names you find in the ``cms_plugins.py``. You can add extra context to each placeholder so
plugin-templates can react to them. In this example we give them some parameters that are used in a
CSS Grid Framework.

You can change the displayed name in the admin with the **name** parameter. In combination with gettext
you can translate this names according to the language of the user. Additionally you can limit the number
of plugins (either total or by type) for each placeholder with the **limits** parameter (see
``Configuration`` for details).


Advanced
--------

CMSGalleryPlugin can be even further customized:

Because CMSPluginBase extends ModelAdmin from django.contrib.admin you can use all the things you are used
to with normal admin classes. You can defined inlines, the form, the form template etc.

Note: If you want to overwrite the form be sure to extend from ``admin/cms/page/plugin_change_form.html``
to have an unified look across the plugins and to have the preview functionality automatically installed.


Plugin Context Processors
-------------------------

Plugin context processors are callables that modify all plugin's context before rendering. They are enabled
using the ``CMS_PLUGIN_CONTEXT_PROCESSORS`` setting.

A plugin context processor takes 2 arguments:

**instance**:

The instance of the plugin model

**placeholder**:

The instance of the placeholder this plugin appears in.

The return value should be a dictionary containing any variables to be added to the context.

Example::

    # settings.py:
    CMS_PLUGIN_CONTEXT_PROCESSORS = (
        'yourapp.cms_plugin_context_processors.add_verbose_name',
    )

    # yourapp.cms_plugin_context_processors.py:
    def add_verbose_name(instance, placeholder):
        '''
        This plugin context processor adds the plugin model's verbose_name to context.
        '''
        return {'verbose_name': instance._meta.verbose_name}

Plugin Processors
-----------------

Plugin processors are callables that modify all plugin's output after rendering. They are enabled using
the ``CMS_PLUGIN_PROCESSORS`` setting.

A plugin processor takes 4 arguments:

**instance**:

The instance of the plugin model

**placeholder**:

The instance of the placeholder this plugin appears in.

**rendered_content**:

A string containing the rendered content of the plugin.

**original_context**:

The original context for the template used to render the plugin.

Note that plugin processors are also applied to plugins embedded in Text. Depending on what your processor
does, this might break the output. For example, if your processor wraps the output in a DIV tag, you might
end up having DIVs inside of P tags, which is invalid. You can prevent such cases by returning
`rendered_content` unchanged if `instance._render_meta.text_enabled` is True, which is the case when
rendering an embedded plugin.

Example:

Suppose you want to put wrap each plugin in the main placeholder in a colored box, but it would be too
complicated to edit each individual plugin's template:

In your settings.py::

    CMS_PLUGIN_PROCESSORS = (
        'yourapp.cms_plugin_processors.wrap_in_colored_box',
    )

In your yourapp.cms_plugin_processors.py::

    def wrap_in_colored_box(instance, placeholder, rendered_content, original_context):
        '''
        This plugin processor wraps each plugin's output in a colored box if it is in the "main" placeholder.
        '''
        if placeholder.slot != 'main' \                   # Plugins not in the main placeholder should remain unchanged
            or instance._render_meta.text_enabled:   # Plugins embedded in Text should remain unchanged in order not to break output
                return rendered_content
        else:
            from django.template import Context, Template
            # For simplicity's sake, construct the template from a string:
            t = Template('<div style="border: 10px {{ border_color }} solid; background: {{ background_color }};">{{ content|safe }}</div>')
            # Prepare that template's context:
            c = Context({
                'content': rendered_content,
                # Some plugin models might allow you to customize the colors,
                # for others, use default colors:
                'background_color': instance.background_color if hasattr(instance, 'background_color') else 'lightyellow',
                'border_color': instance.border_color if hasattr(instance, 'border_color') else 'lightblue',
            })
            # Finally, render the content through that template, and return the output
            return t.render(c)