Как создавать плагины¶

Работа с отношениями¶

Каждый раз, когда страница с вашим пользовательским плагином публикуется, плагин копируется. Поэтому, если ваш пользовательский плагин имеет внешний ключ (к нему или от него) или отношения «многие-ко-многим», вы несете ответственность за копирование этих связанных объектов, если это необходимо, каждый раз, когда CMS копирует плагин - он не будет делать это за вас автоматически.

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

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

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

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

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

class AssociatedItem(models.Model):
    plugin = models.ForeignKey(
        ArticlePluginModel,
        related_name="associated_item"
    )

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

    def copy_relations(self, oldinstance):
        # Before copying related objects from the old instance, the ones
        # on the current one need to be deleted. Otherwise, duplicates may
        # appear on the public version of the page
        self.associated_item.all().delete()

        for associated_item in oldinstance.associated_item.all():
            # instance.pk = None; instance.pk.save() is the slightly odd but
            # standard Django way of copying a saved model instance
            associated_item.pk = None
            associated_item.plugin = self
            associated_item.save()

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

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

    def copy_relations(self, oldinstance):
        self.sections.set(oldinstance.sections.all())

Встроенный администратор¶

Если вы хотите иметь отношение внешнего ключа как встроенную админку, вы можете создать класс admin.StackedInline и поместить его в Plugin в «inlines». Тогда вы сможете использовать форму inline admin для ваших ссылок на внешний ключ:

class ItemInlineAdmin(admin.StackedInline):
    model = AssociatedItem


class ArticlePlugin(CMSPluginBase):
    model = ArticlePluginModel
    name = _("Article Plugin")
    render_template = "article/index.html"
    inlines = (ItemInlineAdmin,)

    def render(self, context, instance, placeholder):
        context = super().render(context, instance, placeholder)
        items = instance.associated_item.all()
        context.update({
            'items': items,
        })
        return context

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

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

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

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

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

• снабдите ваш подкласс cms.plugin_base.CMSPluginBase атрибутом change_form_template, указывающим на ваш новый шаблон.

Расширение admin/cms/page/plugin/change_form.html гарантирует, что вы сохраните единый внешний вид и функциональность всех ваших плагинов.

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

Работа со средствами массовой информации¶

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

Обратите внимание, что sekizai не может помочь вам с шаблонами плагинов со стороны администратора - то, что написано ниже, относится к шаблонам вывода ваших плагинов.

{% 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">{% 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 %}

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

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

Пример:

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

Контекстные процессоры плагинов¶

Контекстные процессоры плагинов - это вызываемые переменные, которые изменяют контекст всех плагинов перед рендерингом. Они включаются с помощью параметра 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}

Процессоры плагинов¶

Процессоры плагинов - это вызываемые переменные, которые изменяют вывод всех плагинов после рендеринга. Они включаются с помощью параметра CMS_PLUGIN_PROCESSORS.

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

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

