Как расширить панель инструментов¶

Создайте файл cms_toolbars.py¶

Для того чтобы взаимодействовать с API панели инструментов, необходимо создать подкласс CMSToolbar в собственном коде и зарегистрировать его.

Этот класс должен быть создан в файле cms_toolbars.py вашего приложения, где он будет обнаружен автоматически при запуске Django runserver.

Вы также можете использовать CMS_TOOLBARS для управления тем, какие классы панели инструментов загружаются.

toolbar = request.toolbar
toolbar.add_modal_button('Do not touch', dangerous_button_url)

Определите и зарегистрируйте подкласс CMSToolbar¶

from cms.toolbar_base import CMSToolbar
from cms.toolbar_pool import toolbar_pool

class MyToolbarClass(CMSToolbar):
    [...]

toolbar_pool.register(MyToolbarClass)

Метод cms.toolbar_pool.ToolbarPool.register также может быть использован в качестве декоратора:

@toolbar_pool.register
class MyToolbarClass(CMSToolbar):
    [...]

Наполнение панели инструментов¶

Для управления тем, что будет отображаться на панели инструментов django CMS, доступны два метода:

• populate(), который вызывается до того, как будет отрисована остальная часть страницы

• post_template_populate(), который вызывается после отрисовки шаблона страницы

Последний метод позволяет управлять панелью инструментов на основе содержимого страницы, например, состояния плагинов или заполнителей, но если вам это не нужно, лучше выбрать более простой метод populate().

class MyToolbar(CMSToolbar):

    def populate(self):

        # add items to the toolbar

Теперь вам нужно решить, какие именно элементы будут отображаться на панели инструментов. К ним можно отнести:

• menus

• buttons и списки кнопок

• различные другие элементы панели инструментов

def populate(self):

    self.toolbar.add_link_item( # or add_button(), add_modal_item(), etc
        name='A link',
        url=url
        )

from cms.utils.urlutils import admin_reverse
[...]

class PollToolbar(CMSToolbar):

    def populate(self):

        self.toolbar.add_sideframe_item(
            name='Poll list',
            url=admin_reverse('polls_poll_changelist')
            )

self.toolbar.add_modal_item(name='Add new poll', url=admin_reverse('polls_poll_add'))

def populate(self):

    button_list = self.toolbar.add_button_list()
    button_list.add_button(name='Button 1', url=url_1)
    button_list.add_button(name='Button 2', url=url_2)

def populate(self):
    menu = self.toolbar.get_or_create_menu(
        key='polls_cms_integration',
        verbose_name='Polls'
        )

def populate(self):
    menu = [...]

    menu.add_sideframe_item(
        name='Poll list',
        url=admin_reverse('polls_poll_changelist')
    )

menu.add_break(identifier='settings_section')

def populate(self):
    menu = [...]

    submenu = menu.get_or_create_menu(
        key='sub_menu_key',
        verbose_name='My sub-menu'
        )

Поиск существующих элементов панели инструментов¶

from cms.cms_toolbars import ADMIN_MENU_IDENTIFIER

class ManipulativeToolbar(CMSToolbar):

    def populate(self):

        admin_menu = self.toolbar.get_menu(ADMIN_MENU_IDENTIFIER)

        admin_menu.name = "Site"

def populate(self):

    self.toolbar.find_items(item_type=LinkItem)

self.toolbar.find_items(Menu, disabled=True))

Управление положением элементов на панели инструментов¶

Методы добавления пунктов меню на панель инструментов принимают необязательный аргумент position, который можно использовать для управления тем, куда будет вставлен пункт.

По умолчанию (position=None) элемент будет вставлен после существующих элементов на том же уровне иерархии (новое подменю станет последним подменю меню, новое меню станет последним меню на панели инструментов и так далее).

Позиция 0 вставляет элемент перед всеми остальными.

Если у вас уже есть объект, его тоже можно использовать в качестве ссылки. Например:

