p15693087
/
django
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Fixed #19695 -- Retitle "Form Media" to "Form Assets".

This commit is contained in:
James Bennett 2013-06-20 01:51:20 -05:00 committed by Tim Graham
parent 660c30ed95
commit c0f03175ce
7 changed files with 105 additions and 98 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/faq/admin.txt
View File

@ -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 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 form that Django automatically generates, you can attach arbitrary JavaScript
modules to the page via the model's class Admin :ref:`js parameter 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 pointing to JavaScript modules that will be included within the admin form via
a ``<script>`` tag. a ``<script>`` tag.

10
docs/ref/contrib/admin/index.txt
View File

@ -1554,13 +1554,13 @@ instances which allow you to easily customize the response data before
rendering. For more details, see the :doc:`TemplateResponse documentation rendering. For more details, see the :doc:`TemplateResponse documentation
</ref/template-response>`. </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 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``:: on your ``ModelAdmin``::
class ArticleAdmin(admin.ModelAdmin): class ArticleAdmin(admin.ModelAdmin):
@ -1572,8 +1572,8 @@ on your ``ModelAdmin``::
The :doc:`staticfiles app </ref/contrib/staticfiles>` prepends The :doc:`staticfiles app </ref/contrib/staticfiles>` prepends
:setting:`STATIC_URL` (or :setting:`MEDIA_URL` if :setting:`STATIC_URL` is :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 ``None``) to any asset paths. The same rules apply as :ref:`regular asset
definitions on forms <form-media-paths>`. definitions on forms <form-asset-paths>`.
jQuery jQuery
~~~~~~ ~~~~~~

9
docs/ref/forms/widgets.txt
View File

@ -171,16 +171,15 @@ You can also set the HTML ``id`` using :attr:`~Widget.attrs`. See
Styling widget classes 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. and more deeply customize their appearance and behavior.
In a nutshell, you will need to subclass the widget and either 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 :ref:`define a "Media" inner class <assets-as-a-static-definition>` or
subclass, or :ref:`create a property "media" <dynamic-property>`, returning an :ref:`create a "media" property <dynamic-property>`.
instance of that class.
These methods involve somewhat advanced Python programming and are described in 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: .. _base-widget-classes:

2
docs/ref/settings.txt
View File

