Permalink
Browse files

Issue #6342: docs of `text_enabled`

Issue #6342: Extended the docs of `text_enabled` param for plugins
  • Loading branch information...
jeroenpeters1986 authored and evildmp committed Apr 25, 2018
1 parent 9863ecd commit a6b56a884e6ef2d51114b94a14241d75fdf3a898
Showing with 22 additions and 15 deletions.
  1. +1 −0 AUTHORS
  2. +21 −15 docs/reference/plugins.rst
@@ -255,6 +255,7 @@ Contributors (based on gitlog, 537 unique authors):
* Jens Diemer
* JensDiemer
* Jeroen Noten
* Jeroen Peters
* Jessica Tallon
* Jimmy Lam
* Johannes Bornhold
@@ -192,12 +192,19 @@ CMSPluginBase Attributes and Methods Reference
Default: ``False``
Not all plugins are usable in text plugins. If your plugin *is* usable in a text plugin:
This attribute controls whether your plugin will be usable (and rendered)
in a text plugin. When you edit a text plugin on a page, the plugin will show up in
the *CMS Plugins* dropdown and can be configured and inserted. The output will even
be previewed in the text editor.
Of course, not all plugins are usable in text plugins. Therefore the default of this
attribute is ``False``. If your plugin *is* usable in a text plugin:
* set this to ``True``
* make sure your plugin provides its own :meth:`icon_src`
* make sure your plugin provides its own :meth:`icon_alt`, this will be used as a tooltip in
the text-editor and comes in handy when you use multiple plugins in your text.
See also: :attr:`icon_src`, :attr:`icon_alt`.
See also: :meth:`icon_alt`, :meth:`icon_src`.
**Methods**
@@ -326,18 +333,16 @@ CMSPluginBase Attributes and Methods Reference
.. method:: icon_alt()
Although it is optional, authors of "text enabled" plugins should consider
overriding this function as well.
By default :meth:`icon_alt` will return a string of the form: "[plugin type] -
[instance]", but can be modified to return anything you like.
This function accepts the ``instance`` as a parameter and returns a string to be
used as the ``alt`` text for the plugin's icon which will appear as a tooltip in
most browsers. This is useful, because if the same plugin is used multiple
times within the same text plugin, they will typically all render with the
same icon rendering them visually identical to one another. This ``alt`` text and
related tooltip will help the operator distinguish one from the others.
used as the ``alt`` text for the plugin's preview or icon.
By default :meth:`icon_alt` will return a string of the form: "[plugin type] -
[instance]", but can be modified to return anything you like.
Authors of text-enabled plugins should consider overriding this function as
it will be rendered as a tooltip in most browser. This is useful, because if
the same plugin is used multiple times, this tooltip can provide information about
its configuration.
:meth:`icon_alt` takes 1 argument:
@@ -348,7 +353,7 @@ CMSPluginBase Attributes and Methods Reference
def icon_alt(self, instance):
return "%s - %s" % (force_text(self.name), force_text(instance))
See also: :attr:`text_enabled`, :attr:`icon_src`.
See also: :attr:`text_enabled`, :meth:`icon_src`.
.. method:: icon_src(instance)
@@ -361,6 +366,9 @@ CMSPluginBase Attributes and Methods Reference
``True`` to return the path to an icon to display in the text of the text
plugin.
Since djangocms-text-ckeditor introduced inline previews of plugins, the icon
will not be rendered anymore.
icon_src takes 1 argument:
* ``instance``: The instance of the plugin model
@@ -388,8 +396,6 @@ CMSPluginBase Attributes and Methods Reference
:class:`django.template.Context`, which will be used as context to render the
plugin template.
.. versionadded:: 2.4
By default this method will add ``instance`` and ``placeholder`` to the
context, which means for simple plugins, there is no need to overwrite this
method.

0 comments on commit a6b56a8

Please sign in to comment.