server extensions have no simple way to use templates

[jcb91]

#879 provides a simple command to install a server extension, based upon values returned by the magically-named _jupyter_server_extension_paths function. So far each dict in the list returned by this function is seems to support only a single key module, which is the python module name to load for the extension.

Many server extensions also provide templates which the extension renders. Since jupyter uses the template_path setting for Tornado, any templates must exist under one of the directories in the template_path directory (as opposed to the default behaviour of looking for the template in the same directory as the .py file referencing it).

So, should server extensions provide an (optional) extra directory to add to template_path as a key in the return of _jupyter_server_extension_paths, or is there another way of going about this?

[minrk]

cc @ellisonbg @bollwyvl on whether template_path should be added to the metadata spec.

As an escape hatch, server extensions can already extend template paths at load time, just not in a declarative way in this metadata.

[jcb91]

As an escape hatch, server extensions can already extend template paths at load time

Do you mean explicitly altering the NotebookApp's template_file_path in load_jupyter_server_extension?

[bollwyvl]

Or perhaps, more devilishly:

# my_serverextension/__init__.py
import os.path import join, dirname
from notebook.base.handlers import IPythonHandler
from notebook.utils import url_path_join


class MyServerExtensionHandler(IPythonHandler):
    def get(self):
        self.finish(self.render_template("my_serverextension/index.html"
                                         **self.application.settings))


def load_jupyter_server_extension(nb_app):
    base_url = nb_app.web_app.settings["base_url"]

    nb_app.web_app.settings["jinja2_env"].loader.searchpath += [
        join(dirname(__file__), "templates")
    ]

    nb_app.web_app.add_handlers(".*$", [
        (url_path_join(base_url, "my_serverextension"),
            MyServerExtensionHandler),
        ])

this assumes a structure like:

- my_serverextension/
  - __init__.py
  - templates/
    - my_serverextension/
      - index.html

This will not overload the base templates, so if you are trying to change, say, notebook, that won't work. However, if you are adding rendered html handlers, it will work fine.

I don't know if adding it to the metadata is a feasible idea, as we don't actually interrogate the modules at runtime. We'd need a new configuration place for it, I guess.

Further, there is the ever-tricky question of ordering: 4.2 stores the server extensions as a dict, so your extension basically has to be ready to handle whatever comes your way.

[jcb91]

Thanks @bollwyvl for the example. Ok, so I need to alter nb_app.web_app.settings["jinja2_env"].loader.searchpath rather than just nbapp.template_path.

Further, there is the ever-tricky question of ordering

I'm not sure in what case this would matter - is this a problem for extending existing templates?

[bollwyvl]

Further, there is the ever-tricky question of ordering

I'm not sure in what case this would matter - is this a problem for extending existing templates?

Well if two server extensions changed the template path... who wins? if they both overload notebook.html, they can't know which one will actually resolve. It will probably stable-ish, for a given user, but still pretty non-deterministic.

So basically, overloading html templates used in the base NotebookApp are not that good a way to overload parts of the application, as so much of the work happens client-side. Good-neighbor namespacing should be a lot more stable, for custom views: with the namespacing, it's very easy to reuse the upstream templates in their normal location... so you could create a custom notebook endpoint,

http://localhost:8888/my-notebooks/Untitled.ipynb

that worked like the base environment. Not that bad a work-around.

[jcb91]

Ah, gotcha. Well, since for the moment I'm not actually trying to overload anything, just provide new rendering handlers, the simple add-extra-directories-to-search-path works fine for me 😄