Плагины¶

Наследует django.contrib.admin.ModelAdmin и в большинстве аспектов ведет себя как обычный подкласс. Обратите внимание, что некоторые атрибуты ModelAdmin просто не будут иметь смысла в контексте Plugin.

Атрибуты

admin_preview¶

По умолчанию: False

Если True, отображает предварительный просмотр в админке.

allow_children¶

По умолчанию: False

Позволяет этому плагину иметь дочерние плагины - другие плагины, размещенные внутри него?

Если True, вам необходимо убедиться, что ваш плагин может отображать свои дочерние элементы в шаблоне плагина. Например:

{% load cms_tags %}
<div class="myplugin">
    {{ instance.my_content }}
    {% for plugin in instance.child_plugin_instances %}
        {% render_plugin plugin %}
    {% endfor %}
</div>

instance.child_plugin_instances предоставляет доступ ко всем дочерним элементам плагина. Они предварительно заполнены и готовы к использованию. Дочерние плагины должны быть отображены с помощью тега шаблона {% render_plugin %}.

См. также: child_classes, parent_classes, require_parent.

cache¶

По умолчанию: CMS_PLUGIN_CACHE

Можно ли кэшировать этот плагин? Если ваш плагин отображает содержимое в зависимости от пользователя, запроса или других динамических свойств, установите значение False.

Если присутствует и имеет значение False, плагин будет предотвращать кэширование получаемой страницы.

Важно

Установка значения False эффективно отключит кэш страниц CMS и все вышестоящие кэши для страниц, на которых появляется плагин. Это может быть полезно в некоторых случаях, но для общего управления кэшем лучше использовать более подходящее значение get_cache_expiration().

Предупреждение

Если вы отключили кэш плагина, обязательно перезапустите сервер и очистите кэш после этого.

change_form_template¶

По умолчанию: admin/cms/page/plugin_change_form.html

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

Пример:

class MyPlugin(CMSPluginBase):
    model = MyModel
    name = _("My Plugin")
    render_template = "cms/plugins/my_plugin.html"
    change_form_template = "admin/cms/page/plugin_change_form.html"

См. также: frontend_edit_template.

child_classes¶

По умолчанию: None

Список имен классов плагинов. Если этот параметр установлен, в этот плагин могут быть добавлены только перечисленные здесь плагины.

См. также: parent_classes.

disable_child_plugins¶

По умолчанию: False

Отключает перетаскивание дочерних плагинов в режиме структуры.

form¶

Класс пользовательской формы, который будет использоваться для редактирования этого плагина.

frontend_edit_template¶

Этот атрибут устарел и будет удален в версии 3.5..

По умолчанию: cms/toolbar/plugin.html

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

См. также: change_form_template.

model¶

По умолчанию: CMSPlugin

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

См. также: Хранение конфигурации.

module¶

Группирует плагин в подборщике плагинов. Если атрибут модуля не указан, плагин попадает в группу «Generic».

name¶

Будет отображаться в подборщике плагинов.

page_only¶

По умолчанию: False

Установите значение True, если этот плагин должен использоваться только в placeholder, прикрепленном к странице django CMS, а не в других моделях с PlaceholderFields.

См. также: child_classes, parent_classes, require_parent.

parent_classes¶

По умолчанию: None

Список имен допустимых родительских классов для этого плагина.

См. также: child_classes, require_parent.

render_plugin¶

Если установлено значение False, этот плагин не будет отображаться вообще. По умолчанию: True

Если True, то render_template() также должно быть определено.

См. также: render_template, get_render_template().

render_template¶

По умолчанию: None

Путь к шаблону, используемому для рендеринга шаблона. Если render_plugin равно True, то либо это, либо get_render_template **должны быть определены;

См. также: render_plugin , get_render_template().

require_parent¶

По умолчанию: False

Требуется ли, чтобы этот плагин был дочерним для другого плагина? Или он может быть добавлен в любой placeholder, даже прикрепленный к странице.

См. также: child_classes, parent_classes.

text_enabled¶

По умолчанию: False

Этот атрибут контролирует, будет ли ваш плагин использоваться (и отображаться) в текстовом плагине. Когда вы редактируете текстовый плагин на странице, плагин появится в выпадающем списке CMS Plugins, и его можно будет настроить и вставить. Вывод будет даже предварительно просматриваться в текстовом редакторе.

Конечно, не все плагины можно использовать в текстовых плагинах. Поэтому по умолчанию этот атрибут имеет значение False. Если ваш плагин является пригодным для использования в текстовом плагине:

• установите значение True

• убедитесь, что ваш плагин предоставляет свой собственный icon_alt(), он будет использоваться в качестве всплывающей подсказки в текстовом редакторе и пригодится, когда вы используете несколько плагинов в тексте.

См. также: icon_alt(), icon_src().

Методы

get_plugin_urls(instance)¶

