[v1.1.2] Add new setting 'JINJA_FILTERS'

This new setting enable to register additional template filters.

docs/basics.rst

@@ -113,7 +113,7 @@ Below is a list of all available settings, but not all are created in the settin
 
     Note that you should be carefull to not conflict with files targeted by webassets bundles.
 **JINJA_EXTENSIONS**
-    Comment, uncomment or add new extension path to use with Jinja here.
+    Add new `template extension <https://jinja.palletsprojects.com/en/2.10.x/extensions/#module-jinja2.ext>`_ paths to enable in Jinja.
 
     Default value is : ::
 
@@ -122,6 +122,25 @@ Below is a list of all available settings, but not all are created in the settin
         )
 
     Note that you don't need to manually define the webassets extension if you use it, it is automatically appended within the build process if it detects bundles.
+**JINJA_FILTERS**
+    Register additional `template filters <https://jinja.palletsprojects.com/en/2.10.x/api/#custom-filters>`_.
+    Default value is an empty dictionnary.
+
+    Each item name is the filter name as it will be available from template and item value is the filter function.
+
+    Sample : ::
+
+        def foo(content):
+            return "Foobar: {}".format(content)
+
+        JINJA_FILTERS = {
+            "foobar": foo,
+        }
+
+    Then in template you will be able to do: ::
+
+        {{ "plop"|foobar }}
+
 **PAGES_MAP**
     Python path to the file that contains pages map, this is relative to your project, default value is ``pages``, meaning this will search for ``pages.py`` file in your project directory.
 **I18N_EXTRACT_MAP**

docs/changelog.rst

@@ -8,6 +8,11 @@
 Changelog
 =========
 
+Version 1.1.2 - 2020/01/01
+--------------------------
+
+Add new setting ``JINJA_FILTERS`` to register additional template filters.
+
 Version 1.1.1 - 2019/07/01
 --------------------------
 

optimus/conf/model.py

@@ -73,6 +73,10 @@ def _default_jinja(self):
                 'jinja2.ext.i18n',
             )
 
+        # Template filters to use with Jinja2
+        if not hasattr(self, "JINJA_FILTERS"):
+            self.JINJA_FILTERS = {}
+
     def _default_watchdog(self):
         """
         Set default attributes for required settings Watchdog

optimus/pages/builder.py

@@ -107,6 +107,10 @@ def get_environnement(self, assets_env=None):
             extensions=exts
         )
 
+        # Enable Jinja filters
+        for name, module in self.settings.JINJA_FILTERS.items():
+            env.filters[name] = module
+
         if assets_env:
             env.assets_environment = assets_env
 

setup.cfg

@@ -3,7 +3,7 @@
 ;;
 [metadata]
 name = Optimus
-version = 1.1.1
+version = 1.1.2
 description = Optimus is a static site builder using Jinja2, webassets and Babel.
 long_description = file:README.rst
 long_description_content_type = text/x-rst

tests/02_conf/01_settingsmodel.py

@@ -132,6 +132,8 @@ def test_apply_defaults():
         'jinja2.ext.i18n',
     )
 
+    assert settings.JINJA_FILTERS == {}
+
     assert settings.WEBASSETS_CACHE == os.path.join(projectdir,
                                                     '.webassets-cache')
 

tests/08_builder/02_get_environnement.py

@@ -19,6 +19,9 @@ class DummyExtension(Extension):
         """
         tags = set(['dummy'])
 
+    def DummyFilter(content):
+        return "Nope"
+
     # Get basic sample settings
     projectdir = os.path.join(fixtures_settings.fixtures_path, 'basic_template')
     settings = minimal_basic_settings(projectdir)
@@ -29,6 +32,9 @@ class DummyExtension(Extension):
     # Tamper settings to define only dummy extension
     settings.JINJA_EXTENSIONS = [DummyExtension]
 
+    # Tamper settings to define a dummy filter
+    settings.JINJA_FILTERS = {"dummy_filter": DummyFilter}
+
     # Get new jinja environment
     jinja_env = builder.get_environnement()
 
@@ -37,6 +43,8 @@ class DummyExtension(Extension):
         '02_get_environnement.DummyExtension'
     ]
 
+    assert "dummy_filter" in jinja_env.filters
+
     # Using 'get_environnement' afterwards trigger additional debug log
     assert caplog.record_tuples == [
         (

tests/08_builder/06_build.py

@@ -10,6 +10,10 @@
 from optimus.assets.registry import register_assets
 
 
+def DummyFilter(content):
+    return "DummyFilter: {}".format(content)
+
+
 @pytest.mark.parametrize('sample_fixture_name,attempted_destinations', [
     (
         'basic_template',
@@ -66,6 +70,9 @@ def test_build_item(minimal_basic_settings, fixtures_settings, temp_builds_dir,
     settings.WEBASSETS_CACHE = cache_dir
     settings.WEBASSETS_URLEXPIRE = False
 
+    # Define a dummy filter to test filter registration and usage
+    settings.JINJA_FILTERS = {"dummy_filter": DummyFilter}
+
     # Init webassets and builder
     assets_env = register_assets(settings)
     builder = PageBuilder(settings, assets_env=assets_env)
@@ -147,6 +154,9 @@ def test_build_bulk(minimal_basic_settings, fixtures_settings, temp_builds_dir,
     # Get basic sample settings
     settings = minimal_basic_settings(projectdir)
 
+    # Define a dummy filter to test filter registration and usage
+    settings.JINJA_FILTERS = {"dummy_filter": DummyFilter}
+
     # Init webassets and builder
     assets_env = register_assets(settings)
     builder = PageBuilder(settings, assets_env=assets_env)

tests/data_fixtures/basic_template/sources/templates/index.html

@@ -7,7 +7,8 @@
             <div class="center-block">
                 <h1>{{ SITE.name }}</h1>
                 <p>{% trans %}Hello World!{% endtrans %}</p>
+                <p>{{ "Yep!"|dummy_filter }}</p>
             </div>
         </div>
     </div>
-</div>{% endblock %}
+</div>{% endblock %}

tests/data_fixtures/builds/basic_template/index.html

@@ -25,6 +25,7 @@
             <div class="center-block">
                 <h1>basic</h1>
                 <p>Hello World!</p>
+                <p>DummyFilter: Yep!</p>
             </div>
         </div>
     </div>