Fandom Developers Wiki
Advertisement

BannerNotification es una biblioteca JavaScript que envuelve la biblioteca BannerNotification incorporada para UCP.

Además, trae de vuelta soporte para insertar automáticamente notificaciones de banner sobre modales visibles. Actualmente, esto es compatible con los modales de Modal.js.

Añadiendo[]

Para añadir la biblioteca en sus propios scripts, use:

importArticle({
    type: 'script',
    article: 'u:dev:MediaWiki:BannerNotification.js'
});

El constructor de BannerNotification no estará disponible de inmediato, pero puede esperar cuando esté disponible usando el hook dev.banners:

mw.hook('dev.banners').add(function(BannerNotification) {
    // BannerNotification is the banner constructor
    new BannerNotification('Hello world', 'notify').show();
    // You can also access it with `window.dev.banners.BannerNotification`, but it's advised to keep your own reference to it
});

Uso[]

Construcción[]

Una vez que tenga acceso al constructor BannerNotification, puede crearlas con la interfaz normal.

new BannerNotification(content, type, $parent, timeout)
content - Contenido de la notificación. Si es una cadena de texto, se interpretará como HTML. Asegúrese de sanitizar adecuadamente todo lo que le pase. Si es algo que no sea una cadena de texto, va a ser convertido en una cadena. Esto significa que los objetos jQuery o las instancias de Element no serán útiles. Por lo tanto, cualquier evento deberá adjuntarse después de la construcción y que se muestre con .show() utilizando la propiedad .$element como se demuestra más adelante en la documentación.
type - Tipo de notificación. Cadena de texto. Los valores posibles son: notify, confirm, warn, error
$parent - El contenedor que contiene la notificación. Debe ser un objeto jQuery.
timeout - Tiempo de espera de visualización de notificaciones en milisegundos. Por defecto, no hay tiempo de espera.

Métodos[]

Llamar a métodos sobre objetos BannerNotification es la forma más común de interactuar con ellos, además de construirlos. La mayoría de las veces, solo tendrás que preocuparte por mostrarlos.

.show()
Muestra la notificación. Si un modal está en primer plano, se añadirá encima a menos que se haya pasado $parent explícitamente al constructor.
.hide()
Oculta la notificación.
.setType(type)
Establece el tipo de notificación. No actualiza el icono del banner si .show() ya se ha invocado sin volver a ocultarlo. Se recomienda no utilizar este método, en su lugar, construir un nuevo objeto una vez que se calcule el tipo.
Los posibles valores son: notify, confirm, warn, error
.setContent(content)
Establece el contenido de la notificación. No actualiza el contenido del banner si .show() ya ha invocado sin que se vuelva a ocultar. Se recomienda no utilizar este método y, en su lugar, construir un nuevo objeto una vez que se calcule el contenido.
.onClose(handler)
Establece una devolución de llamada para cuando se cierra la notificación. Solo puede haber una devolución de llamada a la vez. No se llama si la notificación caduca por sí sola después de que se agota el tiempo de espera.

Propiedades[]

El objeto BannerNotification devuelto tiene muchas propiedades disponibles. Es raro tener que usarlas, pero hay casos específicos en las que necesitará usarlas. Varios casos complejos se pueden encontrar en la sección de ejemplos.

.$element
Objeto jQuery para el banner. Será nulo si .show aún no se llamó o si .hide se llamó. Más específicamente, será nulo cuando la propiedad .hidden sea true. Esta propiedad es útil si desea adjuntar oyentes de eventos al contenido del banner o interactuar con ellos.
.$parent
El objeto jQuery pasó como padre en la construcción. No se actualizará con el padre calculado automáticamente si no se proporciona en la construcción. Si no se adjuntó ninguno en construcción, no estará definido.
.content
La cadena de contenido. Se actualizará si se usa .setContent.
.type
El tipo de cadena. Se actualizará si se usa .setType.
.hidden
Booleano que indica si el banner está oculto o no. Llamar a .show establecerá esto en false, y llamar a .hide lo establecerá en true.
.onCloseHandler
El controlador actual para cuando se cierra la notificación. Si no se pasó ninguno, será una función que no hace nada. Esta propiedad puede ser útil si desea establecer un controlador cercano, pero también desea mantener una referencia al controlador anterior para poder llamarlo después de que se ejecute el nuevo.

Ejemplos[]

Esta es la interacción más simple que se puede tener con BannerNotifications. También es la más común y, con bastante frecuencia, todo lo que realmente necesita saber para usar esta biblioteca.

mw.hook('dev.banners').add(function(BannerNotification) {
    new BannerNotification('Hello', 'notify').show();
});

Si está usando mensajes internacionalizados, como probablemente debería hacerlo, con i18n-js, debe usar .escape() o .parse() para asegurarse de no exponer accidentalmente sus scripts a ataques XSS.

// Here we're assuming that you have an instance `i18n` of your script's messages
mw.hook('dev.banners').add(function(BannerNotification) {
    new BannerNotification(i18n.msg('banner-content').escape(), 'notify').show();
});

Si desea tener un padre personalizado al que adjuntar las notificaciones del banner, puede usar el tercer parámetro. Este es uno de los casos de uso más raros, pero puede ser útil con interfaces de usuario específicas.

mw.hook('dev.banners').add(function(BannerNotification) {
    // Attach to the article's content. It will look weird, but hey, this is just an example!
    var $parent = $('#mw-content-text');

    new BannerNotification('This is the article content. I bet it\'s totally wrong!', 'notify', $parent).show();
});

Si desea establecer un tiempo de espera para que su banner se desvanezca automáticamente, puede usar el cuarto parámetro. Tenga en cuenta cómo se pasa indefinido como el tercer parámetro $parent, ya que no estamos interesados ​​en establecer un padre personalizado. También puede usar null, aunque undefined es el valor predeterminado estándar.

mw.hook('dev.banners').add(function(BannerNotification) {
    new BannerNotification('I will fade out after 2 seconds', 'notify', undefined, 2000).show();
});

Si desea adjuntar eventos al elemento de notificación del banner, tendrá que mantener una referencia a él con una variable. Entonces puedes usar la propiedad $element para hacer lo que quieras. El siguiente ejemplo implementará un tiempo de espera cancelable que actualmente no es posible con el parámetro de tiempo de espera que proporciona el constructor de BannerNotification, y es el más complicado de los ejemplos de esta sección.

mw.hook('dev.banners').add(function(BannerNotification) {
    var banner = new BannerNotification('This notification will automatically hide itself unless you click me before 5 seconds pass. Click me now!', 'notify').show();
    var $content = banner.$element.find('.wds-banner-notification__text');

    var timeoutId = setTimeout(function() {
        banner.hide();
    }, 5000);

    $content.on('click', function() {
        clearTimeout(timeoutId);
        alert('Congratulations, you have successfully averted disaster!');
        $content.text('We are all safe now');

        // Note: This will not update the icon! Not yet, anyway, it's a bit of an oversight in the library I guess
        // It's only useful when reusing an instance that you repeatedly hide and show, but this pattern is discouraged
        banner.setType('confirm');
    });

    banner.onClose(function() {
        alert('No! How dare you close it manually! Do you have ANY idea what you\'ve just done???');
    });
});
Advertisement