Возвращает шаблоны URL, для которых плагин хочет зарегистрировать представления. Они включаются в URLS администратора страниц django CMS в пути к плагину (например: /admin/cms/page/plugin/<plugin-name>/ в случае по умолчанию).

get_plugin_urls() полезно, если ваш плагин должен асинхронно общаться с администратором.

get_render_template()¶

Если вам нужно определить модель рендеринга плагина во время рендеринга, вы можете реализовать метод get_render_template() в классе плагина; этот метод принимает те же аргументы, что и render.

Метод должен возвращать правильный путь к файлу шаблона.

Пример:

def get_render_template(self, context, instance, placeholder):
    if instance.attr = 'one':
        return 'template1.html'
    else:
        return 'template2.html'

См. также: render_plugin() , render_template()

get_extra_placeholder_menu_items(self, request, placeholder)¶

Расширяет контекстное меню для всех заполнителей.

Чтобы добавить один или несколько пользовательских пунктов контекстного меню, которые отображаются в контекстном меню для всех заполнителей в режиме структуры, переопределите этот метод в связанном плагине, чтобы вернуть список экземпляров cms.plugin_base.PluginMenuItem.

get_extra_global_plugin_menu_items(self, request, plugin)¶

Расширяет контекстное меню для всех плагинов.

Чтобы добавить один или несколько пользовательских пунктов контекстного меню, которые отображаются в контекстном меню для всех плагинов в режиме структуры, переопределите этот метод в связанном плагине, чтобы вернуть список экземпляров cms.plugin_base.PluginMenuItem.

get_extra_local_plugin_menu_items()¶

Расширяет контекстное меню для конкретного плагина. Чтобы добавить один или несколько пользовательских пунктов контекстного меню, которые отображаются в контекстном меню для данного плагина в режиме структуры, переопределите этот метод в плагине, чтобы вернуть список экземпляров cms.plugin_base.PluginMenuItem.

get_cache_expiration(self, request, instance, placeholder)¶

Предоставляет значение истечения срока действия местодержателю и, в свою очередь, странице для определения соответствующих заголовков Cache-Control для добавления в объект HTTPResponse.

Должен вернуть одно из:

None

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

datetime

Определенная дата и время (с учетом часового пояса) в будущем, когда истечет срок действия содержимого этого плагина.

Важно

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

int

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

В cms.constants определены константы, которые могут быть полезны: EXPIRE_NOW и MAX_EXPIRATION_TTL.

Целочисленное значение 0 (ноль) или EXPIRE_NOW фактически означает «не кэшировать». Отрицательные значения будут рассматриваться как EXPIRE_NOW. Значения, превышающие значение MAX_EXPIRATION_TTL, будут установлены в это значение.

Отрицательные значения timedelta или значения, превышающие MAX_EXPIRATION_TTL, также будут ранжироваться таким же образом.

Аналогично, значения datetime раньше, чем сейчас, будут рассматриваться как EXPIRE_NOW. Значения, превышающие MAX_EXPIRATION_TTL секунд в будущем, будут рассматриваться как MAX_EXPIRATION_TTL секунд в будущем.

Параметры

• request – Соответствующий HTTPRequest экземпляр.

• instance – Экземпляр CMSPlugin, который отображается.

Тип результата

None или datetime или int

get_vary_cache_on(self, request, instance, placeholder)¶

Возвращает строку заголовка HTTP VARY или их список, который будет учитываться заполнителем и, в свою очередь, поведением страницы для кэширования.

Переопределение этого метода необязательно.

Должен вернуть одно из:

None

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

строка

Имя заголовка, по которому будет изменяться кэширование.

список строк

Список строк, каждая из которых соответствует заголовку для изменения кэша.

icon_alt()¶

По умолчанию icon_alt() возвращает строку вида: «[тип плагина] - [экземпляр]», но может быть модифицирована так, чтобы возвращать что угодно.

Эта функция принимает instance в качестве параметра и возвращает строку, которая будет использоваться в качестве alt текста для предварительного просмотра или иконки плагина.

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

icon_alt() принимает 1 аргумент:

• instance: Экземпляр модели плагина

Реализация по умолчанию выглядит следующим образом:

def icon_alt(self, instance):
    return "%s - %s" % (force_str(self.name), force_str(instance))

См. также: text_enabled, icon_src().

icon_src(instance)¶

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

Следовательно, это должно быть переопределено, когда для плагина text_enabled установлено значение True, чтобы вернуть путь к иконке для отображения в тексте текстового плагина.

С тех пор как в djangocms-text-ckeditor появился встроенный предварительный просмотр плагинов, иконка больше не будет отображаться.

icon_src принимает 1 аргумент:

• instance: Экземпляр модели плагина

Пример:

def icon_src(self, instance):
    return settings.STATIC_URL + "cms/img/icons/plugins/link.png"

См. также: text_enabled, icon_alt()

render(context, instance, placeholder)¶

Этот метод возвращает контекст, который будет использоваться для рендеринга шаблона, указанного в render_template.

