Настройки сайта

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

Чтобы использовать эти настройки, необходимо добавить wagtail.contrib.settings в свой INSTALLED_APPS:

INSTALLED_APPS += [
    'wagtail.contrib.settings',
]

Определение настроек

Создайте модель, которая наследуется от BaseSetting, и зарегистрируйте её с помощью декоратора register_setting:

from django.db import models
from wagtail.contrib.settings.models import BaseSetting, register_setting

@register_setting
class SocialMediaSettings(BaseSetting):
    facebook = models.URLField(
        help_text='Your Facebook page URL')
    instagram = models.CharField(
        max_length=255, help_text='Your Instagram username, without the @')
    trip_advisor = models.URLField(
        help_text='Your Trip Advisor page URL')
    youtube = models.URLField(
        help_text='Your YouTube channel or user account URL')

Ссылка «Настройки социальных сетей» появится в меню «Настройки» админ-панели Wagtail.

Обработчики редактирования

Настройки используют обработчики редактирования, как и в других частях Wagtail. Добавьте настройку panels в вашу модель, определяющую все необходимые обработчики редактирования:

@register_setting
class ImportantPages(BaseSetting):
    donate_page = models.ForeignKey(
        'wagtailcore.Page', null=True, on_delete=models.SET_NULL, related_name='+')
    sign_up_page = models.ForeignKey(
        'wagtailcore.Page', null=True, on_delete=models.SET_NULL, related_name='+')

    panels = [
        PageChooserPanel('donate_page'),
        PageChooserPanel('sign_up_page'),
    ]

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

from wagtail.admin.edit_handlers import TabbedInterface, ObjectList

@register_setting
class MySettings(BaseSetting):
    # ...
    first_tab_panels = [
        FieldPanel('field_1'),
    ]
    second_tab_panels = [
        FieldPanel('field_2'),
    ]

    edit_handler = TabbedInterface([
        ObjectList(first_tab_panels, heading='First tab'),
        ObjectList(second_tab_panels, heading='Second tab'),
    ])

Внешний вид

Вы можете изменить метку, используемую в меню, изменив verbose_name вашей модели.

Вы можете добавить значок в меню, передав аргумент ‘icon’ в декоратор register_setting:

@register_setting(icon='placeholder')
class SocialMediaSettings(BaseSetting):
    class Meta:
        verbose_name = 'social media accounts'
    ...

Список всех доступных значков см. в Руководстве по стилю пользовательского интерфейса.

Использование настроек

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

Использование в Python

Если вам нужен доступ к настройке в представлении, метод for_request() позволяет получить соответствующие настройки для текущего запроса:

def view(request):
    social_media_settings = SocialMediaSettings.for_request(request)
    ...

В тех местах, где запрос недоступен, но вы знаете Site, для которого хотите получить настройки, вы можете использовать for_site() вместо этого:

social_media_settings =  SocialMediaSettings.for_site(user.origin_site)

Использование в Django-шаблонах

Добавьте обработчик контекста settings в ваши настройки:

TEMPLATES = [
    {
        ...

        'OPTIONS': {
            'context_processors': [
                ...

                'wagtail.contrib.settings.context_processors.settings',
            ]
        }
    }
]

Затем обратитесь к настройкам через {{ settings }}:

{{ settings.app_label.SocialMediaSettings.instagram }}

Если вы не в RequestContext, тогда обработчики контекста не будут выполнены, и переменная settings не будет доступна. Чтобы получить settings, используйте предоставленный тег шаблона {% get_settings %}. Если request находится в контексте шаблона, но по какой-то причине это не RequestContext, просто используйте {% get_settings %}:

{% load wagtailsettings_tags %}
{% get_settings %}
{{ settings.app_label.SocialMediaSettings.instagram }}

Если в шаблоне вообще нет request, вы можете использовать настройки для сайта Wagtail по умолчанию:

{% load wagtailsettings_tags %}
{% get_settings use_default_site=True %}
{{ settings.app_label.SocialMediaSettings.instagram }}

По умолчанию тег создаст или обновит переменную settings в контексте. Если вы хотите назначить переменную другому контексту, используйте {% get_settings as other_variable_name %}:

{% load wagtailsettings_tags %}
{% get_settings as wagtail_settings %}
{{ wagtail_settings.app_label.SocialMediaSettings.instagram }}

