Merge pull request #1913 from rkdarst/announcement_text

Add customizable announcement text on home,login,logout,spawn

docs/source/reference/templates.md

@@ -59,3 +59,35 @@ text about the server starting up, place this content in a file named
 <p>Patience is a virtue.</p>
 {% endblock %}
 ```
+
+## Page Announcements
+
+To add announcements to be displayed on a page, you have two options:
+
+- Extend the page templates as described above
+- Use configuration variables
+
+### Announcement Configuration Variables
+
+If you set the configuration variable `JupyterHub.template_vars =
+{'announcement': 'some_text}`, the given `some_text` will be placed on
+the top of all pages.  The more specific variables
+`announcement_login`, `announcement_spawn`, `announcement_home`, and
+`announcement_logout` are more specific and only show on their
+respective pages (overriding the global `announcement` variable).
+Note that changing these varables require a restart, unlike direct
+template extension.
+
+You can get the same effect by extending templates, which allows you
+to update the messages without restarting.  Set
+`c.JupyterHub.template_paths` as mentioned above, and then create a
+template (for example, `login.html`) with:
+
+```html
+{% extends "templates/login.html" %}
+{% set announcement = 'some message' %}
+```
+
+Extending `page.html` puts the message on all pages, but note that
+extending `page.html` take precedence over an extension of a specific
+page (unlike the variable-based approach above).

jupyterhub/tests/test_pages.py

@@ -17,6 +17,7 @@ from .mocking import FormSpawner, public_url, public_host
 from .test_api import api_request, add_user
 from .utils import async_requests
 
+
 def get_page(path, app, hub=True, **kw):
     if hub:
         prefix = app.hub.base_url
@@ -517,3 +518,55 @@ def test_oauth_token_page(app):
 def test_proxy_error(app, error_status):
     r = yield get_page('/error/%i' % error_status, app)
     assert r.status_code == 200
+
+
+@pytest.mark.gen_test
+@pytest.mark.parametrize(
+    "announcements",
+    [
+        "",
+        "spawn",
+        "spawn,home,login",
+        "login,logout",
+    ]
+)
+def test_announcements(app, announcements):
+    """Test announcements on various pages"""
+    # Default announcement - same on all pages
+    ann01 = "ANNOUNCE01"
+    template_vars = {"announcement": ann01}
+    announcements = announcements.split(",")
+    for name in announcements:
+        template_vars["announcement_" + name] = "ANN_" + name
+
+    def assert_announcement(name, text):
+        if name in announcements:
+            assert template_vars["announcement_" + name] in text
+            assert ann01 not in text
+        else:
+            assert ann01 in text
+
+    cookies = yield app.login_user("jones")
+
+    with mock.patch.dict(
+        app.tornado_settings,
+        {"template_vars": template_vars, "spawner_class": FormSpawner},
+    ):
+        r = yield get_page("login", app)
+        r.raise_for_status()
+        assert_announcement("login", r.text)
+        r = yield get_page("spawn", app, cookies=cookies)
+        r.raise_for_status()
+        assert_announcement("spawn", r.text)
+        r = yield get_page("home", app, cookies=cookies)  # hub/home
+        r.raise_for_status()
+        assert_announcement("home", r.text)
+        # need auto_login=True to get logout page
+        auto_login = app.authenticator.auto_login
+        app.authenticator.auto_login = True
+        try:
+            r = yield get_page("logout", app, cookies=cookies)
+        finally:
+            app.authenticator.auto_login = auto_login
+        r.raise_for_status()
+        assert_announcement("logout", r.text)

share/jupyterhub/templates/home.html

@@ -1,4 +1,7 @@
 {% extends "page.html" %}
+{% if announcement_home %}
+  {% set announcement = announcement_home %}
+{% endif %}
 
 {% block main %}
 

share/jupyterhub/templates/login.html

@@ -1,4 +1,7 @@
 {% extends "page.html" %}
+{% if announcement_login %}
+  {% set announcement = announcement_login %}
+{% endif %}
 
 {% block login_widget %}
 {% endblock %}

share/jupyterhub/templates/logout.html

@@ -1,8 +1,14 @@
 {% extends "page.html" %}
+{% if announcement_logout %}
+  {% set announcement = announcement_logout %}
+{% endif %}
+
 {% block main %}
+
 <div id="logout-main" class="container">
   <p>
     Successfully logged out.
   </p>
 </div>
+
 {% endblock %}

share/jupyterhub/templates/page.html

@@ -140,6 +140,16 @@
   </nav>
 {% endblock %}
 
+
+{% block announcement %}
+{% if announcement %}
+<div class="container text-center announcement">
+  {{ announcement | safe }}
+</div>
+{% endif %}
+{% endblock %}
+
+
 {% block main %}
 {% endblock %}
 

share/jupyterhub/templates/spawn.html

@@ -1,4 +1,7 @@
 {% extends "page.html" %}
+{% if announcement_spawn %}
+  {% set announcement = announcement_spawn %}
+{% endif %}
 
 {% block main %}