Пользовательские плагины

20 April 2014 г. 19:37:28

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

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

Это почти как магия, только лучше.

Если Вы настолько удачливы и вам не пришлось познакомиться со встроенными или сторонними плагинами, сейчас у вас появиться возможность написать свой собственный плагины. Но не волнуйтесь, писать плагины в Django CMS очень просто.

3.1. Зачем может понадобиться писать плагины?

3.2. Обзор

3.2.1. Замечание о cms.plugin_base.CMSPluginBase

3.2.2. Рассмотрим модель и конфигурацию

3.3. Простейший плагин

3.4. Поиск ошибок

3.5. Сохранение конфигурации

3.5.1 Обработка отношений

3.5.1.1 Копирование объекта при отношения от другого объекта по внешнему ключу

3.5.1.2 Копирование объекта для отношения многий ко многим на другие объекты

3.6 Дополнительно

3.6.1 Форма плагина

3.4.2 Обработка медиа

3.6.2.1 Стили sekizai

3.6.3. Контекст плагина

3.6.4. Обработчики контекста плагина

3.6.5. Процессор плагина

3.6.5.1 Пример

3.6.6. Вложенные шаблоны

3.7. Атрибуты CMSPluginBase и методы ссылок

3.7.1. Атрибуты

3.7.1.1. admin_preview

3.7.1.2. allow_children

3.7.1.3. cache

3.7.1.4. change_form_template

3.7.1.5. child_classes

3.7.1.6. disable_child_plugins

3.7.1.7. frontend_edit_template

3.7.1.8. model

3.7.1.9. page_only

3.7.1.10. parent_classes

3.7.1.11. render_plugin

3.7.1.11.1. render_template

3.7.1.12. require_parent

3.7.1.13. text_enabled

3.7.2. Методы

3.7.2.1. icon_src

3.7.2.2. icon_alt

3.8 Атрибуты и метода CMSPlugin

3.8.1. Атрибуты

3.8.1.1. translatable_content_excluded_fields

3.8.2. Методы

3.8.2.1. copy_relations

3.8.2.2. get_translatable_content

3.8.2.3. post_copy

3.8.2.4. set_translatable_content

3.1. Зачем может понадобиться писать плагины?

Плагины это самый удобный способ интегрировать любое Django приложения в страницу django CMS.

Например Вы хотите разработать сайт для звукозаписывающей компании на django CMS. Скорее всего вам понадобится блок “последние релизы” на главной странице сайта.

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

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

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

3.2. Обзор

В django CMS плагины в общем состоят из трех вещей:

  • редактор плагина, для конфигурации плагина при использовании.

  • издатель плагина, для автоматического решения какую информацию следует публиковать

  • шаблон плагина, для отображения информации на странице

Это очень похоже на уже знакомую схему Модель-представление-шаблон MVT:

  • модель плагина хранит конфигурацию

  • представление плагина заботиться о том чтобы отображалась нужная информация

  • шаблон плагина отображает информацию

Таким образом, чтобы разработать собственный плагин, Вам надо создать его из:

  • класс унаследованный от cms.models.pluginmodel.CMSPlugin служит для сохранения конфигурации для экземпляра плагина

  • класс унаследованный от cms.plugin_base.CMSPluginBase определят для вашего плагина логику операций

  • шаблон который отображает ваш плагин

3.2.1. Замечание о cms.plugin_base.CMSPluginBase

В общем cms.plugin_base.CMSPluginBase наследуется от django.contrib.admin.options.ModelAdmin.

И его метод render() который является функцией представления плагина.

3.2.2. Рассмотрим модель и конфигурацию

Наследования модели от cms.models.pluginmodel.CMSPlugin является не обязательным.

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

Например Вы можете создать плагин который только публикует информации о записях которые лучше всего продаются за неделю. Очевидно, этот подход не очень гибкий - вы можете захотеть использовать этот плагин для вывода информации о продажах за месяц.

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

3.3 Простейший плагин

