adding helper filters url and static (aio-libs#97)

samuelcolvin · asvetlov · commit a6e9ad554c52 · 2017-09-09T11:43:06.000+03:00
* adding helper filters url and static * switching to contextfunction * rename test_jinja_globals.py & add tests * adding docs for url and static functions * full coverage to please codecov * @asvetlov's comments on aio-libs#130 * adapting as per comments
diff --git a/.gitignore b/.gitignore
@@ -53,4 +53,5 @@ docs/_build/
 # PyBuilder
 target/
 
-coverage/
+coverage/
+.idea/
diff --git a/aiohttp_jinja2/__init__.py b/aiohttp_jinja2/__init__.py
@@ -4,6 +4,7 @@
 from collections import Mapping
 from aiohttp import web
 from aiohttp.abc import AbstractView
+from .helpers import GLOBAL_HELPERS
 
 
 __version__ = '0.13.0'
@@ -17,19 +18,17 @@
 
 
 def setup(app, *args, app_key=APP_KEY, context_processors=(),
-          filters=None, **kwargs):
+          filters=None, default_helpers=True, **kwargs):
     env = jinja2.Environment(*args, **kwargs)
+    if default_helpers:
+        env.globals.update(GLOBAL_HELPERS)
     if filters is not None:
         env.filters.update(filters)
     app[app_key] = env
     if context_processors:
         app[APP_CONTEXT_PROCESSORS_KEY] = context_processors
         app.middlewares.append(context_processors_middleware)
 
-    def url(__aiohttp_jinja2_route_name, **kwargs):
-        return app.router[__aiohttp_jinja2_route_name].url_for(**kwargs)
-
-    env.globals['url'] = url
     env.globals['app'] = app
 
     return env
diff --git a/aiohttp_jinja2/helpers.py b/aiohttp_jinja2/helpers.py
@@ -0,0 +1,50 @@
+"""
+useful context functions, see
+http://jinja.pocoo.org/docs/dev/api/#jinja2.contextfunction
+"""
+import jinja2
+
+
+@jinja2.contextfunction
+def url_for(context, __route_name, **parts):
+    """
+    filter for generating urls, see
+    http://aiohttp.readthedocs.io/en/stable/web.html#reverse-url-constructing-using-named-resources
+
+    Usage: {{ url('the-view-name') }} might become "/path/to/view" or
+    {{ url('item-details', id=123, query={'active': 'true'}) }} might become "/items/1?active=true".
+    """
+    app = context['app']
+
+    query = None
+    if 'query_' in parts:
+        query = parts.pop('query_')
+
+    url = app.router[__route_name].url_for(**parts)
+    if query:
+        url = url.with_query(query)
+    return url
+
+
+@jinja2.contextfunction
+def static_url(context, static_file_path):
+    """
+    filter for generating urls for static files. NOTE: you'll need
+    to set app['static_root_url'] to be used as  the root for the urls returned.
+
+    Usage: {{ static('styles.css') }} might become "/static/styles.css" or "http://mycdn.example.com/styles.css"
+    """
+    app = context['app']
+    try:
+        static_url = app['static_root_url']
+    except KeyError:
+        raise RuntimeError('app does not define a static root url '
+                           '"static_root_url", you need to set the url root '
+                           'with `app[\'static_root_url\'] = \'<static root>\'`.')
+    return '{}/{}'.format(static_url.rstrip('/'), static_file_path.lstrip('/'))
+
+
+GLOBAL_HELPERS = dict(
+    url=url_for,
+    static=static_url,
+)
diff --git a/docs/index.rst b/docs/index.rst
@@ -97,17 +97,70 @@ As you can see, there is a built-in :func:`request_processor`, which
 adds current :class:`aiohttp.web.Request` into context of templates
 under ``'request'`` name.
 
-By default there are two aiohttp specific :attr:`jinja2.Environment().globals` available in templates:
+Default Globals
+...............
 
-- ``url``: Resolve a named route url
-- ``app``: Use any properties on the app instance
+.. highlight:: html+jinja
+
+``app`` is always made in templates via :attr:`jinja2.Environment().globals`::
 
     <body>
         <h1>Welcome to {{ app['name'] }}</h1>
+    </body>
+
+
+Two more helpers are also enabled by default: ``url`` and ``static``.
+
+``url`` can be used with just a view name::
+
+    <body>
         <a href="{{ url('index') }}">Index Page</a>
     </body>
 
 
