<commit_before>#####################
Extending the Toolbar
#####################

.. versionadded:: 3.0

You can add and remove items to the toolbar. This allows you to integrate your
application in the frontend editing mode of django CMS and provide your users
with a streamlined editing experience.

For the toolbar API reference, please refer to :ref:`toolbar-api-reference`.


***********
Registering
***********

There are two ways to control what gets shown in the toolbar.

One is the :setting:`CMS_TOOLBARS`. This gives you full control over which
classes are loaded, but requires that you specify them all manually.

The other is to provide ``cms_toolbar.py`` files in your apps, which will be
automatically loaded as long :setting:`CMS_TOOLBARS` is not set (or set to
``None``).

If you use the automated way, your ``cms_toolbar.py`` file should contain
classes that extend from ``cms.toolbar_base.CMSToolbar`` and are registered using :meth:`cms.toolbar_pool.toolbar_pool.register`.
The register function can be used as a decorator.

These have four attributes:
* toolbar (the toolbar object)
* request (the current request)
* is_current_app (a flag indicating whether the current request is handled by the same app as the function is in)
* app_path (the name of the app used for the current request)

This classes must implement a ``populate`` or ``post_template_populate`` function. An optional ``request_hook`` function
is available for overwrite as well.

* The populate functions will only be called if the current user is a staff user.
* The ``populate`` function will be called before the template and plugins are rendered.
* The ``post_template_populate`` function will be called after the template is rendered.
* The ``request_hook`` function is called before the view and may return a response. This way you would be able to issue
  redirects from a toolbar if needed

A simple example, registering a class that does nothing::
<commit_msg>Add documentation for supported_apps<commit_after>#####################
Extending the Toolbar
#####################

.. versionadded:: 3.0

You can add and remove items to the toolbar. This allows you to integrate your
application in the frontend editing mode of django CMS and provide your users
with a streamlined editing experience.

For the toolbar API reference, please refer to :ref:`toolbar-api-reference`.


***********
Registering
***********

There are two ways to control what gets shown in the toolbar.

One is the :setting:`CMS_TOOLBARS`. This gives you full control over which
classes are loaded, but requires that you specify them all manually.

The other is to provide ``cms_toolbar.py`` files in your apps, which will be
automatically loaded as long :setting:`CMS_TOOLBARS` is not set (or set to
``None``).

If you use the automated way, your ``cms_toolbar.py`` file should contain
classes that extend from ``cms.toolbar_base.CMSToolbar`` and are registered using :meth:`cms.toolbar_pool.toolbar_pool.register`.
The register function can be used as a decorator.

These have four attributes:
* toolbar (the toolbar object)
* request (the current request)
* is_current_app (a flag indicating whether the current request is handled by the same app as the function is in)
* app_path (the name of the app used for the current request)

This classes must implement a ``populate`` or ``post_template_populate`` function. An optional ``request_hook`` function
is available for overwrite as well.

* The populate functions will only be called if the current user is a staff user.
* The ``populate`` function will be called before the template and plugins are rendered.
* The ``post_template_populate`` function will be called after the template is rendered.
* The ``request_hook`` function is called before the view and may return a response. This way you would be able to issue
  redirects from a toolbar if needed

This classes can define an optional ``supported_apps`` attribute to define the toolbar is local to (i.e.: for which the
``is_current_app`` attribute is set to ``True``); this is useful to define the toolbar in a different application than
the views it's related to.

A simple example, registering a class that does nothing::

{'fraction_non_alphanumeric': 0.08931116389548693, 'fraction_numerical': 0.0009501187648456057, 'mean_word_length': 4.9645892351274785, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3064384', 'n_tokens_mistral': 1086, 'n_tokens_neox': 1032, 'n_words': 593}