Вы можете воспользоваться командой python manage.py startapp для создания базового размещения приложения для плагина. Или вы можете просто создать файл под названием cms_plugins.py в существующем приложении Django.

В этом файле размещается Ваш плагин. Например добавьте туда следующий код:

from cms.plugin_base import CMSPluginBase
from cms.plugin_pool import plugin_pool
from cms.models.pluginmodel import CMSPlugin
from django.utils.translation import ugettext_lazy as _
class HelloPlugin(CMSPluginBase):
model = CMSPlugin
render_template = "hello_plugin.html"
plugin_pool.register_plugin(HelloPlugin)

Теперь все почти готово. Все что осталось это добавить шаблон. И поместите следующий код в к файл hello_plugin.html в корневом директории шаблонов.

<h1>Hello
{% if request.user.is_authenticated %}{{ request.user.first_name }} {{ request.user.last_name}}{% else %}Guest{% endif %}
</h1>

Этот плагин будет приветствовать посетителей Вашего сайта по его имени, если он вошел на сайт, или Guest если нет.

Давайте рассмотрим внимательнее что он делает. Определять классы наследованные от cms.models.pluginmodel.CMSPlugin следует в файлах cms_plugin.py, эти классы определяются для различных плагинов.

Есть три требуемых атрибута для этого класса:

  • model: Модель вы можете использовать для сохранения информации о плагинах. Если Вы не требуете чтобы сохранялась какая-то специфическая информация (например конфигурация), Вы можете просто использовать cms.models.pluginmodel.CMSPlugin (давайте на секунду взглянем на эту модель более детально). В обычном классе admin Вам не надо поддерживать эту информацию потому что admin.site.register(Model, Admin) берет на себя всю работу, но плагины не работают таким образом.

  • name: Имя Вашего плагина которое будет отображаться в панели администратора. Хорошей практикой является отмечать эту строку переводимой используя django.utils.translation.ugettext_lazy(), но это совсем не обязательно. По умолчанию имя является более приятной версией имени класса.

  • render_template Шаблон для отображения плагина.

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

Метод render принимает три параметра:

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

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

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

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

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

3.4 Поиск ошибок

Так как модули плагинов загружаются при помощи importlib django, вы можете получить сообщение об ошибках потому что путь окружения отличается от пути при выполнении. Если файл cms_plugins не загружен или не доступен, попробуйте следующую команду:

$ python manage.py shell
>>> from django.utils.importlib import import_module
>>> m = import_module("myapp.cms_plugins")
>>> m.some_test_function()

3.5 Сохранение конфигурации

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

Чтобы это сделать создайте модель Django и унаследуйте его от cms.models.pluginmodel.CMSPlugin в файле models.py конкретного приложения.

Давайте усовершенствуем плагин HelloPlugin создав собственное настраиваемое имя для не-авторизованных пользователей.

В файле models.py добавьте следующее:

from cms.models.pluginmodel import CMSPlugin
from django.db import models
class Hello(CMSPlugin):
guest_name = models.CharField(max_length=50, default='Guest')

Если Вы проходили руководство по Django, то Вам все должно быть знакомо. Единственное отличие от обычных моделей это наследование от cms.models.pluginmodel.CMSPlugin вместо django.db.models.base.Model.

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

from cms.plugin_base import CMSPluginBase
from cms.plugin_pool import plugin_pool
from django.utils.translation import ugettext_lazy as _
from .models import Hello
class HelloPlugin(CMSPluginBase):
model = Hello
name = _("Hello Plugin")
render_template = "hello_plugin.html"
def render(self, context, instance, placeholder):
context['instance'] = instance
return context
plugin_pool.register_plugin(HelloPlugin)

Мы изменили атрибут model чтобы связать его с только что созданной моделью Hello и передать экземпляр модели в контекст.

Как и в прошлом шаге нам понадобиться обновить наш шаблон чтобы учесть новую конфигурацию:

<h1>Hello {% if request.user.is_authenticated %}
{{ request.user.first_name }} {{ request.user.last_name}}
{% else %}
{{ instance.guest_name }}
{% endif %}</h1>

