Adding docs around the new "css" Encore functions and disabling file tracking

Author: weaverryan

frontend.rst

@@ -69,6 +69,7 @@ Guides
 
 * :doc:`Using Bootstrap CSS & JS </frontend/encore/bootstrap>`
 * :doc:`Creating Page-Specific CSS/JS </frontend/encore/page-specific-assets>`
+* :doc:`Rendering Multiple Templates in a Request: Emails, PDFs </frontend/encore/file-tracking>`
 * :doc:`jQuery and Legacy Applications </frontend/encore/legacy-applications>`
 * :doc:`Passing Information from Twig to JavaScript </frontend/encore/server-data>`
 * :doc:`webpack-dev-server and Hot Module Replacement (HMR) </frontend/encore/dev-server>`

frontend/encore/faq.rst

@@ -78,8 +78,8 @@ like ``/myAppSubdir``), you will need to configure that when calling ``Encore.se
     +     .setManifestKeyPrefix('build')
     ;
 
-If you're using the ``encore_entry_script_tags()`` and ``encore_entry_link_tags()``
-Twig shortcuts (or are :ref:`processing your assets through entrypoints.json <load-manifest-files>`
+If you're using one of the ``encore_entry_*()`` Twig shortcuts like
+``encore_entry_script_tags()`` (or are :ref:`processing your assets through entrypoints.json <load-manifest-files>`
 in some other way) you're done! These shortcut methods read from an
 :ref:`entrypoints.json <encore-entrypointsjson-simple-description>` file that will
 now contain the subdirectory.

frontend/encore/file-tracking.rst

@@ -0,0 +1,87 @@
+Rendering Multiple Templates in a Request: Emails, PDFs
+=======================================================
+
+When you render your script or link tags with the Twig helper functions
+(e.g. ``encore_entry_link_tags()``), WebpackEncoreBundle is smart enough
+not to repeat the same JavaScript or CSS file within the same request.
+This prevents you from having duplicate ``<link>`` or ``<script>`` tags
+if you render multiple entries that rely on the same file.
+
+But if you're purposely rendering multiple templates in the same
+request - e.g. rendering a template for a PDF or to send an email -
+then this can cause problems: the later templates won't include any
+``<link>`` or ``<script>`` tags that were rendered in an earlier template.
+
+The easiest solution is to render the raw CSS and JavaScript using
+a special function that *always* returns the full source, even for files
+that were already rendered.
+
+This works especially well in emails thanks to the
+`inline_css`_ filter:
+
+.. code-block:: html+twig
+
+    {% apply inline_css(encore_entry_css_source('my_entry')) %}
+        <div>
+            Hi! The CSS from my_entry will be converted into
+            inline styles on any HTML elements inside.
+        </div>
+    {% endapply %}
+
+Or you can just render the source directly.
+
+.. code-block:: html+twig
+
+    <style>
+        {{ encore_entry_css_source('my_entry')|raw }}
+    </style>
+
+    <script>
+        {{ encore_entry_js_source('my_entry')|raw }}
+    </script>
+
+If you can't use these `encore_entry_*_source` functions, you can instead
+manually disable and enable "file tracking":
+
+.. code-block:: html+twig
+
+    {% do encore_disable_file_tracking() %}
+        {{ encore_entry_link_tags('entry1') }}
+        {{ encore_entry_script_tags('entry1') }}
+    {% do encore_enable_file_tracking() %}
+
+With this, *all* JS and CSS files for `entry1` will be rendered and
+this won't affect any other Twig templates rendered in the request.
+
+Resetting the File Tracking
+---------------------------
+
+If using ``encore_disable_file_tracking()`` won't work for you for some
+reason, you can also "reset" EncoreBundle's internal cache so that the
+bundle re-renders CSS or JS files that it previously rendered. For
+example, in a controller::
+
+
+    // src/Controller/SomeController.php
+
+    use Symfony\WebpackEncoreBundle\Asset\EntrypointLookupInterface;
+
+    class SomeController
+    {
+        public function index(EntrypointLookupInterface $entrypointLookup)
+        {
+            $entrypointLookup->reset();
+            // render a template
+
+            $entrypointLookup->reset();
+            // render another template
+
+            // ...
+        }
+    }
+
+If you have multiple builds, you can also autowire
+``Symfony\WebpackEncoreBundle\Asset\EntrypointLookupCollectionInterface``
+and use it to get the ``EntrypointLookupInterface`` object for any build.
+
+.. _`inline_css`: https://github.com/twigphp/cssinliner-extra

mailer.rst

@@ -464,6 +464,22 @@ called ``css`` that points to the directory where ``email.css`` lives:
             # point this wherever your css files live
             '%kernel.project_dir%/assets/css': css
 
+Using Encore CSS Files
+~~~~~~~~~~~~~~~~~~~~~~
+
+If you're using :ref:`Webpack Encore <frontend-webpack-encore>`, you can also
+include the CSS from your built files. Suppose you create an ``email`` entry to
+contain your email styles:
+
+.. code-block:: html+twig
+
+    {% apply inline_css(encore_entry_css_source('email')) %}
+        <h1>Welcome {{ username }}!</h1>
+        {# ... #}
+    {% endapply %}
+
+Any CSS for your ``email`` entry will now be included and inlined.
+
 .. _mailer-markdown:
 
 Rendering Markdown Content