MAGEDOC-3430: Clarify Storefront customization

Updated content after reading more about DI.

Author: bdenham

docs/configurations/storefront-configuration.md

@@ -1,72 +1,63 @@
 # Storefront customization
 
-You can customize Page Builder content types by adding your own logic on the frontend, as described here.
+A storefront widget is JavaScript code that handles the behavior of a content type after Page Builder renders it on the storefront. For example, the Tabs and Sliders have their own storefront widgets to handle the end-user's tapping of tabs and the swiping of slides. 
 
-## Step 1: Create a JavaScript widget
+Adding a storefront widget to your content type is a simple two-step process:
 
-Create a JavaScript widget in your module's `/view/frontend/web/js/content-type/{content-type-name}/appearance/{appearance-name}/widget.js` file:
 
-``` javascript
-/**
- * Copyright © Magento, Inc. All rights reserved.
- * See COPYING.txt for license details.
- */
 
+![How to add storefront widget](../images/how-to-add-storefront-widget.svg)
+
+
+
+## Step 1: Create the JavaScript
+
+Name your JavaScript file `widget.js` and put it in the following directory structure: `/view/base/web/js/content-type/{content-type-name}/appearance/{appearance-name}/widget.js`. An example from the PageBuilderQuote content type follows:
+
+![Where to add storefront widget](../images/where-to-add-widget.png){:width="477px" height="auto"}
+
+The JavaScript for the widget can handle events, initialize third-party controls, or do whatever else you need in order to control your content type's behavior _after_ Page Builder renders the master format template on the frontend.
+
+``` javascript
 define([
     'jquery',
-    'slick'
 ], function ($) {
     'use strict';
 
-    return function (config, sliderElement) {
-
-        var $element = $(sliderElement);
-
-        /**
-         * Prevent each slick slider from being initialized more than once which could throw an error.
-         */
-        if ($element.hasClass('slick-initialized')) {
-            $element.slick('unslick');
-        }
-
-        $element.slick({
-            autoplay: $element.data('autoplay') === 1,
-            autoplaySpeed: $element.data('autoplay-speed') || 0,
-            fade: $element.data('fade') === 1,
-            infinite: $element.data('is-infinite') === 1,
-            arrows: $element.data('show-arrows') === 1,
-            dots: $element.data('show-dots') === 1
-        });
+    return function (config, element) {
+        var element = $(element);
+        console.log("ELEMENT: " + element.data('element'));
     };
 });
-
 ```
 
-## Step 2: Add XML configuration
-
-The XML configuration loads the widget on the frontend, and on the stage, so that you can preview content inside both the block and dynamic block content types.
+## Step 2: Configure the widget initializer
 
-Add the following configuration to the `etc/di.xml` file in your custom module directory:
+To configure your `widget.js` so that Page Builder can initialize and load it on the storefront, create a new `WidgetInitializerConfig` type in your module's global `di.xml` file (`etc/di.xml`). Then add your configuration (that includes your widget) as a replacement argument. The following example is from the PageBuilderQuote module:
 
 ``` xml
+<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
 <type name="Magento\PageBuilder\Model\WidgetInitializerConfig">
     <arguments>
         <argument name="config" xsi:type="array">
-            <item name="%content-type-name%" xsi:type="array">
+                <item name="example_quote" xsi:type="array">
                 <!-- Name is the appearance name -->
                 <item name="default" xsi:type="array">
                     <!--required argument-->
-                    <item name="component" xsi:type="string">%{vendor-path}/js/content-type/{content-type-name}/appearance/{appearance-name}/widget%</item>
-                    <!--optional if you need provide some config for your widget-->
-                    <item name="config" xsi:type="array">
-                        <item name="buttonSelector" xsi:type="string">.pagebuilder-slide-button</item>
-                        <item name="showOverlay" xsi:type="string">hover</item>
+                        <item name="component" xsi:type="string">Example_PageBuilderQuote/js/content-type/example-quote/appearance/default/widget</item>
                     </item>
-                    <!--optional if you want load widget per appearance-->
-                    <item name="appearance" xsi:type="string">default</item>
                 </item>
-            </item>
         </argument>
     </arguments>
 </type>
-```
+</config>
+```
+
+The XML configuration loads the widget on the frontend, and on the stage, so you can preview content inside both the block and dynamic block content types.
+
+**^^^ I don't understand the reference to blocks and dynamic blocks in the previous sentence.**
+
+**^^^ Is the `WidgetInitializerConfig` class just automatically instantiated for the frontend? When is it instantiated? During the rendering of the storefront/frontend?**
+
+
+