フォームアセット（メディアクラス）—Djangoドキュメント

フォームアセット（Mediaクラス）

魅力的で使いやすいWebフォームをレンダリングするには、HTMLだけでなく、CSSスタイルシートも必要です。また、派手な「Web2.0」ウィジェットを使用する場合は、各ページにJavaScriptを含める必要があります。 特定のページに必要なCSSとJavaScriptの正確な組み合わせは、そのページで使用されているウィジェットによって異なります。

これが資産定義の出番です。 Djangoを使用すると、スタイルシートやスクリプトなどのさまざまなファイルを、それらのアセットを必要とするフォームやウィジェットに関連付けることができます。 たとえば、カレンダーを使用してDateFieldsをレンダリングする場合は、カスタムカレンダーウィジェットを定義できます。 このウィジェットは、カレンダーのレンダリングに必要なCSSおよびJavaScriptに関連付けることができます。 カレンダーウィジェットをフォームで使用すると、Djangoは必要なCSSファイルとJavaScriptファイルを識別し、Webページに簡単に含めるのに適したフォームでファイル名のリストを提供できます。

アセットとDjango管理者

Django Adminアプリケーションは、カレンダー、フィルターされた選択などのためにカスタマイズされたウィジェットの数を定義します。 これらのウィジェットはアセット要件を定義し、Django管理者はDjangoのデフォルトの代わりにカスタムウィジェットを使用します。 管理テンプレートには、特定のページでウィジェットをレンダリングするために必要なファイルのみが含まれます。

Django Adminアプリケーションが使用するウィジェットが気に入った場合は、独自のアプリケーションで自由に使用してください。 それらはすべてdjango.contrib.admin.widgetsに保存されます。

どのJavaScriptツールキットですか？

多くのJavaScriptツールキットが存在し、それらの多くには、アプリケーションを拡張するために使用できるウィジェット（カレンダーウィジェットなど）が含まれています。 Djangoは、JavaScriptツールキットを1つでも祝福することを意図的に避けています。 各ツールキットには、独自の相対的な長所と短所があります。要件に合ったツールキットを使用してください。 Djangoは任意のJavaScriptツールキットと統合できます。

静的定義としての資産

アセットを定義する最も簡単な方法は、静的定義としてです。 このメソッドを使用すると、宣言は内部Mediaクラスになります。 内部クラスのプロパティは要件を定義します。

簡単な例を次に示します。

from django import forms

class CalendarWidget(forms.TextInput):
    class Media:
        css = {
            'all': ('pretty.css',)
        }
        js = ('animations.js', 'actions.js')

Copy

このコードは、TextInputに基づくCalendarWidgetを定義します。 CalendarWidgetがフォームで使用されるたびに、そのフォームはCSSファイルpretty.css、およびJavaScriptファイルanimations.jsとactions.jsを含むように指示されます。

この静的定義は、実行時にmediaという名前のウィジェットプロパティに変換されます。 CalendarWidgetインスタンスのアセットのリストは、次のプロパティから取得できます。

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

Copy

可能なすべてのMediaオプションのリストを次に示します。 必須のオプションはありません。

css

さまざまな形式の出力メディアに必要なCSSファイルを説明する辞書。

ディクショナリの値は、ファイル名のタプル/リストである必要があります。 これらのファイルへのパスを指定する方法の詳細については、パスに関するセクションを参照してください。

辞書のキーは出力メディアタイプです。 これらは、メディア宣言でCSSファイルによって受け入れられるのと同じタイプです：「all」、「aural」、「braille」、「embossed」、「handheld」、「print」、「projection」、「screen」、「tty」、および「テレビ'。 メディアタイプごとに異なるスタイルシートが必要な場合は、出力メディアごとにCSSファイルのリストを提供してください。 次の例では、2つのCSSオプションを提供します。1つは画面用、もう1つは印刷用です。

class Media:
    css = {
        'screen': ('pretty.css',),
        'print': ('newspaper.css',)
    }

Copy

CSSファイルのグループが複数の出力メディアタイプに適している場合、ディクショナリキーは出力メディアタイプのコンマ区切りのリストにすることができます。 次の例では、テレビとプロジェクターのメディア要件は同じです。

class Media:
    css = {
        'screen': ('pretty.css',),
        'tv,projector': ('lo_res.css',),
        'print': ('newspaper.css',)
    }

Copy

この最後のCSS定義をレンダリングすると、次のHTMLになります。

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

Copy

js

必要なJavaScriptファイルを説明するタプル。 これらのファイルへのパスを指定する方法の詳細については、パスに関するセクションを参照してください。

extend

Media宣言の継承動作を定義するブール値。

デフォルトでは、静的Media定義を使用するオブジェクトは、親ウィジェットに関連付けられているすべてのアセットを継承します。 これは、親が独自の要件をどのように定義しているかに関係なく発生します。 たとえば、上記の例から基本的なカレンダーウィジェットを拡張する場合：

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

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

Copy

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="http://static.example.com/fancy.css" type="text/css" media="all" rel="stylesheet">
<script type="text/javascript" src="http://static.example.com/whizbang.js"></script>

Copy

継承をさらに制御する必要がある場合は、動的プロパティを使用してアセットを定義してください。 動的プロパティを使用すると、継承するファイルと継承しないファイルを完全に制御できます。

動的プロパティとしてのMedia

