Ресурсы формы (класс Media)

css

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

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

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

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

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

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 не равна None, и автоматически перейдёт к использованию 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 равен 'https://static.example.com/':

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