{"title":"Form Assets (the Media class)","version":"5.0","locale":"es","docname":"topics/forms/media","url":"/es/5.0/topics/forms/media/","canonical":"https://djangodocs.dev/es/5.0/topics/forms/media/","summary":"Rendering an attractive and easy-to-use web form requires more than just HTML - it also requires CSS stylesheets, and if you want to use fancy widgets, you may also…","html":"

Form Assets (the Media class)Link to this heading#

\n

Rendering an attractive and easy-to-use web form requires more than just\nHTML - it also requires CSS stylesheets, and if you want to use fancy widgets,\nyou may also need to include some JavaScript on each page. The exact\ncombination of CSS and JavaScript that is required for any given page will\ndepend upon the widgets that are in use on that page.

\n

This is where asset definitions come in. Django allows you to\nassociate different files – like stylesheets and scripts – with the\nforms and widgets that require those assets. For example, if you want\nto use a calendar to render DateFields, you can define a custom\nCalendar widget. This widget can then be associated with the CSS and\nJavaScript that is required to render the calendar. When the Calendar\nwidget is used on a form, Django is able to identify the CSS and\nJavaScript files that are required, and provide the list of file names\nin a form suitable for inclusion on your web page.

\n\n\n
\n

Assets as a static definitionLink to this heading#

\n

The easiest way to define assets is as a static definition. Using this\nmethod, the declaration is an inner Media class. The properties of the\ninner class define the requirements.

\n

Here’s an example:

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

This code defines a CalendarWidget, which will be based on TextInput.\nEvery time the CalendarWidget is used on a form, that form will be directed\nto include the CSS file pretty.css, and the JavaScript files\nanimations.js and actions.js.

\n

This static definition is converted at runtime into a widget property\nnamed media. The list of assets for a CalendarWidget instance\ncan be retrieved through this property:

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

Here’s a list of all possible Media options. There are no required options.

\n
\n

cssLink to this heading#

\n

A dictionary describing the CSS files required for various forms of output\nmedia.

\n

The values in the dictionary should be a tuple/list of file names. See\nthe section on paths for details of how to\nspecify paths to these files.

\n

The keys in the dictionary are the output media types. These are the same\ntypes accepted by CSS files in media declarations: “all”, “aural”, “braille”,\n“embossed”, “handheld”, “print”, “projection”, “screen”, “tty” and “tv”. If\nyou need to have different stylesheets for different media types, provide\na list of CSS files for each output medium. The following example would\nprovide two CSS options – one for the screen, and one for print:

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

If a group of CSS files are appropriate for multiple output media types,\nthe dictionary key can be a comma separated list of output media types.\nIn the following example, TV’s and projectors will have the same media\nrequirements:

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

If this last CSS definition were to be rendered, it would become the following HTML:

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

jsLink to this heading#

\n

A tuple describing the required JavaScript files. See the\nsection on paths for details of how to specify\npaths to these files.

\n
\n
\n

extendLink to this heading#

\n

A boolean defining inheritance behavior for Media declarations.

\n

By default, any object using a static Media definition will\ninherit all the assets associated with the parent widget. This occurs\nregardless of how the parent defines its own requirements. For\nexample, if we were to extend our basic Calendar widget from the\nexample above:

\n
Python console
>>> class FancyCalendarWidget(CalendarWidget):\n...     class Media:\n...         css = {\n...             "all": ["fancy.css"],\n...         }\n...         js = ["whizbang.js"]\n...\n\n>>> w = FancyCalendarWidget()\n>>> print(w.media)\n<link href="http://static.example.com/pretty.css" media="all" rel="stylesheet">\n<link href="http://static.example.com/fancy.css" media="all" rel="stylesheet">\n<script src="http://static.example.com/animations.js"></script>\n<script src="http://static.example.com/actions.js"></script>\n<script src="http://static.example.com/whizbang.js"></script>\n
\n

The FancyCalendar widget inherits all the assets from its parent\nwidget. If you don’t want Media to be inherited in this way, add\nan extend=False declaration to the Media declaration:

\n
Python console
>>> class FancyCalendarWidget(CalendarWidget):\n...     class Media:\n...         extend = False\n...         css = {\n...             "all": ["fancy.css"],\n...         }\n...         js = ["whizbang.js"]\n...\n\n>>> w = FancyCalendarWidget()\n>>> print(w.media)\n<link href="http://static.example.com/fancy.css" media="all" rel="stylesheet">\n<script src="http://static.example.com/whizbang.js"></script>\n
\n

If you require even more control over inheritance, define your assets using a\ndynamic property. Dynamic properties give you\ncomplete control over which files are inherited, and which are not.

\n
\n
\n
\n

Media as a dynamic propertyLink to this heading#

\n

If you need to perform some more sophisticated manipulation of asset\nrequirements, you can define the media property directly. This is\ndone by defining a widget property that returns an instance of\nforms.Media. The constructor for forms.Media accepts css\nand js keyword arguments in the same format as that used in a\nstatic media definition.

\n

For example, the static definition for our Calendar Widget could also\nbe defined in a dynamic fashion:

\n
Code
class CalendarWidget(forms.TextInput):\n    @property\n    def media(self):\n        return forms.Media(\n            css={"all": ["pretty.css"]}, js=["animations.js", "actions.js"]\n        )\n
\n

See the section on Media objects for more details on how to construct\nreturn values for dynamic media properties.

\n
\n
\n

Paths in asset definitionsLink to this heading#

\n
\n

Paths as stringsLink to this heading#

\n

String paths used to specify assets can be either relative or absolute. If a\npath starts with /, http:// or https://, it will be\ninterpreted as an absolute path, and left as-is. All other paths will\nbe prepended with the value of the appropriate prefix. If the\ndjango.contrib.staticfiles app is installed, it will be used to serve\nassets.

\n

Whether or not you use django.contrib.staticfiles, the\nSTATIC_URL and STATIC_ROOT settings are required to\nrender a complete web page.

\n

To find the appropriate prefix to use, Django will check if the\nSTATIC_URL setting is not None and automatically fall back\nto using MEDIA_URL. For example, if the MEDIA_URL for\nyour site was 'http://uploads.example.com/' and STATIC_URL\nwas None:

\n
Python console
>>> from django import forms\n>>> class CalendarWidget(forms.TextInput):\n...     class Media:\n...         css = {\n...             "all": ["/css/pretty.css"],\n...         }\n...         js = ["animations.js", "http://othersite.com/actions.js"]\n...\n\n>>> w = CalendarWidget()\n>>> print(w.media)\n<link href="/css/pretty.css" media="all" rel="stylesheet">\n<script src="http://uploads.example.com/animations.js"></script>\n<script src="http://othersite.com/actions.js"></script>\n
\n

But if STATIC_URL is 'http://static.example.com/':

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

Or if staticfiles is configured using the\nManifestStaticFilesStorage:

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

Paths as objectsLink to this heading#

\n

Asset paths may also be given as hashable objects implementing an\n__html__() method. The __html__() method is typically added using the\nhtml_safe() decorator. The object is responsible for\noutputting the complete HTML <script> or <link> tag content:

\n
Python console
>>> from django import forms\n>>> from django.utils.html import html_safe\n>>>\n>>> @html_safe\n... class JSPath:\n...     def __str__(self):\n...         return '<script src="https://example.org/asset.js" defer>'\n...\n\n>>> class SomeWidget(forms.TextInput):\n...     class Media:\n...         js = [JSPath()]\n...\n
\n
\n
\n
\n

Media objectsLink to this heading#

\n

When you interrogate the media attribute of a widget or form, the\nvalue that is returned is a forms.Media object. As we have already\nseen, the string representation of a Media object is the HTML\nrequired to include the relevant files in the <head> block of your\nHTML page.

\n

However, Media objects have some other interesting properties.

\n
\n

Subsets of assetsLink to this heading#

\n

If you only want files of a particular type, you can use the subscript\noperator to filter out a medium of interest. For example:

\n
Python console
>>> w = CalendarWidget()\n>>> print(w.media)\n<link href="http://static.example.com/pretty.css" media="all" rel="stylesheet">\n<script src="http://static.example.com/animations.js"></script>\n<script src="http://static.example.com/actions.js"></script>\n\n>>> print(w.media["css"])\n<link href="http://static.example.com/pretty.css" media="all" rel="stylesheet">\n
\n

When you use the subscript operator, the value that is returned is a\nnew Media object – but one that only contains the media of interest.

\n
\n
\n

Combining Media objectsLink to this heading#

\n

Media objects can also be added together. When two Media objects are\nadded, the resulting Media object contains the union of the assets\nspecified by both:

\n
Python console
>>> from django import forms\n>>> class CalendarWidget(forms.TextInput):\n...     class Media:\n...         css = {\n...             "all": ["pretty.css"],\n...         }\n...         js = ["animations.js", "actions.js"]\n...\n\n>>> class OtherWidget(forms.TextInput):\n...     class Media:\n...         js = ["whizbang.js"]\n...\n\n>>> w1 = CalendarWidget()\n>>> w2 = OtherWidget()\n>>> print(w1.media + w2.media)\n<link href="http://static.example.com/pretty.css" media="all" rel="stylesheet">\n<script src="http://static.example.com/animations.js"></script>\n<script src="http://static.example.com/actions.js"></script>\n<script src="http://static.example.com/whizbang.js"></script>\n
\n
\n
\n

Order of assetsLink to this heading#

\n

The order in which assets are inserted into the DOM is often important. For\nexample, you may have a script that depends on jQuery. Therefore, combining\nMedia objects attempts to preserve the relative order in which assets are\ndefined in each Media class.

\n

For example:

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

Combining Media objects with assets in a conflicting order results in a\nMediaOrderConflictWarning.

\n
\n
\n
\n

Media on FormsLink to this heading#

\n

Widgets aren’t the only objects that can have media definitions –\nforms can also define media. The rules for media definitions\non forms are the same as the rules for widgets: declarations can be\nstatic or dynamic; path and inheritance rules for those declarations\nare exactly the same.

\n

Regardless of whether you define a media declaration, all Form\nobjects have a media property. The default value for this property\nis the result of adding the media definitions for all widgets that\nare part of the form:

\n
Python console
>>> from django import forms\n>>> class ContactForm(forms.Form):\n...     date = DateField(widget=CalendarWidget)\n...     name = CharField(max_length=40, widget=OtherWidget)\n...\n\n>>> f = ContactForm()\n>>> f.media\n<link href="http://static.example.com/pretty.css" media="all" rel="stylesheet">\n<script src="http://static.example.com/animations.js"></script>\n<script src="http://static.example.com/actions.js"></script>\n<script src="http://static.example.com/whizbang.js"></script>\n
\n

If you want to associate additional assets with a form – for example,\nCSS for form layout – add a Media declaration to the form:

\n
Python console
>>> class ContactForm(forms.Form):\n...     date = DateField(widget=CalendarWidget)\n...     name = CharField(max_length=40, widget=OtherWidget)\n...     class Media:\n...         css = {\n...             "all": ["layout.css"],\n...         }\n...\n\n>>> f = ContactForm()\n>>> f.media\n<link href="http://static.example.com/pretty.css" media="all" rel="stylesheet">\n<link href="http://static.example.com/layout.css" media="all" rel="stylesheet">\n<script src="http://static.example.com/animations.js"></script>\n<script src="http://static.example.com/actions.js"></script>\n<script src="http://static.example.com/whizbang.js"></script>\n
\n
","rootId":"form-assets-the-media-class","toc":[{"title":"Assets as a static definition","anchor":"assets-as-a-static-definition","children":[{"title":"css","anchor":"css","children":[]},{"title":"js","anchor":"js","children":[]},{"title":"extend","anchor":"extend","children":[]}]},{"title":"Media as a dynamic property","anchor":"media-as-a-dynamic-property","children":[]},{"title":"Paths in asset definitions","anchor":"paths-in-asset-definitions","children":[{"title":"Paths as strings","anchor":"paths-as-strings","children":[]},{"title":"Paths as objects","anchor":"paths-as-objects","children":[]}]},{"title":"Media objects","anchor":"media-objects","children":[{"title":"Subsets of assets","anchor":"subsets-of-assets","children":[]},{"title":"Combining Media objects","anchor":"combining-media-objects","children":[]},{"title":"Order of assets","anchor":"order-of-assets","children":[]}]},{"title":"Media on Forms","anchor":"media-on-forms","children":[]}],"breadcrumbs":[{"docname":"topics/index","title":"Using Django","url":"/es/5.0/topics/"},{"docname":"topics/forms/index","title":"Working with forms","url":"/es/5.0/topics/forms/"}],"prev":{"docname":"topics/forms/modelforms","title":"Creating forms from models","url":"/es/5.0/topics/forms/modelforms/"},"next":{"docname":"topics/templates","title":"Plantillas","url":"/es/5.0/topics/templates/"},"formats":{"html":"/es/5.0/topics/forms/media/","markdown":"/es/5.0/topics/forms/media.md","json":"/es/5.0/topics/forms/media.json"},"source":"https://github.com/django/django/blob/stable/5.0.x/docs/topics/forms/media.txt","official":"https://docs.djangoproject.com/es/5.0/topics/forms/media/","inVersions":["6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1","3.0","2.2","2.1","2.0","1.11","1.10","1.9"],"inLocales":["en","zh-hans","fr","ja","id","it","pt-br","ko","es","el","pl"]}