Merge pull request #2 from shonin/dev

v0.0.2

.gitignore

@@ -2,4 +2,8 @@ db.sqlite3
 .idea
 __pycache__
 .pyc
-.DS_Store
+.DS_Store
+dist
+node_modules
+*.egg-info
+build

LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) @shonin and individual contributors.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+    1. Redistributions of source code must retain the above copyright notice,
+       this list of conditions and the following disclaimer.
+
+    2. Redistributions in binary form must reproduce the above copyright
+       notice, this list of conditions and the following disclaimer in the
+       documentation and/or other materials provided with the distribution.
+
+    3. Neither the name of Easy Django Webpack nor the names of its contributors may
+       be used to endorse or promote products derived from this software without
+       specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+include README.md
+prune example_project*

README.md

@@ -0,0 +1,169 @@
+# Easy Django webpack
+
+_Always have access to the latest assets, with minimal configuration. Wraps Django's built in 
+`{% static %}` templatetag to allow you to link to assets according to a webpack manifest file._
+
+**Turns this**
+
+```djangotemplate
+{% load static %}
+<script src="{% static 'main.8f7705adfa281590b8dd.js' %}"></script>
+```
+
+**Into this**
+
+```djangotemplate
+{% load manifest %}
+<script src="{% manifest 'main.js' %}"></script>
+```
+
+## Installation
+
+```shell script
+pip install easy_django_webpack
+```
+
+## Setup
+
+```python
+# settings.py
+
+INSTALLED_APPS = [
+    ...
+    'easy_django_webpack',
+    ...
+]
+```
+
+You must add webpack's output directory to the `STATICFILES_DIRS` list. 
+If your webpack configuration is to output all files into a directory `dist/` that is 
+in the `BASE_DIR` of your project, then you would set it like. 
+
+```python
+# settings.py
+STATICFILES_DIRS = [
+    BASE_DIR / 'dist'
+]
+```
+
+`BASE_DIR`'s default value is `BASE_DIR = Path(__file__).resolve().parent.parent`, in general 
+you shouldn't be modifying it. _Hint: the `BASE_DIR` is the directory your `manage.py` file is in._
+
+**Optional settings,** default values shown.
+```python
+# settings.py
+
+WEBPACK_SETTINGS = {
+    'output_dir': BASE_DIR / 'dist',  # where webpack outputs to. 
+    'manifest_file': 'manifest.json',  # name of your manifest file
+    'cache': False,  # recommended True for production, requires a server restart to pickup new values from the manifest.
+    'ignore_missing_assets': False  # recommended True for production. Otherwise raises an exception if a file is not in the manifest.
+}
+```
+
+## Webpack example
+
+Install webpack:
+
+```shell script
+npm i --save-dev webpack webpack-cli
+```
+
+Install recommended plugins
+```shell script
+npm i --save-dev webpack-manifest-plugin clean-webpack-plugin
+```
+
+```javascript
+// webpack.config.js
+
+const path = require('path');
+const {CleanWebpackPlugin} = require('clean-webpack-plugin');
+const ManifestPlugin = require('webpack-manifest-plugin');
+
+module.exports = {
+  entry: './frontend/src/index.js',
+  plugins: [
+      new CleanWebpackPlugin(),  // removes outdated assets from the output dir
+      new ManifestPlugin(),  // generates the required manifest.json file
+  ],
+  output: {
+    filename: '[name].[contenthash].js',  // renames files from example.js to example.8f77someHash8adfa.js
+    path: path.resolve(__dirname, 'dist'), // output to BASE_DIR/dist, assumes webpack.json is on the same level as manage.py
+  },
+};
+```
+
+```javascript
+// package.json
+...
+"scripts": {
+  "start": "webpack"
+},
+...
+```
+
+## Usage
+
+```djangotemplate
+{% load manifest %}
+
+<script src="{% manifest 'main.js' %}"></script>
+```
+
+turns into
+
+```html
+<script src="/static/main.8f7705adfa281590b8dd.js"></script>
+```
+
+## About
+
+At it's heart `easy_django_webpack` is an extension to Django's built-in `static` templatetag. 
+When you use the provided `{% manifest %}` templatetag, all `easy_django_webpack` is doing is 
+taking the input string, looking it up against the manifest file, modifying the value, and then
+passing along the result to the `{% static %}` template tag. 
+
+### Suggested Project Structure
+
+```
+BASE_DIR
+├── dist
+│   ├── main.f82c02a005f7f383003c.js
+│   └── manifest.json
+├── frontend
+│   ├── apps.py
+│   ├── src
+│   │   └── index.js
+│   ├── templates
+│   │   └── frontend
+│   │       └── index.html
+│   └── views.py
+├── manage.py
+├── package.json
+├── project
+│   ├── settings.py
+│   ├── urls.py
+│   └── wsgi.py
+├── requirements.txt
+└── webpack.config.js
+```
+
+### Manifest File and Content Hash (the problem this package solves)
+
+When you put a content hash in the filename of an asset file, it serves as a sort of versioning mechanism
+for your assets. Every time the content changes, the hash changes. And when the hash changes, the browser sees that it 
+doesn't have that asset file, it drops it's 
+cached version of your old assets and gets the new one. If you only use the name `main.js` for your assets, the browser
+will just think, oh hey I have this file in my cache, and it won't check for updates. So then your users 
+won't see the latest changes unless they do a browser cache refresh, which isn't something you can expect.
+
+So you can see why you want the content hash in the filename. The manifest.json file is a way to provide a mapping
+from the original file name to the new one. If you didn't have a way to automate that mapping, every time you generate
+a new version of your assets, you'd have to go into your HTML and update the content hash yourself. Instead, you
+can just tell `easy_django_webpack` that you want the file `main.js` and it'll lookup the content hash for you. 
+
+### License 
+
+Easy Django Webpack is distributed under the [3-clause BSD license](https://opensource.org/licenses/BSD-3-Clause). 
+This is an open source license granting broad permissions to modify and redistribute the software.

easy_django_webpack/templatetags/manifest.py

@@ -0,0 +1,69 @@
+import json
+import os
+
+from django import template
+from django.templatetags.static import do_static
+from django.conf import settings
+from django.core.cache import cache
+
+register = template.Library()
+
+APP_SETTINGS = {
+    'output_dir': settings.BASE_DIR / 'dist',
+    'manifest_file': 'manifest.json',
+    'cache': False,
+    'ignore_missing_assets': False,
+}
+
+if hasattr(settings, 'WEBPACK_SETTINGS'):
+    APP_SETTINGS.update(settings.WEBPACK_SETTINGS)
+
+
+@register.tag('manifest')
+def manifest(parser, token):
+    cached_manifest = cache.get('webpack_manifest')
+    path = os.path.join(APP_SETTINGS['output_dir'],
+                        APP_SETTINGS['manifest_file'])
+
+    if APP_SETTINGS['cache'] and cached_manifest:
+        data = cached_manifest
+    else:
+        try:
+            with open(path) as manifest_file:
+                data = json.load(manifest_file)
+        except FileNotFoundError:
+            raise WebpackManifestNotFound(path)
+
+        if APP_SETTINGS['cache']:
+            cache.set('webpack_manifest', data)
+
+    hashed_filename = data.get(parse_filename(token))
+    if hashed_filename:
+        token.contents = "webpack '{}'".format(hashed_filename)
+    elif not APP_SETTINGS['ignore_missing_assets']:
+        raise AssetNotFoundInWebpackManifest(parse_filename(token), path)
+
+    return do_static(parser, token)
+
+
+def parse_filename(token):
+    return token.contents.split("'")[1]
+
+
+class WebpackManifestNotFound(Exception):
+    def __init__(self, path, message='Manifest file named {} not found. '
+                                     'Looked for it at {}. Either your '
+                                     'settings are wrong or you need to still '
+                                     'generate the file.'):
+        super().__init__(message.format(APP_SETTINGS['manifest_file'], path))
+
+
+class AssetNotFoundInWebpackManifest(Exception):
+    def __init__(self, file, path, message='File {} is not referenced in the '
+                                           'manifest file located at {}. Make '
+                                           'sure webpack is outputting it. If '
+                                           'you would like to suppress this '
+                                           'error set WEBPACK_SETTINGS['
+                                           '"ignore_missing_assets"] '
+                                           'to True'):
+        super().__init__(message.format(file, path))

easy_django_webpack/views.py

@@ -1,3 +0,0 @@
-from django.shortcuts import render
-
-# Create your views here.

example_project/frontend/src/index.js

@@ -0,0 +1 @@
+document.getElementById("main").innerText = 'It works!';

example_project/frontend/templates/frontend/index.html

@@ -0,0 +1,4 @@
+{% load manifest %}
+
+<h1 id="main"></h1>
+<script src="{% manifest 'maddin.js' %}"></script>

example_project/frontend/views.py

@@ -0,0 +1,7 @@
+from django.shortcuts import HttpResponse, render
+from django.conf import settings
+
+
+def home(request):
+    return render(request, 'frontend/index.html')
+    # return HttpResponse(settings.WEBPACK_SETTINGS.get('output_dir'))