зеркало из https://github.com/mozilla/bedrock.git
Add docs for JS lazy-load and notification libs
This commit is contained in:
Alex Gibson
Родитель
cc70e414e7
Коммит
c0210eb10d
|
|
@ -17,3 +17,13 @@ Mozilla Accordion
|
|||
-----------------
|
||||
|
||||
:ref:`mozilla-accordion.js<mozillaaccordion>`
|
||||
|
||||
Mozilla Image Lazy Loader
|
||||
-------------------------
|
||||
|
||||
:ref:`mozilla-lazy-load.js<mozillalazyload>`
|
||||
|
||||
Mozilla Notification Banner
|
||||
---------------------------
|
||||
|
||||
:ref:`mozilla-notification-banner.js<mozillanotificationbanner>`
|
||||
|
|
|
|||
|
|
@ -0,0 +1,76 @@
|
|||
.. This Source Code Form is subject to the terms of the Mozilla Public
|
||||
.. License, v. 2.0. If a copy of the MPL was not distributed with this
|
||||
.. file, You can obtain one at http://mozilla.org/MPL/2.0/.
|
||||
|
||||
.. _mozillalazyload:
|
||||
|
||||
=========================
|
||||
Mozilla Image Lazy Loader
|
||||
=========================
|
||||
|
||||
``mozilla-lazy-load.js`` is a JavaScript library that will lazy load ``<img>`` elements on a web page as the user scrolls the viewport. It requires support for `Intersection Observer API`_, and will fallback to loading all images on page load in non-supporting browsers.**
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
Each image to be lazy loaded requires the following HTML structure::
|
||||
|
||||
<div class="lazy-image-container">
|
||||
<img src="path/to/placeholder.png" data-src="path/to/image.png" alt="">
|
||||
<noscript>
|
||||
<img src="path/to/image.png" alt="">
|
||||
</noscript>
|
||||
</div>
|
||||
|
||||
This HTML snippet is also available via a handy macro that can be imported into any bedrock template::
|
||||
|
||||
{% from "macros.html" import lazy_image with context %}
|
||||
|
||||
The macro can then be used like so in a template like so::
|
||||
|
||||
{{ lazy_image('path/to/image.png', 'path/to/placeholder.png') }}
|
||||
|
||||
To initialize the lazy loading plugin, in your JS run::
|
||||
|
||||
Mozilla.LazyLoad.init();
|
||||
|
||||
Options
|
||||
~~~~~~~
|
||||
|
||||
If you don't want to use the macro provided above and instead use your own HTML, you can pass an alternate custom CSS selecter::
|
||||
|
||||
<div class="my-own-lazy-loading-container">
|
||||
<img src="path/to/placeholder.png" data-src="path/to/image.png" alt="">
|
||||
<noscript>
|
||||
<img src="path/to/image.png" alt="">
|
||||
</noscript>
|
||||
</div>
|
||||
|
||||
Mozilla.LazyLoad.init('.my-own-lazy-loading-container');
|
||||
|
||||
This will instantiate the plugin to observe intersection of elements using the DOM elements matching the selector provided.
|
||||
|
||||
Fading in images
|
||||
----------------
|
||||
|
||||
By default the lazy load plugin will simply swap in images as they load. To add a little extra visual flourish, you can add a custom fade-in effect using CSS::
|
||||
|
||||
.lazy-image-container img {
|
||||
display: block;
|
||||
opacity: 1;
|
||||
transition: opacity 0.3s;
|
||||
}
|
||||
|
||||
.lazy-image-container img[data-src] {
|
||||
opacity: 0;
|
||||
display: none;
|
||||
}
|
||||
|
||||
This works because the plugin removes the ``data-src`` attribute as each image lazy loads.
|
||||
|
||||
Examples
|
||||
--------
|
||||
|
||||
You can view a live example by navigating to ``/firefox/features/`` and scrolling down the page.
|
||||
|
||||
.. _Intersection Observer API: https://developer.mozilla.org/docs/Web/API/Intersection_Observer_API
|
||||
|
|
@ -0,0 +1,132 @@
|
|||
.. This Source Code Form is subject to the terms of the Mozilla Public
|
||||
.. License, v. 2.0. If a copy of the MPL was not distributed with this
|
||||
.. file, You can obtain one at http://mozilla.org/MPL/2.0/.
|
||||
|
||||
.. _mozillanotificationbanner:
|
||||
|
||||
===========================
|
||||
Mozilla Notification Banner
|
||||
===========================
|
||||
|
||||
``mozilla-notification-banner.js`` is a JavaScript library for displaying custom in-page notifications at the top of bedrock web pages. It can be used globally across the site for display over multiple pages, or on a page-by-page basis. It is also capable of displying multiple variations of a notification for A/B testing purposes.
|
||||
|
||||
Dependencies
|
||||
------------
|
||||
|
||||
The notification library requires some additional CSS & JS dependencies:
|
||||
|
||||
- ``css/base/notification-banner.less``
|
||||
- ``css/pebbles/components/_notification-banner.scss``
|
||||
- ``js/base/mozilla-cookie-helper.js``
|
||||
|
||||
.. note::
|
||||
|
||||
All of the above dependencies are currently bundled in all of bedrock's common CSS & JS bundles by default, so they should not need including on a page-by-page basis.
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
To configure a notification, it must be passed one or more ``config`` objects. Each ``config`` is an object literal that relates to a specific message that may be shown to a visitor::
|
||||
|
||||
var config = {
|
||||
'id': 'fx-out-of-date-banner',
|
||||
'name': 'fx-out-of-date',
|
||||
'heading': 'Your Firefox is out-of-date.',
|
||||
'message': 'Get the most recent version to keep browsing securely.',
|
||||
'confirm': 'Update Firefox',
|
||||
'confirmClick': _clickCallback,
|
||||
'url': '/firefox/new/?scene=2',
|
||||
'close': closeText,
|
||||
'gaConfirmAction': 'Update Firefox',
|
||||
'gaConfirmLabel': 'Firefox for Desktop',
|
||||
'gaCloseLabel': 'Close'
|
||||
};
|
||||
|
||||
This object must then be passed to initialize the notification for display::
|
||||
|
||||
Mozilla.NotificationBanner.init(config);
|
||||
|
||||
As long as all the requirements of the config are satisfied, this should be all that's needed in order for the notification to appear. If any of the requirements are not satisifed, the notification will not display. A full list of available options are provided below.
|
||||
|
||||
Options
|
||||
~~~~~~~
|
||||
|
||||
- ``id`` (required) - Unique identifier used to track variations a visitor has seen e.g. ``fx-out-of-date-banner-copy1-direct-1``.
|
||||
- ``name`` (required) - Generic name for the notification type e.g. ``fx-out-of-date``.
|
||||
- ``experimentName`` (optional) - Generic name for tracking a specific experiment in GA e.g. ``fx-out-of-date-banner-copy1``.
|
||||
- ``experimentVariant`` (optional) - Identifier for experiment variation in GA e.g. ``direct-1``.
|
||||
- ``heading`` (required) - Copy string for notification heading.
|
||||
- ``message`` (required) - Copy string for notification message / subheading.
|
||||
- ``confirm`` (required) - Copy string for main CTA button.
|
||||
- ``url`` (required) - URL for main CTA link.
|
||||
- ``close`` (required) - Copy string for close button.
|
||||
- ``gaConfirmAction`` (required) - String for action of CTA button in GA (this should always be English).
|
||||
- ``gaConfirmLabel`` (required) - String for labeling CTA button in GA (this should always be English).
|
||||
- ``gaCloseLabel`` (required) - String for labeling close button in GA (this should always be English).
|
||||
- ``confirmClick`` (optional) - Callback to be executed on confirm CTA click.
|
||||
|
||||
Persistent notifications
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
A notification will be displayed on every visit to a web page where it is instantiated, until a visitor interacts with it either by clicking the main call-to-action button, or closing the notifiction via the close button. Once a visitor interacts with a notification, it will not be displayed again for a **default 21 day** time period (set via a cookie).
|
||||
|
||||
This default expriy date can be changed manually if required::
|
||||
|
||||
Mozilla.NotificationBanner.COOKIE_EXPIRATION_DAYS = 28;
|
||||
|
||||
Testing multiple variations
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To test multiple variations of messaging in a notification, you can also pass an array of ``options`` objects to ``getOptions``::
|
||||
|
||||
var options = [
|
||||
{
|
||||
'id': 'fx-out-of-date-banner-copy1-direct-1',
|
||||
'name': 'fx-out-of-date',
|
||||
'experimentName': 'fx-out-of-date-banner-copy1',
|
||||
'experimentVariant': 'direct-1',
|
||||
'heading': 'Your browser security is at risk.',
|
||||
'message': 'Update Firefox now to protect yourself from the latest malware.',
|
||||
'confirm': 'Update now',
|
||||
'confirmAction': 'Update Firefox',
|
||||
'confirmLabel': 'Firefox for Desktop',
|
||||
'confirmClick': _clickCallback,
|
||||
'url': '/firefox/new/?scene=2',
|
||||
'close': 'Close',
|
||||
'closeLabel': 'Close'
|
||||
},
|
||||
{
|
||||
'id': 'fx-out-of-date-banner-copy1-direct-2',
|
||||
'name': 'fx-out-of-date',
|
||||
'experimentName': 'fx-out-of-date-banner-copy1',
|
||||
'experimentVariant': 'direct-2',
|
||||
'heading': 'Your Firefox is out-of-date.',
|
||||
'message': 'Get the most recent version to keep browsing securely.',
|
||||
'confirm': 'Update Firefox',
|
||||
'confirmAction': 'Update Firefox',
|
||||
'confirmLabel': 'Firefox for Desktop',
|
||||
'confirmClick': _clickCallback,
|
||||
'url': '/firefox/new/?scene=2',
|
||||
'close': 'Close',
|
||||
'closeLabel': 'Close'
|
||||
},
|
||||
];
|
||||
|
||||
var choice = Mozilla.NotificationBanner.getOptions(options);
|
||||
|
||||
if (choice) {
|
||||
Mozilla.NotificationBanner.init(choice);
|
||||
}
|
||||
|
||||
Calling ``Mozilla.NotificationBanner.getOptions(options)`` will pick a variation at random to display if no variation has already been seen. When a visitor sees a random variation, a cookie will be stored with a reference to it's ``id``. This ``id`` is used on repeat visits to ensure that the same variation gets shown again, should the visitor not interact with the notification.
|
||||
|
||||
Setting a sample rate
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You can also set a sample rate limit, if you wish for only a finite percentage of visitors to see a notification::
|
||||
|
||||
Mozilla.NotificationBanner.setSampleRate(0.05); // 5% sample rate
|
||||
|
||||
.. note::
|
||||
|
||||
By default there is no sample rate set, so a notification will display 100% of the time.
|
||||
Загрузка…
Ссылка в новой задаче