Skip to content
Permalink
Browse files

Improved plugins documentation

  • Loading branch information
evildmp committed Mar 13, 2020
1 parent da1aacf commit 7dad3719139b0970f3f559941a6e04118898e59b
Showing with 135 additions and 130 deletions.
  1. +2 −129 docs/how_to/custom_plugins.rst
  2. +1 −1 docs/index.rst
  3. +1 −0 docs/topics/index.rst
  4. +131 −0 docs/topics/plugins.rst
@@ -4,139 +4,12 @@
How to create Plugins
#####################

CMS Plugins are reusable content publishers that can be inserted into django
CMS pages (or indeed into any content that uses django CMS placeholders). They
enable the publishing of information automatically, without further
intervention.

This means that your published web content, whatever it is, is kept
up-to-date at all times.

It's like magic, but quicker.

Unless you're lucky enough to discover that your needs can be met by the
built-in plugins, or by the many available third-party plugins, you'll have to
write your own custom CMS Plugin. Don't worry though - writing a CMS Plugin is
very straightforward.


*************************************
Why would you need to write a plugin?
*************************************

A plugin is the most convenient way to integrate content from another Django
app into a django CMS page.

For example, suppose you're developing a site for a record company in django
CMS. You might like to have a "Latest releases" box on your site's home page.

Of course, you could every so often edit that page and update the information.
However, a sensible record company will manage its catalogue in Django too,
which means Django already knows what this week's new releases are.

This is an excellent opportunity to make use of that information to make your
life easier - all you need to do is create a django CMS plugin that you can
insert into your home page, and leave it to do the work of publishing information
about the latest releases for you.

Plugins are **reusable**. Perhaps your record company is producing a series of
reissues of seminal Swiss punk records; on your site's page about the series,
you could insert the same plugin, configured a little differently, that will
publish information about recent new releases in that series.

********
Overview
********

A django CMS plugin is fundamentally composed of three things.

* a plugin **editor**, to configure a plugin each time it is deployed
* a plugin **publisher**, to do the automated work of deciding what to publish
* a plugin **template**, to render the information into a web page

These correspond to the familiar Model-View-Template scheme:

* the plugin **model** to store its configuration
* the plugin **view** that works out what needs to be displayed
* the plugin **template** to render the information

And so to build your plugin, you'll make it from:

* a sub-class of :class:`cms.models.pluginmodel.CMSPlugin` to
**store the configuration** for your plugin instances
* a sub-class of :class:`cms.plugin_base.CMSPluginBase` that **defines
the operating logic** of your plugin
* a template that **renders your plugin**

A note about :class:`cms.plugin_base.CMSPluginBase`
===================================================

:class:`cms.plugin_base.CMSPluginBase` is actually a sub-class of
:class:`django:django.contrib.admin.ModelAdmin`.

Because :class:`~cms.plugin_base.CMSPluginBase` sub-classes ``ModelAdmin`` several important
``ModelAdmin`` options are also available to CMS plugin developers. These
options are often used:

* ``exclude``
* ``fields``
* ``fieldsets``
* ``form``
* ``formfield_overrides``
* ``inlines``
* ``radio_fields``
* ``raw_id_fields``
* ``readonly_fields``

Please note, however, that not all ``ModelAdmin`` options are effective in a CMS
plugin. In particular, any options that are used exclusively by the
``ModelAdmin``'s ``changelist`` will have no effect. These and other notable options
that are ignored by the CMS are:

* ``actions``
* ``actions_on_top``
* ``actions_on_bottom``
* ``actions_selection_counter``
* ``date_hierarchy``
* ``list_display``
* ``list_display_links``
* ``list_editable``
* ``list_filter``
* ``list_max_show_all``
* ``list_per_page``
* ``ordering``
* ``paginator``
* ``prepopulated_fields``
* ``preserve_fields``
* ``save_as``
* ``save_on_top``
* ``search_fields``
* ``show_full_result_count``
* ``view_on_site``


An aside on models and configuration
====================================

The plugin **model**, the sub-class of :class:`cms.models.pluginmodel.CMSPlugin`,
is actually optional.

You could have a plugin that doesn't need to be configured, because it only
ever does one thing.

For example, you could have a plugin that only publishes information
about the top-selling record of the past seven days. Obviously, this wouldn't
be very flexible - you wouldn't be able to use the same plugin for the
best-selling release of the last *month* instead.

Usually, you find that it is useful to be able to configure your plugin, and this
will require a model.


*******************
The simplest plugin
*******************

We'll start with an example of a very simple plugin.

