Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

[1.6.x] Fixed #19695 -- Retitle "Form Media" to "Form Assets".

Backport of c0f0317 from master
  • Loading branch information...
commit b2afe396635e2de5b3a917a61350cd96fbde9ab7 1 parent 7300691
@ubernostrum ubernostrum authored timgraham committed
View
2  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
-<modeladmin-media-definitions>`. That parameter is a list of URLs, as strings,
+<modeladmin-asset-definitions>`. That parameter is a list of URLs, as strings,
pointing to JavaScript modules that will be included within the admin form via
a ``<script>`` tag.
View
10 docs/ref/contrib/admin/index.txt
@@ -1554,13 +1554,13 @@ instances which allow you to easily customize the response data before
rendering. For more details, see the :doc:`TemplateResponse documentation
</ref/template-response>`.
-.. _modeladmin-media-definitions:
+.. _modeladmin-asset-definitions:
-``ModelAdmin`` media definitions
+``ModelAdmin`` asset definitions
--------------------------------
There are times where you would like add a bit of CSS and/or JavaScript to
-the add/change views. This can be accomplished by using a Media inner class
+the add/change views. This can be accomplished by using a ``Media`` inner class
on your ``ModelAdmin``::
class ArticleAdmin(admin.ModelAdmin):
@@ -1572,8 +1572,8 @@ on your ``ModelAdmin``::
The :doc:`staticfiles app </ref/contrib/staticfiles>` prepends
:setting:`STATIC_URL` (or :setting:`MEDIA_URL` if :setting:`STATIC_URL` is
-``None``) to any media paths. The same rules apply as :ref:`regular media
-definitions on forms <form-media-paths>`.
+``None``) to any asset paths. The same rules apply as :ref:`regular asset
+definitions on forms <form-asset-paths>`.
jQuery
~~~~~~
View
9 docs/ref/forms/widgets.txt
@@ -171,16 +171,15 @@ You can also set the HTML ``id`` using :attr:`~Widget.attrs`. See
Styling widget classes
^^^^^^^^^^^^^^^^^^^^^^
-With widgets, it is possible to add media (``css`` and ``javascript``)
+With widgets, it is possible to add assets (``css`` and ``javascript``)
and more deeply customize their appearance and behavior.
In a nutshell, you will need to subclass the widget and either
-:ref:`define a class "Media" <media-as-a-static-definition>` as a member of the
-subclass, or :ref:`create a property "media" <dynamic-property>`, returning an
-instance of that class.
+:ref:`define a "Media" inner class <assets-as-a-static-definition>` or
+:ref:`create a "media" property <dynamic-property>`.
These methods involve somewhat advanced Python programming and are described in
-detail in the :doc:`Form Media </topics/forms/media>` topic guide.
+detail in the :doc:`Form Assets </topics/forms/media>` topic guide.
.. _base-widget-classes:
View
2  docs/ref/settings.txt
@@ -2487,7 +2487,7 @@ URL to use when referring to static files located in :setting:`STATIC_ROOT`.
Example: ``"/static/"`` or ``"http://static.example.com/"``
If not ``None``, this will be used as the base path for
-:ref:`media definitions<form-media-paths>` and the
+:ref:`asset definitions<form-asset-paths>` (the ``Media`` class) and the
:doc:`staticfiles app</ref/contrib/staticfiles>`.
It must end in a slash if set to a non-empty value.
View
2  docs/releases/1.3-beta-1.txt
@@ -116,7 +116,7 @@ As a result, we took the following steps to rectify the issue:
(``django.core.context_processors.static``) and renamed to
:func:`~django.core.context_processors.static`.
-* :ref:`form-media-paths` now uses :setting:`STATIC_URL` as the prefix
+* :ref:`form-asset-paths` now uses :setting:`STATIC_URL` as the prefix
**if the value is not None**, and falls back to the previously used
:setting:`MEDIA_URL` setting otherwise.
View
2  docs/topics/forms/index.txt
@@ -42,7 +42,7 @@ The library deals with these concepts:
A collection of fields that knows how to validate itself and
display itself as HTML.
- Form Media
+ Form Assets (the ``Media`` class)
The CSS and JavaScript resources that are required to render a form.
The library is decoupled from the other Django components, such as the database
View
176 docs/topics/forms/media.txt
@@ -1,5 +1,5 @@
-Form Media
-==========
+Form Assets (the ``Media`` class)
+=================================
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
@@ -7,23 +7,24 @@ HTML - it also requires CSS stylesheets, and if you want to use fancy
page. The exact combination of CSS and JavaScript that is required for
any given page will depend upon the widgets that are in use on that page.
-This is where Django media definitions come in. Django allows you to
-associate different media files with the forms and widgets that require
-that media. For example, if you want to use a calendar to render DateFields,
-you can define a custom Calendar widget. This widget can then be associated
-with the CSS and JavaScript that is required to render the calendar. When
-the Calendar widget is used on a form, Django is able to identify the CSS and
+This is where asset definitions come in. Django allows you to
+associate different files -- like stylesheets and scripts -- with the
+forms and widgets that require those assets. For example, if you want
+to use a calendar to render DateFields, you can define a custom
+Calendar widget. This widget can then be associated with the CSS and
+JavaScript that is required to render the calendar. When the Calendar
+widget is used on a form, Django is able to identify the CSS and
JavaScript files that are required, and provide the list of file names
in a form suitable for easy inclusion on your Web page.
-.. admonition:: Media and Django Admin
+.. admonition:: Assets and Django Admin
- The Django Admin application defines a number of customized widgets
- for calendars, filtered selections, and so on. These widgets define
- media requirements, and the Django Admin uses the custom widgets
- in place of the Django defaults. The Admin templates will only include
- those media files that are required to render the widgets on any
- given page.
+ The Django Admin application defines a number of customized
+ widgets for calendars, filtered selections, and so on. These
+ widgets define asset requirements, and the Django Admin uses the
+ custom widgets in place of the Django defaults. The Admin
+ templates will only include those files that are required to
+ render the widgets on any given page.
If you like the widgets that the Django Admin application uses,
feel free to use them in your own application! They're all stored
@@ -38,14 +39,14 @@ in a form suitable for easy inclusion on your Web page.
whichever toolkit suits your requirements. Django is able to integrate
with any JavaScript toolkit.
-.. _media-as-a-static-definition:
+.. _assets-as-a-static-definition:
-Media as a static definition
-----------------------------
+Assets as a static definition
+-----------------------------
-The easiest way to define media is as a static definition. Using this method,
-the media declaration is an inner class. The properties of the inner class
-define the media requirements.
+The easiest way to define assets is as a static definition. Using this
+method, the declaration is an inner ``Media`` class. The properties of the
+inner class define the requirements.
Here's a simple example::
@@ -63,9 +64,9 @@ Every time the CalendarWidget is used on a form, that form will be directed
to include the CSS file ``pretty.css``, and the JavaScript files
``animations.js`` and ``actions.js``.
-This static media definition is converted at runtime into a widget property
-named ``media``. The media for a CalendarWidget instance can be retrieved
-through this property::
+This static definition is converted at runtime into a widget property
+named ``media``. The list of assets for a ``CalendarWidget`` instance
+can be retrieved through this property::
>>> w = CalendarWidget()
>>> print(w.media)
@@ -82,8 +83,8 @@ A dictionary describing the CSS files required for various forms of output
media.
The values in the dictionary should be a tuple/list of file names. See
-:ref:`the section on media paths <form-media-paths>` for details of how to
-specify paths to media files.
+:ref:`the section on paths <form-asset-paths>` for details of how to
+specify paths to these files.
The keys in the dictionary are the output media types. These are the same
types accepted by CSS files in media declarations: 'all', 'aural', 'braille',
@@ -119,19 +120,20 @@ If this last CSS definition were to be rendered, it would become the following H
``js``
~~~~~~
-A tuple describing the required JavaScript files. See :ref:`the section on
-media paths <form-media-paths>` for details of how to specify paths to media
-files.
+A tuple describing the required JavaScript files. See :ref:`the
+section on paths <form-asset-paths>` for details of how to specify
+paths to these files.
``extend``
~~~~~~~~~~
-A boolean defining inheritance behavior for media declarations.
+A boolean defining inheritance behavior for ``Media`` declarations.
-By default, any object using a static media definition will inherit all the
-media associated with the parent widget. This occurs regardless of how the
-parent defines its media requirements. For example, if we were to extend our
-basic Calendar widget from the example above::
+By default, any object using a static ``Media`` definition will
+inherit all the assets associated with the parent widget. This occurs
+regardless of how the parent defines its own requirements. For
+example, if we were to extend our basic Calendar widget from the
+example above::
>>> class FancyCalendarWidget(CalendarWidget):
... class Media:
@@ -148,9 +150,9 @@ basic Calendar widget from the example above::
<script type="text/javascript" src="http://static.example.com/actions.js"></script>
<script type="text/javascript" src="http://static.example.com/whizbang.js"></script>
-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::
<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>
-If you require even more control over media inheritance, define your media
-using a :ref:`dynamic property <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-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 </ref/contrib/staticfiles>` two new settings were added
@@ -236,21 +239,22 @@ But if :setting:`STATIC_URL` is ``'http://static.example.com/'``::
<script type="text/javascript" src="http://othersite.com/actions.js"></script>
-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 ``<head>`` 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 ``<head>`` 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']
<link href="http://static.example.com/pretty.css" type="text/css" media="all" rel="stylesheet" />
-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::
<script type="text/javascript" src="http://static.example.com/actions.js"></script>
<script type="text/javascript" src="http://static.example.com/whizbang.js"></script>
-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::
<script type="text/javascript" src="http://static.example.com/actions.js"></script>
<script type="text/javascript" src="http://static.example.com/whizbang.js"></script>
-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)

0 comments on commit b2afe39

Please sign in to comment.
Something went wrong with that request. Please try again.