Активности форм (класс Media)

css

Словарь, описывающий необходимые CSS-файлы для различных типов выходных медиа.

Значения в словаре должны быть кортежами/списками имён файлов. Подробности о том, как указать пути к этим файлам, см. в разделе пути.

Ключами в словаре являются типы выходных медиа. Это те же типы, которые принимаются CSS-файлами в объявлениях медиа: ‘all’, ‘aural’, ‘braille’, ‘embossed’, ‘handheld’, ‘print’, ‘projection’, ‘screen’, ‘tty’ и ‘tv’. Если вам нужны разные таблицы стилей для разных типов медиа, укажите список CSS-файлов для каждого типа выходных медиа. Следующий пример предоставит два варианта CSS — один для экрана и один для печати:

class Media:
    css = {
        "screen": ["pretty.css"],
        "print": ["newspaper.css"],
    }

Если группа CSS-файлов подходит для нескольких типов выходных медиа, ключ словаря может быть списком типов выходных медиа, разделённых запятыми. В следующем примере TV и проекторы будут иметь одинаковые требования к медиа:

class Media:
    css = {
        "screen": ["pretty.css"],
        "tv,projector": ["lo_res.css"],
        "print": ["newspaper.css"],
    }

Если это последнее определение CSS будет визуализировано, оно преобразуется в следующий HTML:

<link href="https://static.example.com/pretty.css" media="screen" rel="stylesheet">
<link href="https://static.example.com/lo_res.css" media="tv,projector" rel="stylesheet">
<link href="https://static.example.com/newspaper.css" media="print" rel="stylesheet">

js

Кортеж, описывающий необходимые JavaScript-файлы. Подробности о том, как указать пути к этим файлам, см. в разделе пути.

extend

Булево значение, определяющее поведение наследования для Media деклараций.

По умолчанию любой объект, использующий статическое Media определение, будет унаследовать все активы, связанные с родительским виджетом. Это происходит независимо от того, как родительский виджет определяет свои собственные требования. Например, если мы расширим наш базовый виджет Calendar из примера выше:

>>> class FancyCalendarWidget(CalendarWidget):
...     class Media:
...         css = {
...             "all": ["fancy.css"],
...         }
...         js = ["whizbang.js"]
...

>>> w = FancyCalendarWidget()
>>> print(w.media)
<link href="https://static.example.com/pretty.css" media="all" rel="stylesheet">
<link href="https://static.example.com/fancy.css" media="all" rel="stylesheet">
<script src="https://static.example.com/animations.js"></script>
<script src="https://static.example.com/actions.js"></script>
<script src="https://static.example.com/whizbang.js"></script>

Виджет FancyCalendar наследует все активы от родительского виджета. Если вы не хотите, чтобы Media наследовались таким образом, добавьте декларацию extend=False в декларацию Media:

>>> class FancyCalendarWidget(CalendarWidget):
...     class Media:
...         extend = False
...         css = {
...             "all": ["fancy.css"],
...         }
...         js = ["whizbang.js"]
...

>>> w = FancyCalendarWidget()
>>> print(w.media)
<link href="https://static.example.com/fancy.css" media="all" rel="stylesheet">
<script src="https://static.example.com/whizbang.js"></script>

Если вам нужен ещё больший контроль над наследованием, определите свои активы, используя динамическое свойство. Динамические свойства обеспечивают полный контроль над тем, какие файлы наследуются, а какие — нет.

Пути как строки

Строковые пути, используемые для указания активностей, могут быть относительными или абсолютными. Если путь начинается с /, http:// или https://, он будет интерпретирован как абсолютный путь и оставлен в первоначальном виде. Все остальные пути будут дополнены значением соответствующего префикса. Если приложение django.contrib.staticfiles установлено, оно будет использоваться для обслуживания активностей.

Используете ли вы django.contrib.staticfiles или нет, настройки STATIC_URL и STATIC_ROOT необходимы для визуализации полной веб-страницы.

