Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Added documentation to both docstrings and the proper manual, hopeful…
…ly closing #647
  • Loading branch information
chrisglass committed Jan 16, 2011
1 parent 6e60864 commit ef1cfa0
Show file tree
Hide file tree
Showing 2 changed files with 15 additions and 2 deletions.
11 changes: 11 additions & 0 deletions cms/models/pluginmodel.py
Expand Up @@ -42,6 +42,17 @@ def __new__(cls, name, bases, attrs):


class CMSPlugin(Mptt):
'''
The base class for a CMS plugin model. When defining a new custom plugin, you should
store plugin-instance specific information on a subclass of this class.
An example for this would be to store the number of pictures to display in a galery.
Two restrictions apply when subclassing this to use in your own models:
1. Subclasses of CMSPlugin *cannot be further subclassed*
2. Subclasses of CMSPlugin cannot define a "text" field.
'''
__metaclass__ = PluginModelBase

placeholder = models.ForeignKey(Placeholder, editable=False, null=True)
Expand Down
6 changes: 4 additions & 2 deletions docs/extending_cms/custom_plugins.rst
Expand Up @@ -72,9 +72,11 @@ Now models.py looks like the following::
gallery = models.ForeignKey(Gallery)


.. note::
.. warning::

Unfortunately `CMSPlugin` subclasses cannot be further subclassed.
Two limitations apply when subclassing the `CMSPlugin` class to use with
your custom plugins: the resulting subclass cannot be further subclassed,
and subclasses of `CMSPlugin` cannot have a field called "text".

This comment has been minimized.

Copy link
@beniwohli

beniwohli Jan 16, 2011

Contributor

This doesn't only apply to text, but also link, file, picture, video, and more, depending on which plugins are activated in the settings. The source of the problem is that inheritance in Django uses OneToOneFields which in turn automatically generate accessors for the reverse relation on the base class. And these reverse relation accessors are of course inherited by all the plugins.

It's possible to suppress the automatic generation of the reverse accessors (see http://docs.djangoproject.com/en/dev/ref/models/fields/#django.db.models.ForeignKey.related_name), but I don't know if it's possible to do this for the implicit OneToOneField generated by inheritance, or if it's even desirable.

This comment has been minimized.

Copy link
@chrisglass

chrisglass Jan 16, 2011

Author Contributor

Thanks, I'll create a bug for your notes and update the docs with your added insight.

This comment has been minimized.

Copy link
@ojii

ojii Jan 16, 2011

Contributor

We should probably try to rename the reverse ('cmsplugin_'?) and also have our metaclass validate the plugin so we can give better error messages. However this can (and probably should, since it'll be quite a chunk of code) happen after 2.1 is out (maybe in 2.1.1).




Expand Down

0 comments on commit ef1cfa0

Please sign in to comment.