Readme revamp

rvlb · rvlb · commit 16099677ee81 · 2021-10-07T23:39:35.000-03:00
diff --git a/README.md b/README.md
@@ -83,11 +83,15 @@ WEBPACK_LOADER = {
 }
 ```
 
-For that setup, we're using the `DEBUG` variable provided by Django when bootstraping a new project. Since in a production environment (`DEBUG = False`) the files won't constantly change, we can safely cache the results and optimize our flow by only fetching the files once.
+For that setup, we're using the `DEBUG` variable provided by Django when bootstraping a new project. Since in a production environment (`DEBUG = False`) the assets files won't constantly change, we can safely cache the results (`CACHE=True`) and optimize our flow, as `django-webpack-loader` will read the stats file only once and store the assets files paths in memory. From that point pnwards, it will use these stored paths as the source of truth. If `CACHE=False`, we'll always read the stats file to get the assets paths.
+> If `CACHE=True`, any changes made in the assets files will only be read when the web workers are restarted.
 
-During development, when files change a lot, we want to always poll for the updated files (in our case, we'll fetch the files every 0.1s, as defined on `POLL_INTERVAL`).
+During development, when the stats file changes a lot, we want to always poll for its updated version (in our case, we'll fetch it every 0.1s, as defined on `POLL_INTERVAL`).
+> In production (`DEBUG=False`), we'll only fetch the stats file once, so `POLL_INTERVAL` is ignored.
 
-`django-webpack-loader` will look for the output file produced by `webpack-bundle-tracker`. Since on Webpack we've named it `webpack-stats.json` and stored it on the project root, we must replicate that setting on the back-end side.
+While `CACHE` isn't directly related to `POLL_INTERVAL`, it's interesting to keep `CACHE` binded to the `DEBUG` logic value (in this case, the negation of the logic value) in order to only cache the assets in production, as we'd not continuously poll the stats file in that environment.
+
+The `STATS_FILE` parameter represents the output file produced by `webpack-bundle-tracker`. Since in the Webpack configuration file we've named it `webpack-stats.json` and stored it on the project root, we must replicate that setting on the back-end side.
 
 `IGNORE` is a list of regular expressions. If a file generated by Webpack matches one of the expressions, the file will not be included in the template.
 
@@ -229,8 +233,65 @@ qwe
 </html>
 ```
 
+### Multiple Webpack projects
+Version 1.0 and up of `django-webpack-loader` also supports multiple Webpack configurations. The following configuration defines 2 Webpack stats files in settings and uses the `config` argument in the template tags to influence which stats file to load the bundles from.
+
+```python
+WEBPACK_LOADER = {
+    'DEFAULT': {
+        'BUNDLE_DIR_NAME': 'bundles/',
+        'STATS_FILE': os.path.join(BASE_DIR, 'webpack-stats.json'),
+    },
+    'DASHBOARD': {
+        'BUNDLE_DIR_NAME': 'dashboard_bundles/',
+        'STATS_FILE': os.path.join(BASE_DIR, 'webpack-stats-dashboard.json'),
+    }
+}
+```
+
+```HTML+Django
+{% load render_bundle from webpack_loader %}
+
+<html>
+  <body>
+    ....
+    {% render_bundle 'main' 'js' 'DEFAULT' %}
+    {% render_bundle 'main' 'js' 'DASHBOARD' %}
+
+    <!-- or render all files from a bundle -->
+    {% render_bundle 'main' config='DASHBOARD' %}
+
+    <!-- the following tags do the same thing -->
+    {% render_bundle 'main' 'css' 'DASHBOARD' %}
+    {% render_bundle 'main' extension='css' config='DASHBOARD' %}
+    {% render_bundle 'main' config='DASHBOARD' extension='css' %}
+
+    <!-- add some extra attributes to the tag -->
+    {% render_bundle 'main' 'js' 'DEFAULT' attrs='async charset="UTF-8"'%}
+  </body>
+</head>
+```
+
+### File URLs instead of html tags
+
+If you need the URL to an asset without the HTML tags, the `get_files` template tag can be used. A common use case is specifying the URL to a custom css file for a Javascript plugin.
+
+`get_files` works exactly like `render_bundle` except it returns a list of matching files and lets you assign the list to a custom template variable. For example:
+
+```HTML+Django
+{% get_files 'editor' 'css' as editor_css_files %}
+CKEDITOR.config.contentsCss = '{{ editor_css_files.0.publicPath }}';
+
+<!-- or list down name, path and download url for every file -->
+<ul>
+{% for css_file in editor_css_files %}
+    <li>{{ css_file.name }} : {{ css_file.path }} : {{ css_file.publicPath }}</li>
+{% endfor %}
+</ul>
+```
+
 ### Code splitting
-In case you wish to use code-splitting, follow the recipe below on the Javascript side.
+In case you wish to use [code-splitting](https://webpack.js.org/guides/code-splitting/), follow the recipe below on the Javascript side.
 
 Create your entrypoint file and add elements to the DOM, while leveraging the lazy imports.
 ```js