You may use ``python manage.py startapp`` to set up the basic layout for your
plugin app (remember to add your plugin to ``INSTALLED_APPS``). Alternatively, just add a file called ``cms_plugins.py`` to an
existing Django application.
@@ -180,8 +180,8 @@ project.

introduction/index
how_to/index
topics/index
reference/index
topics/index
contributing/index
upgrade/index
user/index
@@ -11,6 +11,7 @@ concerned with explaining *how to do things* than with helping you understand
.. toctree::
:maxdepth: 1

plugins
apphooks
publishing
multiple_languages
@@ -0,0 +1,131 @@
.. _plugins:

#####################
Plugins
#####################


.. seealso::

* :ref:`Plugins how-to guide <custom-plugins>`

CMS Plugins are reusable content publishers that can be inserted into django
CMS pages (or indeed into any content that uses django CMS placeholders). They
enable the publishing of information automatically, without further
intervention.

This means that your published web content, whatever it is, is kept
up-to-date at all times.

It's like magic, but quicker.

Unless you're lucky enough to discover that your needs can be met by the
built-in plugins, or by the many available third-party plugins, you'll have to
write your own custom CMS Plugin.


***************************************
*Why* would you need to write a plugin?
***************************************

A plugin is the most convenient way to integrate content from another Django
application into a django CMS page.

For example, suppose you're developing a site for a record company in django
CMS. You might like to have a "Latest releases" box on your site's home page.

Of course, you could every so often edit that page and update the information.
However, a sensible record company will manage its catalogue in Django too,
which means Django already knows what this week's new releases are.

This is an excellent opportunity to make use of that information to make your
life easier - all you need to do is create a django CMS plugin that you can
insert into your home page, and leave it to do the work of publishing information
about the latest releases for you.

Plugins are **reusable**. Perhaps your record company is producing a series of
reissues of seminal Swiss punk records; on your site's page about the series,
you could insert the same plugin, configured a little differently, that will
publish information about recent new releases in that series.


************************
Components of a plugin
************************

A django CMS plugin is fundamentally composed of three components, that correspond to Django's
familiar Model-View-Template scheme:

=================== ================================ ========================================================
What Function Subclass of
=================== ================================ ========================================================
model (if required) plugin instance configuration :class:`CMSPlugin <cms.models.pluginmodel.CMSPlugin>`
view display logic :class:`CMSPluginBase <cms.plugin_base.CMSPluginBase>`
template rendering --
=================== ================================ ========================================================


:class:`CMSPluginBase <cms.plugin_base.CMSPluginBase>`
======================================================

The plugin **model**, the sub-class of :class:`cms.models.pluginmodel.CMSPlugin`,
is optional.

You could have a plugin that doesn't need to be configured, because it only
ever does one thing.

For example, you could have a plugin that only publishes information
about the top-selling record of the past seven days. Obviously, this wouldn't
be very flexible - you wouldn't be able to use the same plugin for the
best-selling release of the last *month* instead.

Usually, you find that it is useful to be able to configure your plugin, and this
will require a model.


:class:`CMSPlugin <cms.models.pluginmodel.CMSPlugin>`
==================================================================

:class:`cms.plugin_base.CMSPluginBase` is actually a sub-class of
:class:`django:django.contrib.admin.ModelAdmin`.

Because :class:`~cms.plugin_base.CMSPluginBase` sub-classes ``ModelAdmin`` several important
``ModelAdmin`` options are also available to CMS plugin developers. These
options are often used:

* ``exclude``
* ``fields``
* ``fieldsets``
* ``form``
* ``formfield_overrides``
* ``inlines``
* ``radio_fields``
* ``raw_id_fields``
* ``readonly_fields``

Please note, however, that not all ``ModelAdmin`` options are effective in a CMS
plugin. In particular, any options that are used exclusively by the
``ModelAdmin``'s ``changelist`` will have no effect. These and other notable options
that are ignored by the CMS are:

* ``actions``
* ``actions_on_top``
* ``actions_on_bottom``
* ``actions_selection_counter``
* ``date_hierarchy``
* ``list_display``
* ``list_display_links``
* ``list_editable``
* ``list_filter``
* ``list_max_show_all``
* ``list_per_page``
* ``ordering``
* ``paginator``
* ``prepopulated_fields``
* ``preserve_fields``
* ``save_as``
* ``save_on_top``
* ``search_fields``
* ``show_full_result_count``
* ``view_on_site``

0 comments on commit 7dad371

Please sign in to comment.
You can’t perform that action at this time.