• placeholder: экземпляр плейсхолдера, в котором появляется этот плагин.

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

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

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

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.
    '''
    # Plugins not in the main placeholder should remain unchanged
    # Plugins embedded in Text should remain unchanged in order not to break output
    if placeholder.slot != 'main' or (instance._render_meta.text_enabled and instance.parent):
        return rendered_content
    else:
        from django.template import Context, Template
        # For simplicity's sake, construct the template from a string:
        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,
            # Some plugin models might allow you to customise the colors,
            # for others, use default colors:
            'background_color': instance.background_color if hasattr(instance, 'background_color') else 'lightyellow',
            'border_color': instance.border_color if hasattr(instance, 'border_color') else 'lightblue',
        })
        # Finally, render the content through that template, and return the output
        return t.render(c)

Вложенные плагины¶

Вы можете вложить плагины 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

@plugin_pool.register_plugin
class ParentCMSPlugin(CMSPluginBase):
    render_template = 'parent.html'
    name = 'Parent'
    model = ParentPlugin
    allow_children = True  # This enables the parent plugin to accept child plugins
    # You can also specify a list of plugins that are accepted as children,
    # or leave it away completely to accept all
    # child_classes = ['ChildCMSPlugin']

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


@plugin_pool.register_plugin
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?
    # You can also specify a list of plugins that are accepted as parents,
    # or leave it away completely to accept all
    # parent_classes = ['ParentCMSPlugin']

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

parent.html:

{% load cms_tags %}

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

child.html:

<div class="plugin child">
    {{ instance }}
</div>

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

class ChildPluginForm(forms.ModelForm):

    class Meta:
        model = ChildPlugin
        exclude = ()

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        if self.instance:
            parent, parent_cls = self.instance.parent.get_bound_plugin()

Расширение контекстных меню заполнителей или плагинов¶

Существует три возможности расширения контекстных меню заполнителей или плагинов.

• Вы можете либо расширить контекстное меню.

• Вы можете расширить контекстные меню всех плагинов.

• Вы можете расширить текущее контекстное меню плагина.

Для этого вы можете переписать 3 метода на CMSPluginBase.

• get_extra_placeholder_menu_items()

• get_extra_global_plugin_menu_items()

• get_extra_local_plugin_menu_items()

Пример:

class AliasPlugin(CMSPluginBase):
    name = _("Alias")
    allow_children = False
    model = AliasPluginModel
    render_template = "cms/plugins/alias.html"

    def render(self, context, instance, placeholder):
        context = super().render(context, instance, placeholder)
        if instance.plugin_id:
            plugins = instance.plugin.get_descendants(
                include_self=True
            ).order_by('placeholder', 'tree_id', 'level', 'position')
            plugins = downcast_plugins(plugins)
            plugins[0].parent_id = None
            plugins = build_plugin_tree(plugins)
            context['plugins'] = plugins
        if instance.alias_placeholder_id:
            content = render_placeholder(instance.alias_placeholder, context)
            print content
            context['content'] = mark_safe(content)
        return context

    def get_extra_global_plugin_menu_items(self, request, plugin):
        return [
            PluginMenuItem(
                _("Create Alias"),
                reverse("admin:cms_create_alias"),
                data={
                    'plugin_id': plugin.pk,
                    'csrfmiddlewaretoken': get_token(request)
                },
            )
        ]

    def get_extra_placeholder_menu_items(self, request, placeholder):
        return [
            PluginMenuItem(
                _("Create Alias"),
                reverse("admin:cms_create_alias"),
                data={
                    'placeholder_id': placeholder.pk,
                    'csrfmiddlewaretoken': get_token(request)
                },
            )
        ]

    def get_plugin_urls(self):
        urlpatterns = [
            re_path(r'^create_alias/$', self.create_alias, name='cms_create_alias'),
        ]
        return urlpatterns

    def create_alias(self, request):
        if not request.user.is_staff:
            return HttpResponseForbidden("not enough privileges")
        if not 'plugin_id' in request.POST and not 'placeholder_id' in request.POST:
            return HttpResponseBadRequest(
                "plugin_id or placeholder_id POST parameter missing."
            )
        plugin = None
        placeholder = None
        if 'plugin_id' in request.POST:
            pk = request.POST['plugin_id']
            try:
                plugin = CMSPlugin.objects.get(pk=pk)
            except CMSPlugin.DoesNotExist:
                return HttpResponseBadRequest(
                    "plugin with id %s not found." % pk
                )
        if 'placeholder_id' in request.POST:
            pk = request.POST['placeholder_id']
            try:
                placeholder = Placeholder.objects.get(pk=pk)
            except Placeholder.DoesNotExist:
                return HttpResponseBadRequest(
                    "placeholder with id %s not found." % pk
                )
            if not placeholder.has_change_permission(request):
                return HttpResponseBadRequest(
                    "You do not have enough permission to alias this placeholder."
                )
        clipboard = request.toolbar.clipboard
        clipboard.cmsplugin_set.all().delete()
        language = request.LANGUAGE_CODE
        if plugin:
            language = plugin.language
        alias = AliasPluginModel(
            language=language, placeholder=clipboard,
            plugin_type="AliasPlugin"
        )
        if plugin:
            alias.plugin = plugin
        if placeholder:
            alias.alias_placeholder = placeholder
        alias.save()
        return HttpResponse("ok")

Миграция данных плагина¶

В связи с миграцией с Django MPTT на django-treebeard в версии 3.1, модель плагинов отличается между двумя версиями. Миграции схем не затрагиваются, так как системы миграции (как South, так и Django) обнаруживают различные базы.

Однако миграция данных - это совсем другая история.

Если ваша миграция данных делает что-то вроде:

MyPlugin = apps.get_model('my_app', 'MyPlugin')

for plugin in MyPlugin.objects.all():
    ... do something ...

В итоге вы можете получить ошибку типа django.db.utils.OperationalError: (1054, "Unknown column 'cms_cmsplugin.level' in 'field list'"), поскольку в зависимости от порядка выполнения миграций исторические модели могут быть рассинхронизированы с применяемой схемой базы данных.

Для сохранения совместимости с 3.0 и 3.x вы можете заставить миграцию данных выполняться до миграции django CMS, которая создает поля treebeard, при этом миграция данных всегда будет выполняться на «старой» схеме базы данных, и конфликтов не будет.

Для южных миграций добавьте следующее:

from distutils.version import LooseVersion
import cms
USES_TREEBEARD = LooseVersion(cms.__version__) >= LooseVersion('3.1')

class Migration(DataMigration):

    if USES_TREEBEARD:
        needed_by = [
            ('cms', '0070_auto__add_field_cmsplugin_path__add_field_cmsplugin_depth__add_field_c')
        ]

Для миграций Django добавьте следующее:

from distutils.version import LooseVersion
import cms
USES_TREEBEARD = LooseVersion(cms.__version__) >= LooseVersion('3.1')

class Migration(migrations.Migration):

    if USES_TREEBEARD:
        run_before = [
            ('cms', '0004_auto_20140924_1038')
        ]