+Or with arguments::
+
+    <body>
+        <a href="{{ url('user', id=123) }}">User Page</a>
+    </body>
+
+A query can be added to the url with the special ``query_`` keyword argument::
+
+    <body>
+        <a href="{{ url('user', id=123, query_={'foo': 'bar'}) }}">User Page</a>
+    </body>
+
+
+For a view defined by ``app.router.add_get('/user-profile/{id}/', user, name='user')``, the above would give::
+
+    <body>
+        <a href="/user-profile/123/?foo=bar">User Page</a>
+    </body>
+
+
+This is useful as it would allow your static path to switch in deployment or testing with just one line.
+
+The ``static`` function has similar usage, except it requires you to set ``static_root_url`` on the app
+
+.. code-block:: ruby
+
+    app = web.Application()
+    aiohttp_jinja2.setup(app,
+        loader=jinja2.FileSystemLoader('/path/to/templates/folder'))
+    app['static_root_url'] = '/static'
+
+Then in the template::
+
+        <script src="{{ static('dist/main.js') }}"></script>
+
+
+Would result in::
+
+        <script src="/static/dist/main.js"></script>
+
+
+Both ``url`` and ``static`` can be disabled by passing ``default_helpers=False`` to ``aiohttp_jinja2.setup``.
+
 Library Installation
 --------------------
 
diff --git a/tests/test_jinja_globals.py b/tests/test_jinja_globals.py
@@ -41,3 +41,96 @@ def other(request):
     assert 200 == resp.status
     txt = yield from resp.text()
     assert '/user/John_Doe' == txt
+
+
+@asyncio.coroutine
+def test_url_with_query(test_client, loop):
+
+    @aiohttp_jinja2.template('tmpl.jinja2')
+    @asyncio.coroutine
+    def index(request):
+        return {}
+
+    app = web.Application(loop=loop)
+    aiohttp_jinja2.setup(app, loader=jinja2.DictLoader(
+        {'tmpl.jinja2':
+         "{{ url('index', query_={'foo': 'bar'})}}"}))
+
+    app.router.add_get('/', index, name='index')
+    client = yield from test_client(app)
+
+    resp = yield from client.get('/')
+    assert 200 == resp.status
+    txt = yield from resp.text()
+    assert '/?foo=bar' == txt
+
+
+@asyncio.coroutine
+def test_helpers_disabled(test_client, loop):
+
+    @aiohttp_jinja2.template('tmpl.jinja2')
+    @asyncio.coroutine
+    def index(request):
+        return {}
+
+    @asyncio.coroutine
+    def other(request):
+        return
+
+    app = web.Application(loop=loop)
+    aiohttp_jinja2.setup(
+        app,
+        default_helpers=False,
+        loader=jinja2.DictLoader(
+            {'tmpl.jinja2': "{{ url('index')}}"})
+    )
+
+    app.router.add_route('GET', '/', index)
+    app.router.add_route('GET', '/user/{name}', other, name='other')
+    client = yield from test_client(app)
+
+    resp = yield from client.get('/')
+    assert 500 == resp.status  # url function is not defined
+
+
+@asyncio.coroutine
+def test_static(test_client, loop):
+
+    @aiohttp_jinja2.template('tmpl.jinja2')
+    @asyncio.coroutine
+    def index(request):
+        return {}
+
+    app = web.Application(loop=loop)
+    aiohttp_jinja2.setup(app, loader=jinja2.DictLoader(
+        {'tmpl.jinja2':
+         "{{ static('whatever.js') }}"}))
+
+    app['static_root_url'] = '/static'
+    app.router.add_route('GET', '/', index)
+    client = yield from test_client(app)
+
+    resp = yield from client.get('/')
+    assert 200 == resp.status
+    txt = yield from resp.text()
+    assert '/static/whatever.js' == txt
+
+
+@asyncio.coroutine
+def test_static_var_missing(test_client, loop):
+
+    @aiohttp_jinja2.template('tmpl.jinja2')
+    @asyncio.coroutine
+    def index(request):
+        return {}
+
+    app = web.Application(loop=loop)
+    aiohttp_jinja2.setup(app, loader=jinja2.DictLoader(
+        {'tmpl.jinja2':
+         "{{ static('whatever.js') }}"}))
+
+    app.router.add_route('GET', '/', index)
+    client = yield from test_client(app)
+
+    resp = yield from client.get('/')
+    assert 500 == resp.status  # static_root_url is not set