Использование в Jinja2-шаблонах

Добавьте расширение wagtail.contrib.settings.jinja2tags.settings в свои настройки Jinja2:

TEMPLATES = [
    # ...
    {
        'BACKEND': 'django.template.backends.jinja2.Jinja2',
        'APP_DIRS': True,
        'OPTIONS': {
            'extensions': [
                # ...
                'wagtail.contrib.settings.jinja2tags.settings',
            ],
        },
    }
]

Затем обратитесь к настройкам через функцию шаблона settings():

{{ settings("app_label.SocialMediaSettings").twitter }}

Это будет искать переменную request в контексте шаблона и определять правильный сайт для использования. Если по какой-то причине у вас нет request, вы можете вместо этого использовать настройки, определённые для сайта по умолчанию:

{{ settings("app_label.SocialMediaSettings", use_default_site=True).instagram }}

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

{% with social_settings=settings("app_label.SocialMediaSettings") %}
    Follow us on Twitter at @{{ social_settings.twitter }},
    or Instagram at @{{ social_settings.instagram }}.
{% endwith %}

Или, как альтернатива, используйте тег set:

{% set social_settings=settings("app_label.SocialMediaSettings") %}

Использование select_related для повышения эффективности

Для моделей с отношениями «многие ко многим» к другим объектам (например, страницам), которые часто необходимы для вывода значений в шаблонах, вы можете установить атрибут select_related в своей модели, чтобы Wagtail использовал метод Django QuerySet.select_related() для получения объекта настроек и связанных объектов в одном запросе. С этим начальный запрос будет более сложным, но вы сможете свободно получать значения внешнего ключа без дополнительных запросов, что в целом повысит эффективность.

Продолжая пример ImportantPages из предыдущего раздела, ниже показано, как установить select_related для повышения эффективности:

@register_setting
class ImportantPages(BaseSetting):

    # Fetch these pages when looking up ImportantPages for or a site
    select_related = ["donate_page", "sign_up_page"]

    donate_page = models.ForeignKey(
        'wagtailcore.Page', null=True, on_delete=models.SET_NULL, related_name='+')
    sign_up_page = models.ForeignKey(
        'wagtailcore.Page', null=True, on_delete=models.SET_NULL, related_name='+')

    panels = [
        PageChooserPanel('donate_page'),
        PageChooserPanel('sign_up_page'),
    ]

С этими дополнениями следующий код шаблона теперь вызовет один запрос к базе данных вместо трёх (один для получения настроек и ещё два для получения каждой страницы):

{% load wagtailcore_tags %}
{% pageurl settings.app_label.ImportantPages.donate_page %}
{% pageurl settings.app_label.ImportantPages.sign_up_page %}

Использование сокращения настроек page_url

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

{% load wagtailcore_tags %}
{% pageurl settings.app_label.ImportantPages.donate_page %}
{% pageurl settings.app_label.ImportantPages.sign_up_page %}

Вы могли бы написать:

{{ settings.app_label.ImportantPages.page_url.donate_page }}
{{ settings.app_label.ImportantPages.page_url.sign_up_page }}

Использование сокращения page_url имеет несколько преимуществ по сравнению с использованием тега:

1. Страница «конкретная» автоматически извлекается для генерации URL, поэтому вам не нужно беспокоиться об этом (или забывать об этом) самим.
2. Результаты кэшируются, поэтому если вам нужно получить тот же URL страницы в нескольких местах (например, в форме и в навигации подвала), использование сокращения page_url будет более эффективным.
3. Это более лаконично, и синтаксис одинаков, будь то в шаблонах, представлениях (или другом коде Python), что позволяет писать более согласованный код.

При использовании сокращения page_url стоит обратить внимание на несколько моментов:

1. Те же ограничения, что и у тега {% pageurl %} , применяются к сокращению: Если настройки получаются из контекста шаблона, где текущий запрос недоступен, все возвращаемые URL будут содержать схему/домен сайта, а генерация URL не будет такой эффективной.
2. Если вы используете сокращение в представлениях или другом Python-коде, метод вызовет AttributeError , если запрашиваемый атрибут из page_url не является атрибутом объекта настроек.
3. Если объект настроек ИМЕТЬ атрибут, но атрибут возвращает значение None (или что-то, что не является Page), сокращение вернёт пустую строку.