• en
  • Language: ru
  • 3.7.x
  • Documentation version: 3.9

Панель инструментов

Панель инструментов может содержать различные элементы, некоторые из которых, в свою очередь, могут содержать другие элементы. Эти элементы представлены классами, перечисленными в cms.toolbar.items, и создаются с помощью различных API, описанных ниже.

Не инстанцируйте эти классы вручную

Эти классы описаны здесь только в справочных целях. Настоятельно рекомендуется не создавать экземпляры самостоятельно, а использовать перечисленные здесь методы.

Классы и методы

Common parameters (key, verbose_name, position, on_close, disabled, active) и опции описаны в конце этого документа.

class cms.toolbar.toolbar.CMSToolbar

Панель инструментов является экземпляром класса cms.toolbar.toolbar.CMSToolbar. Его не следует путать с CMSToolbar, базовым классом для классов-модификаторов панели инструментов в других приложениях, которые добавляют элементы на панель инструментов и манипулируют ею иным образом.

Настоятельно рекомендуется взаимодействовать с панелью инструментов только в собственном коде:

  • API, задокументированные здесь

  • классы модификаторов панели инструментов на основе cms.toolbar_base.CMSToolbar

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

Некоторые из следующих методов создания и добавления других объектов на панель инструментов унаследованы от ToolbarAPIMixin.

См. ToolbarAPIMixin.add_link_item

add_sideframe_item()

См. ToolbarAPIMixin.add_sideframe_item

add_modal_item()

См. ToolbarAPIMixin.add_modal_item

add_ajax_item()

См. ToolbarAPIMixin.add_ajax_item

add_item()

См. ToolbarAPIMixin.add_item

get_or_create_menu(key, verbose_name, position=None, disabled=False)

Если меню с идентификатором Menu и key уже существует, этот метод вернет это меню. В противном случае будет создано меню с идентификатором key.

get_menu(key)

Вернет Menu, идентифицированный с key, или None.

add_button(name, url, active=False, disabled=False, position=None)

Добавляет Button на панель инструментов.

add_sideframe_button(name, url, active=False, disabled=False, on_close=None)

Добавляет SideframeButton на панель инструментов.

add_modal_button(name, url, active=False, disabled=False, on_close=REFRESH_PAGE)

Добавляет ModalButton на панель инструментов.

add_button_list(position=None)

Добавляет (пустой) ButtonList на панель инструментов и возвращает его.

edit_mode_active()

Свойство; возвращает True, если активны режимы редактирования доски содержимого или доски структуры.

watch_models()

Свойство; список моделей, которые панель инструментов watches for URL changes, чтобы она могла перенаправить на новый URL при сохранении.

class cms.toolbar.items.Menu

Предоставляет меню на панели инструментов. Используйте метод CMSToolbar.get_or_create_menu для создания экземпляра Menu. Может быть добавлен к CMSToolbar.

Наследует от SubMenu ниже, поэтому разделяет все его методы, но дополнительно имеет:

get_or_create_menu(key, verbose_name, disabled=False, position=None)

Добавляет новое подменю, по адресу position, и возвращает SubMenu.

class cms.toolbar.items.SubMenu

Потомок Menu. Используйте метод Menu.get_or_create_menu для создания экземпляра SubMenu. Может быть добавлен к Menu.

Некоторые из следующих методов создания и добавления объектов унаследованы от ToolbarAPIMixin.

См. ToolbarAPIMixin.add_link_item

add_sideframe_item()

См. ToolbarAPIMixin.add_sideframe_item

add_modal_item()

См. ToolbarAPIMixin.add_modal_item

add_ajax_item()

См. ToolbarAPIMixin.add_ajax_item

add_item()

См. ToolbarAPIMixin.add_item

get_item_count()

Возвращает количество пунктов в меню.

Другие методы:

add_break(identifier=None, position=None)

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

class cms.toolbar.items.LinkItem

Отправляет GET-запрос. Используйте метод add_link_item для создания экземпляра LinkItem. Может быть добавлен к CMSToolbar, Menu, SubMenu.

class cms.toolbar.items.SideframeItem

Отправляет GET-запрос; загружает ответ в боковой рамке. Используйте метод add_sideframe_item для создания экземпляра SideframeItem. Может быть добавлен к CMSToolbar, Menu, SubMenu.

class cms.toolbar.items.ModalItem

Отправляет GET-запрос; загружает ответ в модальном окне. Используйте метод add_modal_item для создания экземпляра ModalItem. Может быть добавлен к CMSToolbar, Menu, SubMenu.

class cms.toolbar.items.AjaxItem

Отправляет POST-запрос. Используйте метод add_ajax_item для создания экземпляра AjaxItem. Может быть добавлен к CMSToolbar, Menu, SubMenu.

class cms.toolbar.items.Break

Визуальный разрыв в меню. Используйте метод add_break для создания экземпляра Break. Может быть добавлен к Menu, SubMenu.

class cms.toolbar.items.ButtonList

Визуально связанный список из одной или нескольких кнопок. Используйте метод add_button_list() для создания экземпляра Button. Может быть добавлен к CMSToolbar.

add_button(name, url, active=False, disabled=False)

Добавляет Button в список кнопок и возвращает его.

add_sideframe_button(name, url, active=False, disabled=False, on_close=None)

Добавляет ModalButton на панель инструментов.

