Activos de Formulario (la clase Media)

La traducción de los textos es la siguiente:

Esto es donde entran en juego las definiciones de activos. Django te permite asociar diferentes archivos – como hojas de estilo y scripts – con los formularios y widgets que requieren esos activos. Por ejemplo, si deseas utilizar un calendario para renderizar Campos de Fecha, puedes definir un widget de Calendario personalizado. Este widget puede entonces estar asociado con el CSS y JavaScript requeridos para renderizar el calendario. Cuando se utiliza el widget de Calendario en un formulario, Django es capaz de identificar los archivos CSS y JavaScript que se requieren y proporcionar la lista de nombres de archivo en una forma adecuada para incluir en tu página web.

Activos y Django Admin

La aplicación del Administrador de Django define un número de widgets personalizados para calendarios, selecciones filtradas, etc. Estos widgets definen las necesidades de activos y el Administrador de Django utiliza los widgets personalizados en lugar de los valores por defecto de Django. Los plantillas del Administrador solo incluirán aquellos archivos que se requieren para renderizar los widgets en cualquier página dada.

Si te gusta utilizar los widgets utilizados por la aplicación del Administrador de Django, ¡no dudes en usarlos en tu propia aplicación! Están almacenados en django.contrib.admin.widgets.

¿Cuál toolkit de JavaScript?

Existen muchos toolkits de JavaScript y muchos de ellos incluyen widgets (como calendarios) que pueden utilizarse para mejorar tu aplicación. Django ha evitado deliberadamente dar su bendición a algún toolkit de JavaScript en particular. Cada toolkit tiene sus propias fortalezas y debilidades relativas - utiliza el que se adapte mejor a tus necesidades. Django es capaz de integrarse con cualquier toolkit de JavaScript.

Activos como definición estática

La forma más fácil de definir activos es como una definición estática. Utilizando este método, la declaración es una clase Media interna. Las propiedades de la clase interna definen las necesidades.

Aquí tienes un ejemplo:

from django import forms


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

Este código define un CalendarWidget, que se basará en TextInput. Cada vez que el CalendarWidget se utilice en una forma, esa forma será dirigida a incluir el archivo CSS pretty.css, y los archivos JavaScript animations.js y actions.js.

Esta definición estática se convierte en tiempo de ejecución en la propiedad del widget llamada media. La lista de activos para una instancia de CalendarWidget puede ser recuperada a través de esta propiedad:

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

Aquí tienes una lista de todas las opciones posibles de Media. No hay opciones requeridas.

css

Un diccionario que describe los archivos CSS necesarios para diferentes tipos de medios de salida.

Los valores en el diccionario deben ser una tupla/lista de nombres de archivo. Consulta la sección sobre rutas <form-asset-paths> para obtener detalles sobre cómo especificar las rutas a estos archivos.

Las claves en el diccionario son los tipos de medios de salida. Estos son los mismos tipos aceptados por los archivos CSS en declaraciones de medios: “all”, “aural”, “braille”, “embossed”, “handheld”, “print”, “projection”, “screen”, “tty” y “tv”. Si necesitas tener estilos diferentes para diferentes tipos de medios, proporciona una lista de archivos CSS para cada tipo de medio. El siguiente ejemplo proporcionaría dos opciones CSS – una para la pantalla, y otra para la impresión:

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

Si un grupo de archivos CSS son adecuados para varios tipos de medios de salida, la clave del diccionario puede ser una lista separada por comas de los tipos de medios. En el siguiente ejemplo, TV’s y proyectores tendrán las mismas requisitos de medios:

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

Si esta última definición CSS se hubiera de renderizar, se convertiría en el siguiente HTML:

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

js

Los textos traducidos son:

Script objetos

class Script(src, **attributes)[fuente]

Representa un archivo script.

El primer parámetro, src, es la ruta como cadena al archivo script. Consulta la sección sobre rutas <form-asset-paths> para obtener detalles de cómo especificar las rutas a estos archivos.

Los argumentos de palabra clave opcionales, **attributes, son atributos HTML que se establecen en el tag <script> renderizado.

Consulta los objetos de activos de media <form-media-asset-objects> para obtener ejemplos de uso.

extend

Un booleano que define el comportamiento de herencia para las declaraciones Media.

Por defecto, cualquier objeto que utilice una definición estática Media heredará todos los activos asociados con el widget padre. Esto ocurre sin importar cómo el padre defina sus propias necesidades. Por ejemplo, si extendemos nuestro calendario básico del ejemplo anterior:

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

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

El widget FancyCalendar hereda todos los activos de su widget padre. Si no deseas que Media se herede de esta manera, agrega una declaración extend=False a la declaracion Media:

>>> class FancyCalendarWidget(CalendarWidget):
...     class Media:
...         extend = False
...         css = {
...             "all": ["fancy.css"],
...         }
...         js = ["whizbang.js"]
...

>>> w = FancyCalendarWidget()
>>> print(w.media)
<link href="https://static.example.com/fancy.css" media="all" rel="stylesheet">
<script src="https://static.example.com/whizbang.js"></script>

Si requieres un control aún más completo sobre la herencia, define tus activos utilizando una propiedad dinámica <dynamic-property>. Las propiedades dinámicas te dan un control total sobre los archivos que se heredan y los que no.

