diff --git a/common/images/widget/loader-widget-result.png b/common/images/widget/loader-widget-result.png new file mode 100644 index 00000000000..7f837fc8011 Binary files /dev/null and b/common/images/widget/loader-widget-result.png differ diff --git a/guides/v2.2/javascript-dev-guide/widgets/widget_loader.md b/guides/v2.2/javascript-dev-guide/widgets/widget_loader.md index 7fba316cad0..765caca08d4 100644 --- a/guides/v2.2/javascript-dev-guide/widgets/widget_loader.md +++ b/guides/v2.2/javascript-dev-guide/widgets/widget_loader.md @@ -6,13 +6,37 @@ title: Loader widget ## Overview -The Loader [widget](https://glossary.magento.com/widget) blocks page content (all content or a part of it). Its intended use is blocking content when an Ajax request is being sent. But it can be initialized for non-Ajax tasks as well. +The Loader [widget](https://glossary.magento.com/widget) blocks page content (all content or a part of it). Its intended use is blocking content when an Ajax request is being sent, but it can be initialized for non-Ajax tasks as well. The Loader widget source is [lib/web/mage/loader.js]. ## Initialize the loader widget {#loader_init} -The loader widget is initialized as described in [JavaScript initialization]. +For information about how to initialize a widget in a JS component or `.phtml` template, see the [Initialize JavaScript][] topic. + +The following example shows how to instantiate the Loader widget: + +```javascript +$('#example').loader({ + icon: 'path to icon' +}); +``` + +Where: + +- `#element` is the selector of the element for Loader is initialized. + +```html + +``` ## Options {#loader_options} @@ -22,6 +46,7 @@ The loader widget has the following options: - [texts](#l_texts) ### `icon` {#l_icon} + The URL to the loader image. This image is displayed when the widget is active; that is, between the `ajaxSend` and `ajaxComplete` events. **Type**: String @@ -29,6 +54,7 @@ The URL to the loader image. This image is displayed when the widget is active; **Default value**: No image by default. ### `template` {#l_template} + HTML wrapper for the output, or a DOM element selector. **Default value**: @@ -81,6 +107,7 @@ Loader is subscribed to the following events: - [processStop](#l_processStop) ### `processStart` {#l_processStart} + Display the loader. Can be triggered on any page element. Start show loading: @@ -89,6 +116,16 @@ Start show loading: $("body").trigger('processStart'); ``` +The following is an example of adding a callback to `processStart` event. + +```javascript +var callback = function () { + // do something before showing the loader +}; + +$("body").on('processStart', callback); +``` + ### `processStop` {#l_processStop} Hide the loader. Can be triggered on any page element. @@ -98,5 +135,39 @@ Stop show loading: $("body").trigger('processStop'); ``` +The following is an example of adding a callback to a `processStop` event. + +```javascript +var callback = function () { + // do something before hiding the loader +}; + +$("body").on('processStop', callback); +``` + +## Code Sample + +The following example shows the loader when a `processStart` event triggers for the `#loader-example` element. + +```html +
+

Block

+ Lorem ipsum dolor sit amet, consectetur adipisicing elit. Dignissimos itaque numquam placeat quam recusandae velit voluptas. Ad architecto asperiores eos eveniet id nostrum officiis saepe soluta totam voluptate! Debitis, quibusdam. +
+ +``` + +## Result + +The loader shows when a `processStart` event triggers for the `#loader-example` element. + +![Loader Widget Example]({{ site.baseurl }}/common/images/widget/loader-widget-result.png) + [lib/web/mage/loader.js]: {{ site.mage2bloburl }}/{{ page.guide_version }}/lib/web/mage/loader.js -[JavaScript initialization]: {{page.baseurl}}/javascript-dev-guide/javascript/js_init.html +[Initialize JavaScript]: {{page.baseurl}}/javascript-dev-guide/javascript/js_init.html