diff --git a/docs/faq/admin.txt b/docs/faq/admin.txt index ec407540942..dbcd725a8d7 100644 --- a/docs/faq/admin.txt +++ b/docs/faq/admin.txt @@ -82,7 +82,7 @@ How can I customize the functionality of the admin interface? You've got several options. If you want to piggyback on top of an add/change form that Django automatically generates, you can attach arbitrary JavaScript modules to the page via the model's class Admin :ref:`js parameter -`. That parameter is a list of URLs, as strings, +`. That parameter is a list of URLs, as strings, pointing to JavaScript modules that will be included within the admin form via a `` -The FancyCalendar widget inherits all the media from its parent widget. If -you don't want media to be inherited in this way, add an ``extend=False`` -declaration to the media declaration:: +The FancyCalendar widget inherits all the assets from its parent +widget. If you don't want ``Media`` to be inherited in this way, add +an ``extend=False`` declaration to the ``Media`` declaration:: >>> class FancyCalendarWidget(CalendarWidget): ... class Media: @@ -165,23 +167,24 @@ declaration to the media declaration:: -If you require even more control over media inheritance, define your media -using a :ref:`dynamic property `. Dynamic properties give -you complete control over which media files are inherited, and which are not. +If you require even more control over inheritance, define your assets using a +:ref:`dynamic property `. Dynamic properties give you +complete control over which files are inherited, and which are not. .. _dynamic-property: -Media as a dynamic property ---------------------------- +``Media`` as a dynamic property +------------------------------- -If you need to perform some more sophisticated manipulation of media -requirements, you can define the media property directly. This is done -by defining a widget property that returns an instance of ``forms.Media``. -The constructor for ``forms.Media`` accepts ``css`` and ``js`` keyword -arguments in the same format as that used in a static media definition. +If you need to perform some more sophisticated manipulation of asset +requirements, you can define the ``media`` property directly. This is +done by defining a widget property that returns an instance of +``forms.Media``. The constructor for ``forms.Media`` accepts ``css`` +and ``js`` keyword arguments in the same format as that used in a +static media definition. -For example, the static media definition for our Calendar Widget could -also be defined in a dynamic fashion:: +For example, the static definition for our Calendar Widget could also +be defined in a dynamic fashion:: class CalendarWidget(forms.TextInput): def _media(self): @@ -190,17 +193,17 @@ also be defined in a dynamic fashion:: media = property(_media) See the section on `Media objects`_ for more details on how to construct -return values for dynamic media properties. +return values for dynamic ``media`` properties. -.. _form-media-paths: +.. _form-asset-paths: -Paths in media definitions +Paths in asset definitions -------------------------- -Paths used to specify media can be either relative or absolute. If a path -starts with ``/``, ``http://`` or ``https://``, it will be interpreted as an -absolute path, and left as-is. All other paths will be prepended with the value -of the appropriate prefix. +Paths used to specify assets can be either relative or absolute. If a +path starts with ``/``, ``http://`` or ``https://``, it will be +interpreted as an absolute path, and left as-is. All other paths will +be prepended with the value of the appropriate prefix. As part of the introduction of the :doc:`staticfiles app ` two new settings were added @@ -236,21 +239,22 @@ But if :setting:`STATIC_URL` is ``'http://static.example.com/'``:: -Media objects -------------- +``Media`` objects +----------------- -When you interrogate the media attribute of a widget or form, the value that -is returned is a ``forms.Media`` object. As we have already seen, the string -representation of a Media object is the HTML required to include media -in the ```` block of your HTML page. +When you interrogate the ``media`` attribute of a widget or form, the +value that is returned is a ``forms.Media`` object. As we have already +seen, the string representation of a ``Media`` object is the HTML +required to include the relevant files in the ```` block of your +HTML page. -However, Media objects have some other interesting properties. +However, ``Media`` objects have some other interesting properties. -Media subsets -~~~~~~~~~~~~~ +Subsets of assets +~~~~~~~~~~~~~~~~~ -If you only want media of a particular type, you can use the subscript operator -to filter out a medium of interest. For example:: +If you only want files of a particular type, you can use the subscript +operator to filter out a medium of interest. For example:: >>> w = CalendarWidget() >>> print(w.media) @@ -261,14 +265,15 @@ to filter out a medium of interest. For example:: >>> print(w.media)['css'] -When you use the subscript operator, the value that is returned is a new -Media object -- but one that only contains the media of interest. +When you use the subscript operator, the value that is returned is a +new ``Media`` object -- but one that only contains the media of interest. -Combining media objects -~~~~~~~~~~~~~~~~~~~~~~~ +Combining ``Media`` objects +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Media objects can also be added together. When two media objects are added, -the resulting Media object contains the union of the media from both files:: +``Media`` objects can also be added together. When two ``Media`` objects are +added, the resulting ``Media`` object contains the union of the assets +specified by both:: >>> from django import forms >>> class CalendarWidget(forms.TextInput): @@ -290,17 +295,19 @@ the resulting Media object contains the union of the media from both files:: -Media on Forms --------------- +``Media`` on Forms +------------------ -Widgets aren't the only objects that can have media definitions -- forms -can also define media. The rules for media definitions on forms are the -same as the rules for widgets: declarations can be static or dynamic; -path and inheritance rules for those declarations are exactly the same. +Widgets aren't the only objects that can have ``media`` definitions -- +forms can also define ``media``. The rules for ``media`` definitions +on forms are the same as the rules for widgets: declarations can be +static or dynamic; path and inheritance rules for those declarations +are exactly the same. -Regardless of whether you define a media declaration, *all* Form objects -have a media property. The default value for this property is the result -of adding the media definitions for all widgets that are part of the form:: +Regardless of whether you define a ``media`` declaration, *all* Form +objects have a ``media`` property. The default value for this property +is the result of adding the ``media`` definitions for all widgets that +are part of the form:: >>> from django import forms >>> class ContactForm(forms.Form): @@ -314,8 +321,9 @@ of adding the media definitions for all widgets that are part of the form:: -If you want to associate additional media with a form -- for example, CSS for form -layout -- simply add a media declaration to the form:: +If you want to associate additional assets with a form -- for example, +CSS for form layout -- simply add a ``Media`` declaration to the +form:: >>> class ContactForm(forms.Form): ... date = DateField(widget=CalendarWidget)