@ -2475,7 +2475,7 @@ URL to use when referring to static files located in :setting:`STATIC_ROOT`.
Example: ``"/static/"`` or ``"http://static.example.com/"`` Example: ``"/static/"`` or ``"http://static.example.com/"``
If not ``None``, this will be used as the base path for 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>`. :doc:`staticfiles app</ref/contrib/staticfiles>`.
It must end in a slash if set to a non-empty value. It must end in a slash if set to a non-empty value.

2
docs/releases/1.3-beta-1.txt
View File

@ -116,7 +116,7 @@ As a result, we took the following steps to rectify the issue:
(``django.core.context_processors.static``) and renamed to (``django.core.context_processors.static``) and renamed to
:func:`~django.core.context_processors.static`. :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 **if the value is not None**, and falls back to the previously used
:setting:`MEDIA_URL` setting otherwise. :setting:`MEDIA_URL` setting otherwise.

2
docs/topics/forms/index.txt
View File

@ -42,7 +42,7 @@ The library deals with these concepts:
A collection of fields that knows how to validate itself and A collection of fields that knows how to validate itself and
display itself as HTML. display itself as HTML.
Form Media Form Assets (the ``Media`` class)
The CSS and JavaScript resources that are required to render a form. 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 The library is decoupled from the other Django components, such as the database

176
docs/topics/forms/media.txt
View File

@ -1,5 +1,5 @@
Form Media Form Assets (the ``Media`` class)
========== =================================
Rendering an attractive and easy-to-use Web form requires more than just 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 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 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. 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 This is where asset definitions come in. Django allows you to
associate different media files with the forms and widgets that require associate different files -- like stylesheets and scripts -- with the
that media. For example, if you want to use a calendar to render DateFields, forms and widgets that require those assets. For example, if you want
you can define a custom Calendar widget. This widget can then be associated to use a calendar to render DateFields, you can define a custom
with the CSS and JavaScript that is required to render the calendar. When Calendar widget. This widget can then be associated with the CSS and
the Calendar widget is used on a form, Django is able to identify 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 JavaScript files that are required, and provide the list of file names
in a form suitable for easy inclusion on your Web page. 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 The Django Admin application defines a number of customized
for calendars, filtered selections, and so on. These widgets define widgets for calendars, filtered selections, and so on. These
media requirements, and the Django Admin uses the custom widgets widgets define asset requirements, and the Django Admin uses the
in place of the Django defaults. The Admin templates will only include custom widgets in place of the Django defaults. The Admin
those media files that are required to render the widgets on any templates will only include those files that are required to
given page. render the widgets on any given page.
If you like the widgets that the Django Admin application uses, If you like the widgets that the Django Admin application uses,
feel free to use them in your own application! They're all stored 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 whichever toolkit suits your requirements. Django is able to integrate
with any JavaScript toolkit. 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 easiest way to define assets is as a static definition. Using this
the media declaration is an inner class. The properties of the inner class method, the declaration is an inner ``Media`` class. The properties of the
define the media requirements. inner class define the requirements.
Here's a simple example:: 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 to include the CSS file ``pretty.css``, and the JavaScript files
``animations.js`` and ``actions.js``. ``animations.js`` and ``actions.js``.
This static media definition is converted at runtime into a widget property This static definition is converted at runtime into a widget property
named ``media``. The media for a CalendarWidget instance can be retrieved named ``media``. The list of assets for a ``CalendarWidget`` instance
through this property:: can be retrieved through this property::
>>> w = CalendarWidget() >>> w = CalendarWidget()
>>> print(w.media) >>> print(w.media)
@ -82,8 +83,8 @@ A dictionary describing the CSS files required for various forms of output
media. media.
The values in the dictionary should be a tuple/list of file names. See 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 :ref:`the section on paths <form-asset-paths>` for details of how to
specify paths to media files. specify paths to these files.
The keys in the dictionary are the output media types. These are the same 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', 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`` ``js``
~~~~~~ ~~~~~~
A tuple describing the required JavaScript files. See :ref:`the section on A tuple describing the required JavaScript files. See :ref:`the
media paths <form-media-paths>` for details of how to specify paths to media section on paths <form-asset-paths>` for details of how to specify
files. paths to these files.
``extend`` ``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 By default, any object using a static ``Media`` definition will
media associated with the parent widget. This occurs regardless of how the inherit all the assets associated with the parent widget. This occurs
parent defines its media requirements. For example, if we were to extend our regardless of how the parent defines its own requirements. For
basic Calendar widget from the example above:: example, if we were to extend our basic Calendar widget from the
example above::
>>> class FancyCalendarWidget(CalendarWidget): >>> class FancyCalendarWidget(CalendarWidget):
... class Media: ... 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/actions.js"></script>
<script type="text/javascript" src="http://static.example.com/whizbang.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 The FancyCalendar widget inherits all the assets from its parent
you don't want media to be inherited in this way, add an ``extend=False`` widget. If you don't want ``Media`` to be inherited in this way, add
declaration to the media declaration:: an ``extend=False`` declaration to the ``Media`` declaration::
>>> class FancyCalendarWidget(CalendarWidget): >>> class FancyCalendarWidget(CalendarWidget):
... class Media: ... 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" /> <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> <script type="text/javascript" src="http://static.example.com/whizbang.js"></script>
If you require even more control over media inheritance, define your media If you require even more control over inheritance, define your assets using a
using a :ref:`dynamic property <dynamic-property>`. Dynamic properties give :ref:`dynamic property <dynamic-property>`. Dynamic properties give you
you complete control over which media files are inherited, and which are not. complete control over which files are inherited, and which are not.
.. _dynamic-property: .. _dynamic-property:
Media as a dynamic property ``Media`` as a dynamic property
--------------------------- -------------------------------
If you need to perform some more sophisticated manipulation of media If you need to perform some more sophisticated manipulation of asset
requirements, you can define the media property directly. This is done requirements, you can define the ``media`` property directly. This is
by defining a widget property that returns an instance of ``forms.Media``. done by defining a widget property that returns an instance of
The constructor for ``forms.Media`` accepts ``css`` and ``js`` keyword ``forms.Media``. The constructor for ``forms.Media`` accepts ``css``
arguments in the same format as that used in a static media definition. 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 For example, the static definition for our Calendar Widget could also
also be defined in a dynamic fashion:: be defined in a dynamic fashion::
class CalendarWidget(forms.TextInput): class CalendarWidget(forms.TextInput):
def _media(self): def _media(self):
@ -190,17 +193,17 @@ also be defined in a dynamic fashion::
media = property(_media) media = property(_media)
See the section on `Media objects`_ for more details on how to construct 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 Paths used to specify assets can be either relative or absolute. If a
starts with ``/``, ``http://`` or ``https://``, it will be interpreted as an path starts with ``/``, ``http://`` or ``https://``, it will be
absolute path, and left as-is. All other paths will be prepended with the value interpreted as an absolute path, and left as-is. All other paths will
of the appropriate prefix. be prepended with the value of the appropriate prefix.
As part of the introduction of the As part of the introduction of the
:doc:`staticfiles app </ref/contrib/staticfiles>` two new settings were added :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> <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 When you interrogate the ``media`` attribute of a widget or form, the
is returned is a ``forms.Media`` object. As we have already seen, the string value that is returned is a ``forms.Media`` object. As we have already
representation of a Media object is the HTML required to include media seen, the string representation of a ``Media`` object is the HTML
in the ``<head>`` block of your HTML page. 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 If you only want files of a particular type, you can use the subscript
to filter out a medium of interest. For example:: operator to filter out a medium of interest. For example::
>>> w = CalendarWidget() >>> w = CalendarWidget()
>>> print(w.media) >>> print(w.media)
@ -261,14 +265,15 @@ to filter out a medium of interest. For example::
>>> print(w.media)['css'] >>> print(w.media)['css']
<link href="http://static.example.com/pretty.css" type="text/css" media="all" rel="stylesheet" /> <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 When you use the subscript operator, the value that is returned is a
Media object -- but one that only contains the media of interest. 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, ``Media`` objects can also be added together. When two ``Media`` objects are
the resulting Media object contains the union of the media from both files:: added, the resulting ``Media`` object contains the union of the assets
specified by both::
>>> from django import forms >>> from django import forms
>>> class CalendarWidget(forms.TextInput): >>> 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/actions.js"></script>
<script type="text/javascript" src="http://static.example.com/whizbang.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 Widgets aren't the only objects that can have ``media`` definitions --
can also define media. The rules for media definitions on forms are the forms can also define ``media``. The rules for ``media`` definitions
same as the rules for widgets: declarations can be static or dynamic; on forms are the same as the rules for widgets: declarations can be
path and inheritance rules for those declarations are exactly the same. 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 Regardless of whether you define a ``media`` declaration, *all* Form
have a media property. The default value for this property is the result objects have a ``media`` property. The default value for this property
of adding the media definitions for all widgets that are part of the form:: is the result of adding the ``media`` definitions for all widgets that
are part of the form::
>>> from django import forms >>> from django import forms
>>> class ContactForm(forms.Form): >>> 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/actions.js"></script>
<script type="text/javascript" src="http://static.example.com/whizbang.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 If you want to associate additional assets with a form -- for example,
layout -- simply add a media declaration to the form:: CSS for form layout -- simply add a ``Media`` declaration to the
form::
>>> class ContactForm(forms.Form): >>> class ContactForm(forms.Form):
... date = DateField(widget=CalendarWidget) ... date = DateField(widget=CalendarWidget)