finishing read-through

Author: weaverryan

frontend/encore/bootstrap.rst

@@ -41,29 +41,17 @@ Bootstrap JavaScript requires jQuery and Popper.js, so make sure you have this i
 
 .. code-block:: terminal
 
-    $ yarn add jquery --dev
-    $ yarn add popper.js --dev
+    $ yarn add jquery popper.js --dev
 
-Next, make sure to call ``.autoProvidejQuery()`` in your ``webpack.config.js`` file:
-
-.. code-block:: diff
-
-    // webpack.config.js
-    Encore
-        // ...
-    +     .autoProvidejQuery()
-    ;
-
-This is needed because Bootstrap expects jQuery to be available as a global
-variable. Now, require bootstrap from any of your JavaScript files:
+Now, require bootstrap from any of your JavaScript files:
 
 .. code-block:: javascript
 
     // app.js
 
     const $ = require('jquery');
-    // JS is equivalent to the normal "bootstrap" package
-    // no need to set this to a variable, just require it
+    // this "modifies" the jquery module: adding behavior to it
+    // the bootstrap module doesn't export/return anything
     require('bootstrap');
 
     // or you can include specific pieces
@@ -74,8 +62,13 @@ variable. Now, require bootstrap from any of your JavaScript files:
         $('[data-toggle="popover"]').popover();
     });
 
-Thanks to ``autoProvidejQuery()``, you can require any other jQuery
-plugins in a similar way:
+Using other Bootstrap / jQuery Plugins
+--------------------------------------
+
+If you need to use jQuery plugins that work well with jQuery, you may need to use
+Encore's :ref:`autoProvidejQuery() <encore-autoprovide-jquery>` method so that
+these plugins know where to find jQuery. Then, you can include the needed JavaScript
+and CSS like normal:
 
 .. code-block:: javascript
 

frontend/encore/dev-server.rst

@@ -1,12 +1,12 @@
 Using webpack-dev-server and HMR
 ================================
 
-While developing, instead of using ``encore dev --watch``, you can use the
+While developing, instead of using ``yarn encore dev --watch``, you can use the
 `webpack-dev-server`_:
 
 .. code-block:: terminal
 
-    $ ./node_modules/.bin/encore dev-server
+    $ yarn encore dev-server
 
 This serves the built assets from a new server at ``http://localhost:8080`` (it does
 not actually write any files to disk). This means your ``script`` and ``link`` tags
@@ -22,7 +22,7 @@ by the normal `webpack-dev-server`_. For example:
 
 .. code-block:: terminal
 
-    $ ./node_modules/.bin/encore dev-server --https --port 9000
+    $ yarn encore dev-server --https --port 9000
 
 This will start a server at ``https://localhost:9000``.
 

frontend/encore/legacy-apps.rst

@@ -1,5 +1,5 @@
-jQuery and Legacy Applications
-==============================
+jQuery Plugins and Legacy Applications
+======================================
 
 Inside Webpack, when you require a module, it does *not* (usually) set a global variable.
 Instead, it just returns a value:
@@ -10,30 +10,25 @@ Instead, it just returns a value:
     const $ = require('jquery');
 
 In practice, this will cause problems with some outside libraries that *rely* on
-jQuery to be global. It will be a problem if some of *your* JavaScript isn't being
-processed through Webpack (e.g. you have some JavaScript in your templates).
-
-Using Libraries that Expect jQuery to be Global
------------------------------------------------
-
-Some legacy JavaScript applications use programming practices that don't play
-well with the new practices promoted by Webpack. The most common of these
-problems is using code (e.g. jQuery plugins) that assume that jQuery is already
-available via the ``$`` or ``jQuery`` global variables. If those variables
-are not defined, you'll get these errors:
+jQuery to be global *or* if *your* JavaScript isn't being processed through Webpack
+(e.g. you have some JavaScript in your templates) and you need jQuery. Both will
+cause similar errors:
 
 .. code-block:: text
 
     Uncaught ReferenceError: $ is not defined at [...]
     Uncaught ReferenceError: jQuery is not defined at [...]
 