Media como propiedad dinámica

Si necesitas realizar alguna manipulación más sofisticada de las exigencias de activos, puedes definir la propiedad media directamente. Esto se hace definiendo una propiedad de widget que devuelve una instancia de forms.Media. El constructor para forms.Media acepta argumentos clave css y js en el mismo formato que se utiliza en una definición estática de media.

Por ejemplo, la definición estática para nuestro Widget del Calendario también podría estar definida de manera dinámica:

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

Consulte la sección sobre objetos Media para obtener más detalles sobre cómo construir valores de retorno para propiedades media dinámicas.

Rutas en definiciones de activos

Rutas como cadenas de texto

Las rutas utilizadas para especificar activos pueden ser relativas o absolutas. Si una ruta comienza con /, http:// o https://, se interpretará como una ruta absoluta y se dejará tal cual. Todas las otras rutas se prepondrán con el valor del prefijo apropiado. Si la aplicación django.contrib.staticfiles está instalada, se utilizará para servir activos.

Independientemente de si utilizas django.contrib.staticfiles, los ajustes STATIC_URL y STATIC_ROOT son necesarios para renderizar una página web completa.

Para encontrar el prefijo apropiado a utilizar, Django comprobará si el ajuste STATIC_URL no es None y caería automáticamente en la utilización de MEDIA_URL. Por ejemplo, si el ajuste MEDIA_URL para tu sitio era 'https://uploads.example.com/' y STATIC_URL era None:

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

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

Pero si STATIC_URL es 'https://static.example.com/':

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

O si staticfiles está configurado utilizando la clase ManifestStaticFilesStorage:

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

Rutas como objetos

Los activos también pueden ser basados en objetos, utilizando la clase Script. Además, estos permiten pasar atributos HTML personalizados:

class Media:
    js = [
        Script(
            "https://cdn.example.com/something.min.js",
            **{
                "crossorigin": "anonymous",
                "async": True,
            },
        ),
    ]

Si esta definición de Media se hubiera de renderizar, se convertiría en el siguiente código HTML:

<script src="https://cdn.example.com/something.min.js"
        crossorigin="anonymous"
        async>
</script>

Se agregó la clase objeto Script.

Objetos Media

Cuando interrogas la propiedad media de un widget o formulario, el valor que se devuelve es un objeto forms.Media. Como ya hemos visto, la representación en cadena de un objeto Media es el código HTML necesario para incluir los archivos relevantes en el bloque <head> de tu página HTML.

Sin embargo, los objetos Media tienen algunas otras propiedades interesantes.

Subconjuntos de activos

Si solo deseas archivos de un tipo particular, puedes utilizar el operador subíndice para filtrar un medio de interés. Por ejemplo:

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

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

Cuando utilizas el operador subíndice, el valor que se devuelve es un nuevo objeto Media – pero uno que contiene únicamente los medios de interés.

Combinación de objetos Media

Los objetos Media también pueden sumarse. Cuando dos objetos Media se suman, el objeto Media resultante contiene la unión de los activos especificados por ambos:

>>> 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="https://static.example.com/pretty.css" media="all" rel="stylesheet">
<script src="https://static.example.com/animations.js"></script>
<script src="https://static.example.com/actions.js"></script>
<script src="https://static.example.com/whizbang.js"></script>

Orden de activos

El orden en que se insertan los activos en el DOM a menudo es importante. Por ejemplo, puede tener un script que depende de jQuery. Por lo tanto, la combinación de objetos Media intenta preservar el orden relativo en que se definen los activos en cada clase Media.

Por ejemplo:

>>> 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 src="https://static.example.com/jQuery.js"></script>
<script src="https://static.example.com/calendar.js"></script>
<script src="https://static.example.com/time.js"></script>
<script src="https://static.example.com/noConflict.js"></script>

La combinación de objetos Media con activos en un orden conflictivo produce una advertencia MediaOrderConflictWarning.

Media en Formularios

Las herramientas no son los únicos objetos que pueden tener definiciones media – también las formas pueden definir media. Las reglas para las definiciones media en las formas son las mismas que las reglas para las herramientas: las declaraciones pueden ser estáticas o dinámicas; las reglas de ruta y herencia para esas declaraciones son exactamente las mismas.

Independientemente de si defines una declaración media, todos los objetos Form tienen una propiedad media. El valor predeterminado de esta propiedad es el resultado de sumar las definiciones media para todos los widgets que forman parte de la forma:

>>> 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="https://static.example.com/pretty.css" media="all" rel="stylesheet">
<script src="https://static.example.com/animations.js"></script>
<script src="https://static.example.com/actions.js"></script>
<script src="https://static.example.com/whizbang.js"></script>

Si deseas asociar activos adicionales con un formulario —por ejemplo, CSS para la disposición del formulario— agrega una declaración de Media al formulario:

>>> 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="https://static.example.com/pretty.css" media="all" rel="stylesheet">
<link href="https://static.example.com/layout.css" media="all" rel="stylesheet">
<script src="https://static.example.com/animations.js"></script>
<script src="https://static.example.com/actions.js"></script>
<script src="https://static.example.com/whizbang.js"></script>
« previous | up | next »