Единственное изменение это замена переменной шаблона {{ instance.guest_name }} вместо жестко сашитой строки Guest.

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

В данный момент класс унаследованный от cms.models.pluginmodel.CMSPlugin не может быть унаследован в дальнейшем. Если Вы захотите повторно использовать модель плагина, то надо использовать абстрактные модели.

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

В качестве имен полей Вашей модели вы не можете использовать имена любых установленных плагинов в нижнем регистре, из-за конфликта отношений один к одному, который возникнет в модели. Если Вы используете все встроенные плагины, то они включают file, flash, googlemap, link, picture, snippetptr, teaser, twittersearch, twitterrecententries и video.

Также рекомендуется избегать для поля подели имени page, так как у класса cms.models.pluginmodel.CMSPlugin задеклорировано свойство с аналогичным именем, и плагин может работать не корректно.

3.5.1 Обработка отношений

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

Каждая модель плагина наследует пустой метод cms.models.pluginmodel.CMSPlugin.copy_relations() базового класса и вызывает его при копировании плагина. Таким образом вы моете адаптировать это поведение для собственных нужд.

Обычно требуется копировать связанные объекты, чтобы сделать это, Вам потребуется создать в модели метод copy_relations который получает старый экземпляр плагина в качестве параметра.

Вы так же можете определить какие отношения не должны копироваться - например вы хотите оставить их как есть. Или возможно даже выбрать какие то другие отношения для них, или создать новые при копировании. Это зависит от вашего плагина и того как вы хотите работать.

Если вы хотите скопировать связанный объект, то Вы можете это сделать двумя немного разными способами, в зависимости от того надо-ли скопировать объект на который ссылается ваш плагин, или другой объект ссылается на ваш плагин

3.5.1.1 Копирование объекта при отношения от другого объекта по внешнему ключу

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

class ArticlePluginModel(CMSPlugin):
title = models.CharField(max_length=50)
class AssociatedItem(models.Model):
plugin = models.ForeignKey(
ArticlePluginModel,
related_name="associated_item"
)

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

 class ArticlePluginModel(CMSPlugin):
title = models.CharField(max_length=50)
def copy_relations(self, oldinstance):
for associated_item in oldinstance.associated_item.all():
# instance.pk = None; instance.pk.save() это выглядит немного странным
# стандартный способ копирования в Django и сохранения экземпляра модели
associated_item.pk = None
associated_item.plugin = self
associated_item.save()

3.5.1.2 Копирование объекта для отношения многий ко многим на другие объекты

Давайте предположим что код ниже это соответствующая часть вашего плагина:

class ArticlePluginModel(CMSPlugin):
title = models.CharField(max_length=50)
sections = models.ManyToManyField(Section)

И когда мы захотим скопировать плагин, Вы можете секции (sections) плагину сохраняться, если используется следующее:

class ArticlePluginModel(CMSPlugin):
title = models.CharField(max_length=50)
sections = models.ManyToManyField(Section)
def copy_relations(self, oldinstance):
self.sections = oldinstance.sections.all()

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

3.6 Дополнительно

3.6.1 Форма плагина

Так как cms.plugin_base.CMSPluginBase расширяет django.contrib.admin.options.ModelAdmin, вы можете создать форму для настроки плагина, которую можно использовать в интерфейсе панели администратора.

Шаблона который используется для редактирования плагина находится в файле cms/templates/admin/cms/page/plugin_change_form.html. Возможно понадобится его изменить.

Если Вы хотите настроить его, то лучший способ сделать это:

  • создать собственный шаблон который наследуется от cms/templates/admin/cms/page/plugin_change_form.html, для предоставления требуемой функциональности.

  • предоставить свой собственный класс унаследованный от cms.plugin_base.CMSPluginBase с атрибутом change_from_template, ссылающегося на Ваш шаблон.

Наследуя шаблон от cms/templates/admin/cms/page/plugin_change_form.html вы можете быть уверены, что ваш шаблон будет иметь ту же функциональность и внешний вид, как и остальных плагинов.