-Instead of rewriting everything, Encore allows for a different solution. Thanks
-to the ``autoProvidejQuery()`` method, whenever a JavaScript file uses the ``$``
-or ``jQuery`` variables, Webpack automatically requires ``jquery`` and creates
-those variables for you.
+The fix depends on what code is causing the problem.
+
+.. _encore-autoprovide-jquery:
 
-So, when working with legacy applications, you may need to add the following to
-``webpack.config.js``:
+Fixing jQuery Plugins that Expect jQuery to be Global
+-----------------------------------------------------
+
+jQuery plugins often expect that jQuery is already available via the ``$`` or
+``jQuery`` global variables. To fix this, call ``autoProvidejQuery()`` from your
+``webpack.config.js`` file:
 
 .. code-block:: diff
 
@@ -42,6 +37,10 @@ So, when working with legacy applications, you may need to add the following to
     +     .autoProvidejQuery()
     ;
 
+After restarting Encore, Webpack will look for all uninitialized ``$`` and ``jQuery``
+variables and automatically require ``jquery`` and set those variables for you.
+It "rewrites" the "bad" code to be correct.
+
 Internally, this ``autoProvidejQuery()`` method calls the ``autoProvideVariables()``
 method from Encore. In practice, it's equivalent to doing:
 
@@ -61,25 +60,27 @@ method from Encore. In practice, it's equivalent to doing:
 Accessing jQuery from outside of Webpack JavaScript Files
 ---------------------------------------------------------
 
-If you also need to provide access to ``$`` and ``jQuery`` variables outside of
+If *your* code needs access to ``$`` or ``jQuery`` and you are inside of a file
+that's processed by Webpack/Encore, you should remove any "$ is not defined" errors
+by requiring jQuery: ``var $ = require('jquery')``.
+
+But if you also need to provide access to ``$`` and ``jQuery`` variables outside of
 JavaScript files processed by Webpack (e.g. JavaScript that still lives in your
 templates), you need to manually set these as global variables in some JavaScript
 file that is loaded before your legacy code.
 
-For example, you could define a ``common.js`` file that's processed by Webpack and
-loaded on every page with the following content:
+For example, in your ``app.js`` file that's processed by Webpack and loaded on every
+page, add:
 
-.. code-block:: javascript
+.. code-block:: diff
 
     // require jQuery normally
     const $ = require('jquery');
 
-    // create global $ and jQuery variables
-    global.$ = global.jQuery = $;
-
-.. tip::
+    + // create global $ and jQuery variables
+    + global.$ = global.jQuery = $;
 
-    The ``global`` variable is a special way of setting things in the ``window``
-    variable. In a web context, using ``global`` and ``window`` are equivalent,
-    except that ``window.jQuery`` won't work when using ``autoProvidejQuery()``.
-    In other words, use ``global``.
+The ``global`` variable is a special way of setting things in the ``window``
+variable. In a web context, using ``global`` and ``window`` are equivalent,
+except that ``window.jQuery`` won't work when using ``autoProvidejQuery()``.
+In other words, use ``global``.

frontend/encore/page-specific-assets.rst

@@ -23,5 +23,5 @@ page-specific JavaScript and CSS file from a page-specific entry (e.g. ``checkou
 
 .. tip::
 
-    Be sure to use split chunks :doc:`shared entry </frontend/encore/split-chunks>`
+    Be sure to use :doc:`split chunks </frontend/encore/split-chunks>`
     to avoid duplicating and shared code between your entry files.

frontend/encore/server-data.rst

@@ -19,6 +19,9 @@ Fetch this in JavaScript:
     document.addEventListener('DOMContentLoaded', function() {
         var userRating = document.querySelector('.js-user-rating');
         var isAuthenticated = userRating.dataset.isAuthenticated;
+
+        // or with jQuery
+        //var isAuthenticated = $('.js-user-rating').data('isAuthenticated');
     });
 
 .. note::

frontend/encore/split-chunks.rst

@@ -63,7 +63,4 @@ this plugin with the ``configureSplitChunks()`` function:
     +         splitChunks.minSize = 0;
     +     }
 
-- talk about SplitChunksPlugin & how you talk to it in Encore
-- also look at the runtime chunk stuff
-
 .. _`SplitChunksPlugin from Webpack`: https://webpack.js.org/plugins/split-chunks-plugin/