mirror of
https://github.com/jupyterhub/jupyterhub.git
synced 2025-10-15 14:03:02 +00:00
90 lines
3.6 KiB
Markdown
90 lines
3.6 KiB
Markdown
# Working with templates and UI
|
|
|
|
The pages of the JupyterHub application are generated from
|
|
[Jinja](http://jinja.pocoo.org/) templates. This allows the header to be defined once and incorporated into all pages. By providing your templates, you can have complete control over JupyterHub's
|
|
appearance.
|
|
This document will provide information on how to:
|
|
- [add custom templates](#custom-templates)
|
|
- [extend templates](#extending-templates)
|
|
- [add announcements to a page](#page-announcements)
|
|
|
|
## Custom Templates
|
|
|
|
JupyterHub will look for custom templates in all of the paths in the
|
|
`JupyterHub.template_paths` configuration option, falling back on the
|
|
[default templates](https://github.com/jupyterhub/jupyterhub/tree/HEAD/share/jupyterhub/templates)
|
|
if no custom template with that name is found. This fallback
|
|
behavior is new in version 0.9; previous versions searched only the paths
|
|
explicitly included in `template_paths`. You may override as many
|
|
or as few templates as you desire.
|
|
|
|
## Extending Templates
|
|
|
|
Jinja provides a mechanism to [extend templates](http://jinja.pocoo.org/docs/2.10/templates/#template-inheritance).
|
|
A base template can define a `block`, and child templates can replace or
|
|
supplement the material in the block. The
|
|
[JupyterHub templates](https://github.com/jupyterhub/jupyterhub/tree/HEAD/share/jupyterhub/templates)
|
|
make extensive use of blocks, which allows you to customize parts of the interface easily.
|
|
|
|
In general, a child template can extend a base template, `page.html`, by beginning with:
|
|
|
|
```html
|
|
{% extends "page.html" %}
|
|
```
|
|
|
|
This works if you are trying to extend the default template for the same
|
|
file name. Starting in version 0.9, you may refer to the base file with a
|
|
`templates/` prefix. Thus, if you are writing a custom `page.html`, start the
|
|
file with this block:
|
|
|
|
```html
|
|
{% extends "templates/page.html" %}
|
|
```
|
|
|
|
By defining `block`s with the same name as in the base template, child templates
|
|
can replace those sections with custom content. The content from the base
|
|
template can be included with the `{{ super() }}` directive.
|
|
|
|
### Example
|
|
|
|
To add an additional message to the spawn-pending page, below the existing
|
|
text about the server starting up, place this content in a file named
|
|
`spawn_pending.html` in a directory included in the
|
|
`JupyterHub.template_paths` configuration option.
|
|
|
|
```html
|
|
{% extends "templates/spawn_pending.html" %} {% block message %} {{ super() }}
|
|
<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](#extending-templates)
|
|
- 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 variables requires a restart, unlike direct
|
|
template extension.
|
|
|
|
Alternatively, 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` takes precedence over an extension of a specific
|
|
page (unlike the variable-based approach above).
|