Есть много причин, по которым это может понадобиться. Например вам может понадобиться JavaScript сниппет, который должен ссылаться на переменную в шаблоне, которая скорее находится в блоке {% block extrahead %} после {{ block.super }} (чтобы наследовать существующие элементы, которые находятся в родительском шаблоне.

Или cms/templates/admin/cms/page/plugin_change_form.html расширяет собственный шаблон admin/base_site.html, который загружает достаточно старую версию JQuery, а Ваш плагин может потребовать более новую версию. В таком случае вы можете это настроить. Чтобы переопределить *{% block jquery %} добавив в change_form_template следующее:

{% block jquery %}
<script type="text/javascript" src="///ajax.googleapis.com/ajax/libs/jquery/1.8.0/jquery.min.js" type="text/javascript"></script>
{% endblock jquery %}

3.6.2 Обработка медиа

Если ваш плагин зависит от конкретных медиа файлов, джаваскриптов или стилей, вы можете добавить их из шаблона вашего плагина используя django-sekizai. Ваши шаблоны CMS всегда содержат css и js в пространстрве имен sekizai, таким образом они могут быть включены и использованы в соответствующих файлах. Больше информации можно найти в документации по sekizai.

Имейте в виду что sekizai не может вам помочь с шаблонами на стороне панели администратора. Отсюда следует что для ваших плагинов потребуются внешние шаблоны.

3.6.2.1 Стили sekizai

Чтобы использовать django-sekizai по полной, полезно иместь и использовать единый стиль. Вот надор соглашений которым надо стараться следовать (хотя и не обязательно):

  • Одна чатсь на addtoblock. Всегда включайте один внешний CSS или JS файл на addtoblock или один сниппет на addtoblock. Это необходимо чтобы django-sekizai корректно определял дублированные файлы

  • Внешние файлы должны занимать одну строку, без пробелов или переходов на новую строку между тэгами addtoblock и HTML тэгами.

  • Когда используется встроенный javascript или CSS, HTML тэги должны начинаться с новой строки.

Вот хороший пример:

{% load sekizai_tags %}
{% addtoblock "js" %}<script type="text/javascript" src="{{ MEDIA_URL }}myplugin/js/myjsfile.js"></script>{% endaddtoblock %}
{% addtoblock "js" %}<script type="text/javascript" src="{{ MEDIA_URL }}myplugin/js/myotherfile.js"></script>{% endaddtoblock %}
{% addtoblock "css" %}<link rel="stylesheet" type="text/css" href="{{ MEDIA_URL }}myplugin/css/astylesheet.css"></script>{% endaddtoblock %}
{% addtoblock "js" %}
<script type="text/javascript">
$(document).ready(function(){
doSomething();
});
</script>
{% endaddtoblock %}

А вот плохой пример:

{% load sekizai_tags %}
{% addtoblock "js" %}<script type="text/javascript" src="{{ MEDIA_URL }}myplugin/js/myjsfile.js"></script>
<script type="text/javascript" src="{{ MEDIA_URL }}myplugin/js/myotherfile.js"></script>{% endaddtoblock %}
{% addtoblock "css" %}
<link rel="stylesheet" type="text/css" href="{{ MEDIA_URL }}myplugin/css/astylesheet.css"></script>
{% endaddtoblock %}
{% addtoblock "js" %}<script type="text/javascript">
$(document).ready(function(){
doSomething();
});
</script>{% endaddtoblock %}

3.6.3. Контекст плагина

Плагин имеет доступ к контексту шаблонов django. Вы можете переписать переменные используя тэг with.

Пример:

{% with 320 as width %}{% placeholder "content" %}{% endwith %}

3.6.4. Обработчики контекста плагина

Обработчики контекстов плагина вызываемые, они модифицируют контекст плагина перед отрисовкой. Они используют настройку CMS_PLUGIN_CONTEXT_PROCESSORS.

Контекст процессор принимает 3 аргуметна:

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

  • placeholder: Экземпляр плейсхолдера в котором будет отрисован плагин

  • context: Используемый контекст, включая запрос.

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

Пример:

def add_verbose_name(instance, placeholder, context):
'''
This plugin context processor adds the plugin model's verbose_name to context.
'''
return {'verbose_name': instance._meta.verbose_name}

3.6.5. Процессор плагина

Плагин процессор, является вызываемым, который модифицирует весь вывод плагина после. Они используются в соответствии с настройкой CMS_PLUGIN_PROCESSORS.

Процессор плагина принимает 4 аргумента:

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

  • placeholder: Экземпляр плейсхолдера в котором будет отрисован плагин

  • rendered_content: Строка включающая отрисованное содержание плагина

  • original_context: Исходный контекст шаблона, который использует плагин.

Замечание

Процессоры плагинов также применяются в клагинам встроенные в плагины Text (и все вложенные пользовательские плагины). В зависимости от того какой вы используете плагин, он пожет прерыват вывод. Например, если ваш плагин встраивается в тэг div, может получиться так, что div окажется внутри тэга p, что является некорректным. Вы можете предотвратить это возвращая rendered_content неизмененным если настройка instance._render_meta.text_enabled установлена в True, что является случаем, когда плагин встраиваемый.

3.6.5.1 Пример

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

В файле settings.py:

CMS_PLUGIN_PROCESSORS = (
'yourapp.cms_plugin_processors.wrap_in_colored_box',
)

В файле yourapp.cms_plugin_processors.py:

def wrap_in_colored_box(instance, placeholder, rendered_content, original_context):
'''
This plugin processor wraps each plugin's output in a colored box if it is in the "main" placeholder.
'''
# Плагины вне основного плейсхолдера должны оставаться неизменными
# Плагины встроенные в Text должны оставаться неизменными, чтобы они не прервали вывод
if placeholder.slot != 'main' or (instance._render_meta.text_enabled and instance.parent):
return rendered_content
else:
from django.template import Context, Template
# Для простоты, создадим плагин из строки
t = Template('<div style="border: 10px {{ border_color }} solid; background: {{ background_color }};">{{ content|safe }}</div>')
# Prepare that template's context:
c = Context({
'content': rendered_content,
# Некоторые модели плагинов могут позвалить вам изменять цвет,
# для остальных используем цвет по умочанию
'background_color': instance.background_color if hasattr(instance, 'background_color') else 'lightyellow',
'border_color': instance.border_color if hasattr(instance, 'border_color') else 'lightblue',
})
# Наконец можем отрисовать содержания используя шаблон и возвращая вывод
return t.render(c)

3.6.6. Вложенные шаблоны

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

models.py:

class ParentPlugin(CMSPlugin):
# add your fields here
class ChildPlugin(CMSPlugin):
# add your fields here

cms_plugins.py:

from .models import ParentPlugin, ChildPlugin
class ParentCMSPlugin(CMSPluginBase):
render_template = 'parent.html'
name = 'Parent'
model = ParentPlugin
allow_children = True # This enables the parent plugin to accept child plugins
# child_classes = ['ChildCMSPlugin'] # Вы так же можете указать список плагинов, которые принимаются в качестве детей, или оставить пустой, чтобы принять все
def render(self, context, instance, placeholder):
context['instance'] = instance
return context
plugin_pool.register_plugin(ParentCMSPlugin)
class ChildCMSPlugin(CMSPluginBase):
render_template = 'child.html'
name = 'Child'
model = ChildPlugin
require_parent = True # Is it required that this plugin is a child of another plugin?
# parent_classes = ['ParentCMSPlugin'] # Вы так же можете указать список плагинов, которые принимаются в качестве родителей, или оставить пустой, чтобы принять все
def render(self, context, instance, placeholder):
context['instance'] = instance
return context
plugin_pool.register_plugin(ChildCMSPlugin)

parent.html:

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

3.7. Атрибуты CMSPluginBase и методы ссылок

Есть список атрибутов и методов которые могут (или должны) быть переопределены в определении Вашего плагина.

3.7.1. Атрибуты

3.7.1.1. admin_preview

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

Должен ли плагин быть показан администратору когда вы нажимаете на плагин или сохранить?

3.7.1.2. allow_children

Может ли плагин иметь детей? Или остальные плагины будут размещаться внутри этого плагина? Если установлено в 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 %}.

