feature symfony#8204 Reworded some explanations in the basic Webpack Encore example (javiereguiluz)

weaverryan · weaverryan · commit 15935098e4e8 · 2017-11-16T14:27:54.000+02:00
This PR was squashed before being merged into the 3.3 branch (closes symfony#8204). Discussion ---------- Reworded some explanations in the basic Webpack Encore example There are two main ways of using Webpack: * Old apps: generate 1 app.css and 1 app.js file for the entire website * New apps: generate 1 CSS and 1 JS for each "entry" (each important section) I feel that the existing article tries to mix both. That's why we use "global.scss" as the name of the CSS file instead of "app.scss" to avoid name collisions with the "app.css" generated by "app.js" entry. I propose to use first the old way and then explain better the modern way. Commits ------- 478b93d More rewords and removed the addStyleEntry() method f855793 Typo 381570d Reworded some explanations in the basic Webpack Encore example
diff --git a/frontend/encore/simple-example.rst b/frontend/encore/simple-example.rst
@@ -4,10 +4,20 @@ First Example
 Imagine you have a simple project with one CSS and one JS file, organized into
 an ``assets/`` directory:
 
-* ``assets/js/main.js``
-* ``assets/css/global.scss``
+* ``assets/js/app.js``
+* ``assets/css/app.scss``
 
-With Encore, we can easily minify these files, pre-process ``global.scss``
+Let's consider that the project follows the recommended practice of importing
+the CSS files for their associated JavaScript files:
+
+.. code-block:: javascript
+
+    // assets/js/app.js
+    require('../css/app.scss');
+
+    // ...rest of JavaScript code here
+
+With Encore, we can easily minify these files, pre-process ``app.scss``
 through Sass and a *lot* more.
 
 Configuring Encore/Webpack
@@ -22,20 +32,17 @@ Inside, use Encore to help generate your Webpack configuration.
     var Encore = require('@symfony/webpack-encore');
 
     Encore
-        // directory where all compiled assets will be stored
+        // the project directory where all compiled assets will be stored
         .setOutputPath('web/build/')
 
-        // what's the public path to this directory (relative to your project's document root dir)
+        // the public path used by the web server to access the previous directory
         .setPublicPath('/build')
 
         // empty the outputPath dir before each build
         .cleanupOutputBeforeBuild()
 
-        // will output as web/build/app.js
-        .addEntry('app', './assets/js/main.js')
-
-        // will output as web/build/global.css
-        .addStyleEntry('global', './assets/css/global.scss')
+        // will create web/build/app.js and web/build/app.css
+        .addEntry('app', './assets/js/app.js')
 
         // allow sass/scss files to be processed
         .enableSassLoader()
@@ -83,7 +90,7 @@ Actually, to use ``enableSassLoader()``, you'll need to install a few
 more packages. But Encore will tell you *exactly* what you need.
 
 After running one of these commands, you can now add ``script`` and ``link`` tags
-to the new, compiled assets (e.g. ``/build/global.css`` and ``/build/app.js``).
+to the new, compiled assets (e.g. ``/build/app.css`` and ``/build/app.js``).
 In Symfony, use the ``asset()`` helper:
 
 .. code-block:: twig
@@ -93,7 +100,7 @@ In Symfony, use the ``asset()`` helper:
     <html>
         <head>
             <!-- ... -->
-            <link rel="stylesheet" href="{{ asset('build/global.css') }}">
+            <link rel="stylesheet" href="{{ asset('build/app.css') }}">
         </head>
         <body>
             <!-- ... -->
@@ -124,7 +131,7 @@ Great! Use ``require()`` to import ``jquery`` and ``greet.js``:
 
 .. code-block:: javascript
 
-    // assets/js/main.js
+    // assets/js/app.js
 
     // loads the jquery package from node_modules
     var $ = require('jquery');
@@ -141,32 +148,23 @@ That's it! When you build your assets, jQuery and ``greet.js`` will automaticall
 be added to the output file (``app.js``). For common libraries like jQuery, you
 may want also to :doc:`create a shared entry </frontend/encore/shared-entry>` for better performance.
 
-Requiring CSS Files from JavaScript
------------------------------------
+Multiple JavaScript Entries
+---------------------------
 
-Above, you created an entry called ``app`` that pointed to ``main.js``:
+The previous example is the best way to deal with SPA (Single Page Applications)
+and very simple applications. However, as your application grows, you'll need to
+define more entries with the JavaScript and CSS code of some specific sections
+(homepage, blog, store, etc.)
 
 .. code-block:: javascript
 
     Encore
         // ...
-        .addEntry('app', './assets/js/main.js')
+        .addEntry('homepage', './assets/js/homepage.js')
+        .addEntry('blog', './assets/js/blog.js')
+        .addEntry('store', './assets/js/store.js')
     ;
 
-Once inside ``main.js``, you can even require CSS files:
-
-.. code-block:: javascript
-
-    // assets/js/main.js
-    // ...
-
-    // a CSS file with the same name as the entry js will be output
-    require('../css/main.scss');
-
-Now, both an ``app.js`` **and** an ``app.css`` file will be created. You'll need
-to add a link tag to the ``app.css`` file in your templates:
-
-.. code-block:: diff
-
-    <link rel="stylesheet" href="{{ asset('build/global.css') }}">
-    + <link rel="stylesheet" href="{{ asset('build/app.css') }}">
+If those entries include CSS/Sass files (e.g. ``homepage.js`` requires
+``assets/css/homepage.scss``), two files will be generated for each of them
+(e.g. ``build/homepage.js`` and ``build/homepage.css``).