Для определения соответствующего префикса Django проверяет, не является ли настройка STATIC_URL пустой, и в противном случае автоматически использует MEDIA_URL. Например, если MEDIA_URL для вашего сайта была 'https://uploads.example.com/', а STATIC_URL была None:

>>> from django import forms
>>> class CalendarWidget(forms.TextInput):
...     class Media:
...         css = {
...             "all": ["/css/pretty.css"],
...         }
...         js = ["animations.js", "https://othersite.com/actions.js"]
...

>>> w = CalendarWidget()
>>> print(w.media)
<link href="/css/pretty.css" media="all" rel="stylesheet">
<script src="https://uploads.example.com/animations.js"></script>
<script src="https://othersite.com/actions.js"></script>

Но если STATIC_URL пуста:

>>> w = CalendarWidget()
>>> print(w.media)
<link href="/css/pretty.css" media="all" rel="stylesheet">
<script src="https://static.example.com/animations.js"></script>
<script src="https://othersite.com/actions.js"></script>

Или если staticfiles настроено с помощью ManifestStaticFilesStorage:

>>> w = CalendarWidget()
>>> print(w.media)
<link href="/css/pretty.css" media="all" rel="stylesheet">
<script src="https://static.example.com/animations.27e20196a850.js"></script>
<script src="https://othersite.com/actions.js"></script>

Пути как объекты

Активности также могут быть объектно-ориентированными, используя Script. Кроме того, это позволяет передавать настраиваемые HTML-атрибуты:

class Media:
    js = [
        Script(
            "https://cdn.example.com/something.min.js",
            **{
                "crossorigin": "anonymous",
                "async": True,
            },
        ),
    ]

Если это определение Media будет визуализировано, оно преобразуется в следующий HTML:

<script src="https://cdn.example.com/something.min.js"
        crossorigin="anonymous"
        async>
</script>

Подмножества ресурсов

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

>>> w = CalendarWidget()
>>> print(w.media)
<link href="https://static.example.com/pretty.css" media="all" rel="stylesheet">
<script src="https://static.example.com/animations.js"></script>
<script src="https://static.example.com/actions.js"></script>

>>> print(w.media["css"])
<link href="https://static.example.com/pretty.css" media="all" rel="stylesheet">

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

Объединение объектов Media

Объекты Media также можно складывать. При сложении двух объектов Media результирующий объект Media содержит объединение ресурсов, указанных в обоих объектах:

>>> from django import forms
>>> class CalendarWidget(forms.TextInput):
...     class Media:
...         css = {
...             "all": ["pretty.css"],
...         }
...         js = ["animations.js", "actions.js"]
...

>>> class OtherWidget(forms.TextInput):
...     class Media:
...         js = ["whizbang.js"]
...

>>> w1 = CalendarWidget()
>>> w2 = OtherWidget()
>>> print(w1.media + w2.media)
<link href="https://static.example.com/pretty.css" media="all" rel="stylesheet">
<script src="https://static.example.com/animations.js"></script>
<script src="https://static.example.com/actions.js"></script>
<script src="https://static.example.com/whizbang.js"></script>

Порядок ресурсов

Порядок вставки ресурсов в DOM часто важен. Например, у вас может быть скрипт, зависящий от jQuery. Поэтому при объединении объектов Media сохраняется относительный порядок, в котором ресурсы определены в каждом классе Media.

Например:

>>> from django import forms
>>> class CalendarWidget(forms.TextInput):
...     class Media:
...         js = ["jQuery.js", "calendar.js", "noConflict.js"]
...
>>> class TimeWidget(forms.TextInput):
...     class Media:
...         js = ["jQuery.js", "time.js", "noConflict.js"]
...
>>> w1 = CalendarWidget()
>>> w2 = TimeWidget()
>>> print(w1.media + w2.media)
<script src="https://static.example.com/jQuery.js"></script>
<script src="https://static.example.com/calendar.js"></script>
<script src="https://static.example.com/time.js"></script>
<script src="https://static.example.com/noConflict.js"></script>

Объединение объектов Media с ресурсами в конфликтующем порядке приводит к возникновению MediaOrderConflictWarning.