datasette.urls.table() / .instance() / .database() methods for constructing URLs, also exposed to templates

[simonw]

I tried using this block of template in a plugin and got an error:

{% block nav %}
    <p class="crumbs">
        <a href="{{ base_url }}">home</a> /
        <a href="{{ database_url(database) }}">{{ database }}</a> /
        <a href="{{ database_url(database) }}/{{ table|quote_plus }}">{{ table }}</a>
    </p>
    {{ super() }}
{% endblock %}

Error: 'database_url' is undefined

That's because database_url is only made available by the BaseView template here:

datasette/datasette/views/base.py

Lines 110 to 125 in d6e03b0

	async def render(self, templates, request, context=None):
	context = context or {}
	template = self.ds.jinja_env.select_template(templates)
	template_context = {
	**context,
	**{
	"database_url": self.database_url,
	"database_color": self.database_color,
	"select_templates": [
	"{}{}".format(
	"*" if template_name == template.name else "", template_name
	)
	for template_name in templates
	],
	},
	}

[simonw]

Tracking ticket: #1023

[simonw]

Here's the current implementation of database_url - on the BaseView class, but only because it needs access to a datasette instance (to read base_url):

datasette/datasette/views/base.py

Lines 102 to 108 in 8f97b9b

	def database_url(self, database):
	db = self.ds.databases[database]
	base_url = self.ds.config("base_url")
	if self.ds.config("hash_urls") and db.hash:
	return "{}{}-{}".format(base_url, database, db.hash[:HASH_LENGTH])
	else:
	return "{}{}".format(base_url, database)

[simonw]

I think this should be a family of functions:

• instance_url() - the root URL of the instance (usually / unless base_url is set)
• database_url(database_name) - already got this
• table_url(database_name, table_name)
• row_url(database_name, table_name, row) - not sure about this one. The idea would be for row to be correctly turned into a URL by introspecting the primary keys for that table, then pulling those values out of the SQLite row object. Might not be necessary though.

I also need a way for plugins to link to e.g. /-/configure-fts - or even /-/configure-fts/database-name/table-name. What should that look like?

[simonw]

Could have instance_url() take an optional path argument which is then turned into the correct path.

[simonw]

Alternatively, I could expose a single object that knows how to construct all kinds of URLs. Something like this:

{{ urls.instance() }}
{{ urls.database(database_name) }}
{{ urls.table(database_name, table_name) }}
etc

[simonw]

If I do these methods I think this should be available on the datasette object too, as an internal API for plugins to use to construct redirects and suchlike.

[simonw]

Related: #1026 (How should datasette.client interact with base_url)

Also this comment from #943 (comment)

One thing to consider here: Datasette's table and database name escaping rules can be a little bit convoluted.

If a plugin wants to get back the first five rows of a table, it will need to construct a URL /dbname/tablename?_size=5 - but it will need to know how to turn the database and table names into the correctly escaped dbname and tablename values.

[simonw]

Options:

• datasette.urls.instance() (or datasette.urls.root()), datasette.urls.table() etc
• datasette.url_for.instance()...
• datasette.url.instance()...
• datasette.root_url(), datasette.table_url()...

[simonw]

I quite like datasette.urls.table() but I'm not sure why.

[simonw]

OK, I'm committing to datasette.urls.table() and friends, which will be available to (and documented for use in) plugins and will be exposed to templates as {{ urls.table(...) }}.

[simonw]

Documentation is https://docs.datasette.io/en/latest/writing_plugins.html#building-urls-within-plugins and https://docs.datasette.io/en/latest/internals.html#internals-datasette-urls