add_modal_button(name, url, active=False, disabled=False, on_close=REFRESH_PAGE)

Добавляет (пустой) ButtonList на панель инструментов и возвращает его.

get_buttons()
class cms.toolbar.items.Button

Отправляет запрос GET. Используйте метод CMSToolbar.add_button или ButtonList.add_button() для создания экземпляра Button. Может быть добавлен к CMSToolbar, ButtonList.

class cms.toolbar.items.SideframeButton

Отправляет запрос GET. Используйте метод CMSToolbar.add_sideframe_button или ButtonList.add_sideframe_button() для создания экземпляра SideframeButton. Может быть добавлен к CMSToolbar, ButtonList.

class cms.toolbar.items.ModalButton

Отправляет запрос GET. Используйте метод CMSToolbar.add_modal_button или ButtonList.add_modal_button() для создания экземпляра ModalButton. Может быть добавлен к CMSToolbar, ButtonList.

class cms.toolbar.items.BaseItem

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

template

Должен быть установлен подклассами и указывать на шаблон Django

render()

Рендерит элемент и возвращает его в виде строки. По умолчанию вызывает get_context() и рендерит template с возвращенным контекстом.

get_context()

Возвращает контекст (в виде словаря) для данного элемента.

class cms.toolbar.items.ToolbarAPIMixin

Предоставляет API, используемые CMSToolbar и Menu.

Добавляет LinkItem, который открывает url, и возвращает его.

add_sideframe_item(name, url, active=False, disabled=False, on_close=None, position=None)

Добавляет SideframeItem, который открывает url в боковой рамке, и возвращает его.

add_modal_item(name, url, active=False, disabled=False, on_close=REFRESH_PAGE, position=None)

Аналогичен add_sideframe_item(), но добавляет ModalItem, который открывает url в модальном диалоге вместо бокового фрейма, и возвращает его.

add_ajax_item(name, action, active=False, disabled=False, data=None, question=None, position=None)

Добавляет AjaxItem, который отправляет POST-запрос на action с data, и возвращает его. data должен быть None или словарь. CSRF-токен будет автоматически добавлен к элементу.

Если для question указана строка, она будет представлена пользователю для подтверждения перед отправкой запроса.

add_item(item, position=None)

Добавляет элемент (который должен быть подклассом BaseItem) и возвращает его. Это низкоуровневый API, и для добавления элементов всегда следует использовать один из встроенных методов, специфичных для объекта, предпочитая, по возможности, использовать этот метод только для пользовательских классов элементов.

find_items(item_type)

Возвращает список объектов ItemSearchResult, соответствующих всем элементам item_type (например, LinkItem).

find_first(item_type, **attributes)

Возвращает первый ItemSearchResult, соответствующий поиску, или None. Стратегия поиска такая же, как и в find_items(). Возвращаемое значение этого метода безопасно для использования в качестве аргумента position различных API для добавления элементов.

class cms.toolbar.items.ItemSearchResult

Возвращается API find в формате ToolbarAPIMixin.

У ItemSearchResult будет два полезных атрибута:

item

Найденный предмет.

index

Индекс элемента (его положение среди других элементов).

Сам параметр ItemSearchResult может быть приведен к целому числу и поддерживает сложение и вычитание чисел. Более подробную информацию см. в параметре position, а примеры - в Управление положением элементов на панели инструментов.

class cms.toolbar_base.CMSToolbar.CMSToolbar

Базовый класс для модификаторов панели инструментов.

Дополнительную информацию см. в разделе Как расширить панель инструментов.

Параметры

Описанные ниже методы создания/изменения элементов панели инструментов имеют ряд общих параметров:

key

уникальный идентификатор (обычно строка)

verbose_name

отображаемый текст в элементе

position

Индекс позиции нового элемента в списке элементов. Может быть:

  • None - добавляет элемент в список

  • целое число - вставляет элемент по данному индексу в список

  • объект уже в списке - вставляет элемент в список непосредственно перед объектом; должен быть подклассом BaseItem, и должен существовать в списке

  • ItemSearchResult - вставляет элемент в список непосредственно перед ItemSearchResult. ItemSearchResult может рассматриваться как целое число.

on_close:

Определяет, что происходит после закрытия фрейма (бокового или модального), который был открыт пунктом меню. Может быть:

  • None - ничего не делает, когда боковой фрейм закрывается

  • REFRESH_PAGE - обновляет страницу при закрытии фрейма

  • URL - открывает URL-адреса при закрытии фрейма.

disabled

Закрашивает элемент и делает его неработоспособным.

active

Применяется только к кнопкам; отображает кнопку в «активированном» состоянии.

Константы django CMS, используемые в панелях инструментов

cms.constants.REFRESH_PAGE

Подставляется в аргументы on_close для обновления текущей страницы при закрытии фрейма, например:

from cms.constants import REFRESH_PAGE

self.toolbar.add_modal_item(
    'Modal item',
    url=modal_url,
    on_close=REFRESH_PAGE
    )
cms.cms_toolbars.ADMIN_MENU_IDENTIFIER

Меню Site (в котором обычно отображается доменное имя проекта, по умолчанию example.com). ADMIN_MENU_IDENTIFIER позволяет легко получить доступ к этому объекту. Пример использования см. в Поиск существующих элементов панели инструментов.