3.7.1.3. cache

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

Является ли плагин кэшируемым? Если ваш плагин показывает содержание основанное на пользователе или запросе или другие динамические свойства то надо установить значение в False

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

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

3.7.1.4. 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.

3.7.1.5. child_classes

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

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

Смотрите также parent_classes

3.7.1.6. disable_child_plugins

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

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

3.7.1.7. frontend_edit_template

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

Шаблон испольуемый в качестве обертки при редактировании на стороне клиента

Смотрите также change_form_template

3.7.1.8. model

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

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

Смотрите также Сохранение конфигурации

3.7.1.9. page_only

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

Указывает может ли этот плагин быть привязан к плейсхолдеру или только к странице. Установите в True если вам надо встраивать плагин только в страницу

Смотрите также child_classes, parent_classes, require_parent

3.7.1.10. parent_classes

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

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

Смотрите также child_classes, require_parent

3.7.1.11. render_plugin

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

Должен ли плагин отрисовываться или у него нет выходных данных. Если установлени в True, то надо указать render_template

Смотрите также: render_template

3.7.1.11.1. render_template

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

Путь к шаблону который должен быть использован при отрисовке. Значение требуется если render_plugin установлено в True.

Смотрите также: render_plugin

3.7.1.12. require_parent

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

Может ли этот плагин быть ребенком другого плагина. Или может ли он быть дабавлен в какой-то плейсхолдер, и даже прикреплен к странице