def populate(self):

    link = self.toolbar.add_link_item('Link', url=link_url)
    self.toolbar.add_button('Button', url=button_url, position=link)

добавит новую кнопку перед элементом ссылки.

Наконец, вы можете использовать ItemSearchResult в качестве позиции:

def populate(self):

    self.toolbar.add_link_item('Link', url=link_url)

    link = self.toolbar.find_first(LinkItem)

    self.toolbar.add_button('Button', url=button_url, position=link)

и поскольку ItemSearchResult может быть приведено к целому числу, вы даже можете сделать:

self.toolbar.add_button(„Button“, url=button_url, position=link+1)

Управление тем, как и когда появляется панель инструментов¶

По умолчанию ваш подкласс CMSToolbar будет активен (т.е. его методы populate будут вызываться) в панели инструментов на каждой странице, когда пользователь is_staff. Однако иногда подкласс CMSToolbar должен появляться на панели инструментов только при посещении страниц, связанных с определенным приложением.

Подкласс CMSToolbar имеет полезный атрибут, который может помочь определить, должна ли панель инструментов быть активирована. is_current_app является True, когда приложение, содержащее класс панели инструментов, совпадает с приложением, обрабатывающим запрос.

Это позволяет, например, активировать его выборочно:

def populate(self):

    if not self.is_current_app:
        return

    [...]

Если класс панели инструментов находится в другом приложении, а не в том, для которого вы хотите, чтобы он был активен, вы можете перечислить все приложения, которые он должен поддерживать при создании класса:

supported_apps = ['some_app']

supported_apps - это кортеж прикладных точечных путей (например: supported_apps = ('whatever.path.app', 'another.path.app').

Атрибут app_path будет содержать имя приложения, обрабатывающего текущий запрос - если app_path находится в supported_apps, то is_current_app будет True.

Изменение существующей панели инструментов¶

Если вам нужно изменить существующую панель инструментов (например, изменить атрибут или поведение метода), вы можете сделать это, создав ее подкласс, который реализует необходимые изменения, и зарегистрировав его вместо исходного.

Оригинальный класс можно снять с регистрации, используя toolbar_pool.unregister(), как в примере ниже. Также, если вы изначально вызывали класс панели инструментов с помощью CMS_TOOLBARS, вам нужно будет изменить его, чтобы он ссылался на новый класс.

Пример, в котором мы снимаем с регистрации оригинал и регистрируем свой собственный:

from cms.toolbar_pool import toolbar_pool
from third_party_app.cms_toolbar import ThirdPartyToolbar

@toolbar_pool.register
class MyBarToolbar(ThirdPartyToolbar):
    [...]

toolbar_pool.unregister(ThirdPartyToolbar)

Обнаружение изменений URL-адреса объекта¶

Если вы хотите следить за созданием объектов или редактированием моделей и перенаправлять после их добавления или изменения, добавьте на панель инструментов атрибут watch_models.

Пример:

class PollToolbar(CMSToolbar):

    watch_models = [Poll]

    def populate(self):
        ...

После добавления этой функции каждое изменение экземпляра Poll через боковой фрейм или модальное окно будет вызывать перенаправление на URL экземпляра опроса, который был отредактирован, в соответствии со статусом панели инструментов:

• в режиме черновик возвращается get_draft_url() (или get_absolute_url(), если первого не существует)

• в режиме live, и метод существует, возвращается get_public_url().

Frontend¶

Если вам необходимо взаимодействовать с панелью инструментов или иным образом учитывать ее в коде фронтенда вашего сайта, она предоставляет крючки CSS и JavaScript для использования.

Он добавит различные классы к элементу <html> страницы:

• cms-ready, когда панель инструментов готова

• cms-toolbar-expanded, когда панель инструментов полностью развернута

• cms-toolbar-expanding и cms-toolbar-collapsing во время анимации панели инструментов.

Панель инструментов также запускает событие JavaScript под названием cms-ready в документе. Вы можете прослушать это событие с помощью jQuery:

CMS.$(document).on('cms-ready', function () { ... });