Метод render() принимает три аргумента:

• context: Контекст, с которым отображается страница.

• instance: экземпляр вашего плагина, который отображается.

• placeholder: Имя отображаемого заполнителя.

Этот метод должен возвращать словарь или экземпляр django.template.Context, который будет использоваться как контекст для рендеринга шаблона плагина.

По умолчанию этот метод будет добавлять instance и placeholder к контексту, что означает, что для простых плагинов нет необходимости перезаписывать этот метод.

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

def render(self, context, instance, placeholder):
    context = super().render(context, instance, placeholder)
    ...
    return context

Параметры

• context – Текущий контекст шаблона.

• instance – Экземпляр плагина, который отображается.

• placeholder – Имя местоположения, в котором находится плагин.

Тип результата

dict

text_editor_button_icon()¶

Когда text_enabled равно True, этот плагин может быть добавлен в текстовый редактор, и для этого может существовать кнопка-иконка. Данный метод позволяет переопределить эту иконку.

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

text_editor_button_icon() принимает 2 аргумента:

• editor_name: Имя плагина текстового редактора

• icon_context: Словарь, содержащий информацию о нужной иконке, такую как ширина, высота, тема и т.д.

Обычно этот метод должен возвращать URL иконки. Но это может зависеть от текстового редактора, поскольку требуемые параметры могут отличаться. Пожалуйста, обратитесь к документации плагина вашего текстового редактора.

Для этого требуется поддержка текстового плагина; поддержка этого плагина в настоящее время планируется в версии djangocms-text-ckeditor 2.5.0.

См. также: text_enabled.

__init___(name, url, data, question=None, action='ajax', attributes=None)¶

Создает пункт в меню плагина/заместителя

Параметры

• name – Название элемента (этикетка)

• url – URL, на который указывает элемент. Этот URL будет вызываться с помощью POST

• data – Данные, которые должны быть отправлены на указанный выше URL-адрес

• question – Подтверждающий текст, который будет показан пользователю перед вызовом данного URL (необязательно)

• action – Пользовательское действие, которое будет вызываться при нажатии; в настоящее время поддерживаются: „ajax“, „ajax_add“

• attributes – Словарь, содержимое которого будет добавлено в качестве данных-атрибутов к пункту меню

См. также: Хранение конфигурации

Атрибуты

translatable_content_excluded_fields¶

По умолчанию: [ ]

Список полей плагина, которые не будут экспортироваться при использовании get_translatable_content().

См. также: get_translatable_content(), set_translatable_content().

Методы

copy_relations()¶

Обработка копирования любых отношений, связанных с этим плагином. Пользовательские плагины должны делать это самостоятельно.

copy_relations принимает 1 аргумент:

• old_instance: Исходный экземпляр плагина

См. также: Работа с отношениями, post_copy().

get_translatable_content()¶

Получите словарь всех полей содержимого (пары имя поля / значение поля) из плагина.

Пример:

from djangocms_text_ckeditor.models import Text

plugin = Text.objects.get(pk=1).get_bound_plugin()[0]
plugin.get_translatable_content()
# returns {'body': u'<p>I am text!</p>\n'}

См. также: translatable_content_excluded_fields, set_translatable_content.

post_copy()¶

Может (должно) быть переопределено для обработки копирования плагинов, содержащих дочерние плагины, после копирования исходного родительского плагина.

post_copy принимает 2 аргумента:

• old_instance: Старый экземпляр плагина

• new_old_ziplist: Список кортежей, содержащий новые копии и старые существующие дочерние плагины.

См. также: Работа с отношениями, copy_relations().

set_translatable_content()¶

Берет словарь полей плагина (пары имя поля / значение поля) и перезаписывает поля плагина. Возвращает True, если все поля были записаны успешно, и False в противном случае.

set_translatable_content принимает 1 аргумент:

• fields: Словарь, содержащий имена полей и переведенное содержимое каждого из них.

• get_translatable_content()

Пример:

from djangocms_text_ckeditor.models import Text

plugin = Text.objects.get(pk=1).get_bound_plugin()[0]
plugin.set_translatable_content({'body': u'<p>This is a different text!</p>\n'})
# returns True

См. также: translatable_content_excluded_fields, get_translatable_content().

get_add_url()¶

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

get_edit_url()¶

Возвращает URL, который нужно вызвать для редактирования экземпляра плагина; полезно для реализации специфической для плагина логики в пользовательском представлении.

get_move_url()¶

Возвращает URL, который нужно вызвать для перемещения экземпляра плагина; полезно для реализации специфической для плагина логики в пользовательском представлении.

get_delete_url()¶

Возвращает URL, который нужно вызвать для удаления экземпляра плагина; полезно для реализации специфической для плагина логики в пользовательском представлении.

get_copy_url()¶

Возвращает URL, который нужно вызвать для копирования экземпляра плагина; полезно для реализации специфической для плагина логики в пользовательском представлении.