Смотрите также: child_classes, parent_classes

3.7.1.13. text_enabled

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

Может ли этот плагин быть вставлен в текстовый плагин. Если установен в True то icon_src() должна быть переопределена.

Смотрите также icon_src, icon_alt

3.7.2. Методы

3.7.2.1. icon_src

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

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

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

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

Пример:

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

Смотрите также: text_enabled, icon_alt

3.7.2.2. icon_alt

Хотя он и не обязателен, авторы плагина "text enabled" должны также переопределить эту функцию.

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

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

icon_alt принимает один аргумент

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

Определение функции по умолчанию следующее:

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

Смотрите также: text_enabled, icon_src

3.8 Атрибуты и метода CMSPlugin

Вот список атрибутов и методов которые могут (или должны) быть переопределены при объявлении модели плагина.

Смотрите также Сохранение конфигурации

3.8.1. Атрибуты

3.8.1.1. translatable_content_excluded_fields

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

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

Смотрите также: get_translatable_content, set_translatable_content

3.8.2. Методы

3.8.2.1. copy_relations

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

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

  • old_instance: Экземпляр объекта испольуемый в качестве источника.

3.8.2.2. get_translatable_content

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

Пример:

from djangocms_text_ckeditor.models import Text
plugin = Text.objects.get(pk=1).get_plugin_instance()[0]
plugin.get_translatable_content()
# Возвращает {'body': u'<p>I am text!</p>\n'}

Сотрите также: translatable_content_excluded_fields, set_translatable_content

3.8.2.3. post_copy

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

post_copy принимает два параметра:

  • old_instance Эксземпляр старого плагина

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

Смотрите также: Handling Relations, copy_relations

3.8.2.4. set_translatable_content

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

set_translatable_content принимает один аргумент

  • fields: Словарь содержащий список полей и его соответствующее значение

Пример:

from djangocms_text_ckeditor.models import Text
plugin = Text.objects.get(pk=1).get_plugin_instance()[0]
plugin.set_translatable_content({'body': u'<p>This is a different text!</p>\n'})
# Возвращает True

Смотрите также: translatable_content_excluded_fields, get_translatable_content


Оставьте свой комментарий

comments powered by Disqus
Меню

Cult of digits 2014 Яндекс.Метрика