Hooks HTML

Plugster lee sus entradas del DOM vía un conjunto pequeño y fijo de atributos data-*. Esta página es la referencia para cada uno: qué hace, dónde va, y qué hace el framework con él en los momentos de init() y plug(). La mayoría ya aparecieron en páginas anteriores — esta es la búsqueda rápida consolidada.

data-controller-name #

Marca un elemento HTML como vista de un Plugster y lo vincula a una clase controladora del mismo nombre. El valor del atributo es el nombre PascalCase de la clase, igualado exactamente. 

        
            <div data-controller-name="ExchangeRatesPlugster">
                <!-- esta región pertenece a ExchangeRatesPlugster -->
            </div>

El framework escanea el documento en busca de estos atributos una vez, cuando el primer Plugster de la página llama a Plugster.plug(). Cualquier tipo de elemento sirve — <div>, <form>, incluso <body>. Varias vistas pueden compartir el mismo nombre de clase solo si también provees un controllerName explícito como segundo argumento del constructor; de lo contrario el mapeo clase-a-vista es uno-a-uno.

data-outlet-id #

Declara un elemento como outlet de su vista contenedora. El valor del atributo es el identificador del outlet, usado por el controlador como this._.<identifier>. Los identificadores de outlets son camelCase y únicos dentro de su vista dueña. 

        
            <div data-controller-name="SignInPlugster">
                <input data-outlet-id="emailInput" type="email">
                <button data-outlet-id="submitButton">Sign in</button>
            </div>

Los outlets que viven dentro de una vista anidada pertenecen al controlador de esa vista anidada, no al externo. El límite es estricto — un controlador externo no puede alcanzar los outlets de una vista interna a través de this._. Ver Conceptos básicos → La vista para la regla de anidamiento en detalle.

data-child-templates #

Marca un outlet como habilitado-para-lista. El valor del atributo es un array JSON de una o más URLs que apuntan a archivos HTML estáticos que el framework descargará y cacheará. Cada URL es una plantilla de fila; el controlador escoge cuál usar por ítem vía el primer argumento de buildListItem. 

        
            <div data-outlet-id="ratesList"
                 data-child-templates='["rate-row-template.html"]'>
            </div>

El framework descarga cada URL de plantilla una vez y cachea la respuesta en Plugster.childTemplateHtmlCache durante la vida de la página; las peticiones concurrentes para la misma URL comparten un único jqXHR en vuelo vía Plugster.childTemplateRequestCache. Varios Plugsters declarando la misma URL pagan el costo de red una sola vez.

Las plantillas hijas son HTML estático — no las procesa el motor de plantillas del servidor, así que helpers como {{ _() }} o {{ render_snippet() }} no están disponibles dentro. Usan data-child-outlet-id en lugar de data-outlet-id para sus outlets internos; Outlets de lista cubre el patrón completo.

data-on-{publicador}-{evento} #

Declara una suscripción a nivel HTML: el controlador de esta vista quiere escuchar un evento con nombre que viene de otro Plugster. El valor del atributo es el nombre del método handler en la clase suscriptora.

La regla de nombrado para el atributo en sí es mecánica:

  • Nombre del publicador: el nombre de la clase del Plugster publicador, completamente en minúsculas.
  • Nombre del evento: el nombre del evento publicado, completamente en minúsculas.
  • Separador: guiones simples entre on, publicador y evento.
        
            <div data-controller-name="DataLoaderPlugster"
                 data-on-workspaceplugster-bucketpresenterready="setup"
                 data-on-themetogglerplugster-themechanged="handleThemeChanged">
                ...
            </div>

En este ejemplo, DataLoaderPlugster escucha a dos publicadores — el evento bucketPresenterReady de WorkspacePlugster (mapeado a su propio método setup) y el evento themeChanged de ThemeTogglerPlugster (mapeado a handleThemeChanged).

El framework cablea estas suscripciones en el momento de Plugster.plug(). El método handler DEBE existir en la clase suscriptora — si no, el framework lanza una excepción. Las suscripciones son bidireccionales en el sentido del registro (ambos, publicador y suscriptor, deben estar registrados para que los eventos fluyan), pero el cableado es de una vía: el publicador despacha, el suscriptor recibe.

Para Plugsters que no existen en la página al momento de carga — típicamente porque se instancian dinámicamente desde dentro de otro controlador — usa la API explícita listenTo en su lugar. Ver Eventos.

data-lang #

Lleva el código del idioma activo al elemento de la vista, para que el controlador pueda recogerlo en tiempo de ejecución. El atributo es típicamente puesto por la plantilla del servidor que renderiza la página: 

        
            <div data-controller-name="SignInPlugster"
                 data-lang="{{ lang_code }}">
                ...
            </div>

Dentro del controlador, léelo a través del outlet implícito root: 

        
            afterInit() {
                this.lang = this._.root.data('lang');
                this._.titleLabel.text(this.translateTo(this.lang, 'Welcome'));
            }

El framework en sí no hace nada con data-lang — es una convención, no una característica. La razón por la que tiene una entrada dedicada en esta página es que los helpers de localización (setLocales / translateTo, cubiertos en Localización) esperan que this.lang esté configurado, y leerlo desde data-lang es la forma estándar de hacerlo.

Atributos reservados dentro de plantillas hijas #

Los archivos HTML estáticos usados como plantillas hijas usan un conjunto paralelo de atributos — cubiertos por completo en Outlets de lista:

  • data-child-outlet-id — outlet declarado dentro de una plantilla hija.
  • data-key — clave por ítem, escrita por el framework cuando un ítem se construye vía buildListItem.

Estos son de solo lectura desde la perspectiva del autor de la página; los declaras en la plantilla pero nunca los configuras desde afuera.

En resumen # 

        
            data-controller-name="PascalCaseName"          → vincula vista a clase controladora
            data-outlet-id="camelCaseId"                   → declara un outlet
            data-child-templates='["url.html", ...]'       → habilita el outlet como lista
            data-on-{pubname}-{eventname}="handler"        → suscripción declarada en HTML
            data-lang="{{ lang_code }}"                    → lleva idioma activo a la vista

            (solo dentro de archivos de plantilla hija)
            data-child-outlet-id="camelCaseId"             → outlet dentro de un ítem de lista
            data-key                                       → clave por ítem, gestionada por el framework
Content