アセット要件のより高度な操作を実行する必要がある場合は、mediaプロパティを直接定義できます。 これは、forms.Mediaのインスタンスを返すウィジェットプロパティを定義することによって行われます。 forms.Mediaのコンストラクターは、静的メディア定義で使用されているものと同じ形式のcssおよびjsキーワード引数を受け入れます。

たとえば、カレンダーウィジェットの静的定義は、動的な方法で定義することもできます。

class CalendarWidget(forms.TextInput):
    @property
    def media(self):
        return forms.Media(css={'all': ('pretty.css',)},
                           js=('animations.js', 'actions.js'))

Copy

動的mediaプロパティの戻り値を作成する方法の詳細については、メディアオブジェクトのセクションを参照してください。

アセット定義のパス

アセットを指定するために使用されるパスは、相対パスまたは絶対パスのいずれかです。 パスが/、http://、またはhttps://で始まる場合、絶対パスとして解釈され、そのままになります。 他のすべてのパスには、適切なプレフィックスの値が付加されます。 django.contrib.staticfiles アプリがインストールされている場合、アセットの提供に使用されます。

django.contrib.staticfiles を使用するかどうかに関係なく、完全にレンダリングするには、：setting： `STATIC_URL` および：setting：` STATIC_ROOT` 設定が必要です。ウェブページ。

使用する適切なプレフィックスを見つけるために、Djangoは：setting： `STATIC_URL` 設定がNoneでないかどうかを確認し、自動的に：setting：` MEDIA_URL` [の使用にフォールバックします。 X181X]。 たとえば、サイトの：setting： `MEDIA_URL` が'http://uploads.example.com/'で、：setting：` STATIC_URL` がNoneの場合：

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

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

Copy

ただし、：setting： `STATIC_URL` が'http://static.example.com/'の場合：

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

Copy

または、 staticfiles が ManifestStaticFilesStorage を使用して構成されている場合：

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

Copy

Mediaオブジェクト

ウィジェットまたはフォームのmedia属性を調べると、返される値はforms.Mediaオブジェクトです。 すでに見てきたように、Mediaオブジェクトの文字列表現は、HTMLページの<head>ブロックに関連ファイルを含めるために必要なHTMLです。

ただし、Mediaオブジェクトには他にもいくつかの興味深いプロパティがあります。

資産のサブセット

特定のタイプのファイルのみが必要な場合は、添え字演算子を使用して、対象のメディアを除外できます。 例えば：

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

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

Copy

添え字演算子を使用すると、返される値は新しいMediaオブジェクトですが、対象のメディアのみが含まれています。

Mediaオブジェクトの組み合わせ

Mediaオブジェクトを一緒に追加することもできます。 2つの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="http://static.example.com/pretty.css" type="text/css" media="all" rel="stylesheet">
<script type="text/javascript" src="http://static.example.com/animations.js"></script>
<script type="text/javascript" src="http://static.example.com/actions.js"></script>
<script type="text/javascript" src="http://static.example.com/whizbang.js"></script>

Copy

資産の順序

多くの場合、アセットが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 type="text/javascript" src="http://static.example.com/jQuery.js"></script>
<script type="text/javascript" src="http://static.example.com/calendar.js"></script>
<script type="text/javascript" src="http://static.example.com/time.js"></script>
<script type="text/javascript" src="http://static.example.com/noConflict.js"></script>

Copy

Mediaオブジェクトをアセットと競合する順序で組み合わせると、MediaOrderConflictWarningになります。

フォーム上のMedia

mediaの定義を持つことができるオブジェクトはウィジェットだけではありません–フォームはmediaを定義することもできます。 フォームのmedia定義の規則は、ウィジェットの規則と同じです。宣言は静的または動的にすることができます。 これらの宣言のパスと継承のルールはまったく同じです。

media宣言を定義するかどうかに関係なく、すべてのフォームオブジェクトにはmediaプロパティがあります。 このプロパティのデフォルト値は、フォームの一部であるすべてのウィジェットにmedia定義を追加した結果です。

>>> from django import forms
>>> class ContactForm(forms.Form):
...     date = DateField(widget=CalendarWidget)
...     name = CharField(max_length=40, widget=OtherWidget)

>>> f = ContactForm()
>>> f.media
<link href="http://static.example.com/pretty.css" type="text/css" media="all" rel="stylesheet">
<script type="text/javascript" src="http://static.example.com/animations.js"></script>
<script type="text/javascript" src="http://static.example.com/actions.js"></script>
<script type="text/javascript" src="http://static.example.com/whizbang.js"></script>

Copy

追加のアセットをフォームに関連付ける場合（たとえば、フォームレイアウト用のCSS）、フォームにMedia宣言を追加するだけです。

>>> class ContactForm(forms.Form):
...     date = DateField(widget=CalendarWidget)
...     name = CharField(max_length=40, widget=OtherWidget)
...
...     class Media:
...         css = {
...             'all': ('layout.css',)
...         }

>>> f = ContactForm()
>>> f.media
<link href="http://static.example.com/pretty.css" type="text/css" media="all" rel="stylesheet">
<link href="http://static.example.com/layout.css" type="text/css" media="all" rel="stylesheet">
<script type="text/javascript" src="http://static.example.com/animations.js"></script>
<script type="text/javascript" src="http://static.example.com/actions.js"></script>
<script type="text/javascript" src="http://static.example.com/whizbang.js"></script>

Copy