Skip to content

Instantly share code, notes, and snippets.

@simonw

simonw/template_contexts.md Secret

Created October 11, 2025 21:22
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save simonw/5b7d87fe5ffa36e7a4c104fcb18fc097 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save simonw/5b7d87fe5ffa36e7a4c104fcb18fc097 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
template_contexts.md

Template Context Reference

This document provides a comprehensive reference of all context variables passed to each template in Datasette. Understanding these variables is essential for creating custom templates and plugins.

Table of Contents

Global Template Variables

All templates inherit from base.html and automatically receive these variables via datasette.render_template() in datasette/app.py:1550-1577:

request

  • Type: Request
  • Description: The ASGI request object containing HTTP request information
  • Source: datasette/app.py:1553

crumb_items

  • Type: callable (async function)
  • Description: Function that generates breadcrumb navigation items based on the current database/table context
  • Source: datasette/app.py:1554

urls

  • Type: Urls
  • Description: URL builder object with methods like instance(), database(), table(), row(), etc. for generating Datasette URLs
  • Source: datasette/app.py:1555

actor

  • Type: dict | None
  • Description: The currently authenticated actor/user object, or None if not authenticated
  • Source: datasette/app.py:1556

menu_links

  • Type: callable (async function)
  • Description: Function that returns list of navigation menu links from plugins via the menu_links hook
  • Source: datasette/app.py:1557

display_actor

  • Type: function
  • Description: Function to format actor information for display
  • Source: datasette/app.py:1558

show_logout

  • Type: bool
  • Description: Whether to show the logout button (based on ds_actor cookie presence)
  • Source: datasette/app.py:1559-1561

app_css_hash

  • Type: str
  • Description: SHA1 hash of the app.css file for cache-busting
  • Source: datasette/app.py:1562

zip

  • Type: builtin_function_or_method
  • Description: Python's built-in zip() function for use in templates
  • Source: datasette/app.py:1563

body_scripts

  • Type: list[dict]
  • Description: List of script objects to inject at the end of the body, from plugins via the extra_body_script hook. Each dict contains script (Markup) and module (bool)
  • Source: datasette/app.py:1564

format_bytes

  • Type: function
  • Description: Utility function to format byte sizes into human-readable format (e.g., "1.5 KB")
  • Source: datasette/app.py:1565

show_messages

  • Type: callable
  • Description: Function that returns and clears flash messages for display
  • Source: datasette/app.py:1566

extra_css_urls

  • Type: list[dict]
  • Description: Additional CSS URLs from plugins and configuration. Each dict contains url, optional sri (Subresource Integrity), and optional module (bool)
  • Source: datasette/app.py:1567-1569

extra_js_urls

  • Type: list[dict]
  • Description: Additional JavaScript URLs from plugins and configuration. Each dict contains url, optional sri, and optional module (bool)
  • Source: datasette/app.py:1570-1572

base_url

  • Type: str
  • Description: The configured base URL path for the Datasette instance (default: "/")
  • Source: datasette/app.py:1573

csrftoken

  • Type: callable
  • Description: Function that returns the CSRF token for forms, or empty string if no request
  • Source: datasette/app.py:1574

datasette_version

  • Type: str
  • Description: The version string of Datasette
  • Source: datasette/app.py:1575

select_templates

  • Type: list[str]
  • Description: List of template names that were considered for rendering, with * marking the selected one (useful for debugging)
  • Source: datasette/views/base.py:147-150

alternate_url_json

  • Type: str (when available)
  • Description: Absolute URL to the JSON version of the current page
  • Source: datasette/views/base.py:155-159

Template-Specific Variables

index.html

The homepage template rendered by IndexView in datasette/views/index.py.

databases

  • Type: list[dict]
  • Description: List of database objects containing information about each accessible database
  • Source: datasette/views/index.py:160
  • Structure: Each database dict contains:
    • name (str): Database name
    • hash (str): Database hash value
    • color (str): Color code for the database
    • path (str): URL path to the database page
    • tables_and_views_truncated (list): Up to 5 tables/views to display
    • tables_and_views_more (bool): Whether there are more tables/views than shown
    • tables_count (int): Number of visible tables
    • table_rows_sum (int): Total rows across all visible tables
    • show_table_row_counts (bool): Whether to display row counts
    • hidden_table_rows_sum (int): Total rows in hidden tables
    • hidden_tables_count (int): Number of hidden tables
    • views_count (int): Number of views
    • private (bool): Whether database is private (requires authentication)

metadata

  • Type: dict
  • Description: Instance-level metadata from the internal database, typically includes title, description, license, etc.
  • Source: datasette/views/index.py:161

private

  • Type: bool
  • Description: Whether the instance itself is private (requires authentication to view)
  • Source: datasette/views/index.py:163-165

top_homepage

  • Type: callable
  • Description: Async function that renders HTML from the top_homepage plugin hook, displayed at the top of the homepage
  • Source: datasette/views/index.py:166-168

homepage_actions

  • Type: list[dict]
  • Description: List of action links/buttons to display on the homepage, typically from plugins
  • Source: datasette/views/index.py:169

noindex

  • Type: bool
  • Description: Whether to add a <meta name="robots" content="noindex"> tag to prevent search engine indexing
  • Source: datasette/views/index.py:170

database.html

The database page template rendered by DatabaseView in datasette/views/database.py. Context is defined using the DatabaseContext dataclass (lines 204-250).

database

  • Type: str
  • Description: The name of the database
  • Source: datasette/views/database.py:160

private

  • Type: bool
  • Description: Whether this is a private database requiring authentication
  • Source: datasette/views/database.py:161

path

  • Type: str
  • Description: The URL path to this database
  • Source: datasette/views/database.py:162

size

  • Type: int
  • Description: The size of the database in bytes
  • Source: datasette/views/database.py:163

tables

  • Type: list[dict]
  • Description: List of table objects in the database
  • Source: datasette/views/database.py:164
  • Structure: Each table dict contains:
    • name (str): Table name
    • columns (list): List of column names
    • primary_keys (list): List of primary key column names
    • count (int): Row count
    • hidden (bool): Whether table is hidden
    • fts_table (str): Associated FTS table name if any
    • foreign_keys (dict): Foreign key relationships
    • private (bool): Whether table requires authentication

hidden_count

  • Type: int
  • Description: Count of hidden tables
  • Source: datasette/views/database.py:165

views

  • Type: list[dict]
  • Description: List of view objects in the database
  • Source: datasette/views/database.py:166
  • Structure: Each view dict contains:
    • name (str): View name
    • private (bool): Whether view requires authentication

queries

  • Type: list[dict]
  • Description: List of canned query objects
  • Source: datasette/views/database.py:167
  • Structure: Each query inherits from canned query definition with added private (bool) field

allow_execute_sql

  • Type: bool
  • Description: Whether custom SQL can be executed on this database
  • Source: datasette/views/database.py:168

table_columns

  • Type: dict[str, list]
  • Description: Dictionary mapping table names to their column lists (for autocomplete in SQL editor)
  • Source: datasette/views/database.py:169-173

metadata

  • Type: dict
  • Description: Metadata for the database
  • Source: datasette/views/database.py:174

database_color

  • Type: str
  • Description: The color assigned to the database (used for styling)
  • Source: datasette/views/database.py:175

database_actions

  • Type: callable
  • Description: Async callable returning list of action links for the database menu (from database_actions plugin hook)
  • Source: datasette/views/database.py:176

show_hidden

  • Type: str | None
  • Description: Value of _show_hidden query parameter
  • Source: datasette/views/database.py:177

editable

  • Type: bool
  • Description: Whether the database is editable
  • Source: datasette/views/database.py:178

count_limit

  • Type: int
  • Description: The maximum number of rows to count
  • Source: datasette/views/database.py:179

allow_download

  • Type: bool
  • Description: Whether database download is allowed (based on settings and database type)
  • Source: datasette/views/database.py:180-182

attached_databases

  • Type: list[str]
  • Description: List of names of attached databases
  • Source: datasette/views/database.py:183

top_database

  • Type: callable
  • Description: Callable to render the top_database plugin slot
  • Source: datasette/views/database.py:189-191

table.html

The table page template rendered by TableView in datasette/views/table.py.

database

  • Type: str
  • Description: Name of the database being viewed
  • Source: datasette/views/table.py:1511-1512

table

  • Type: str
  • Description: Name of the table or view being viewed
  • Source: datasette/views/table.py:1513-1514

is_view

  • Type: bool
  • Description: Whether this is a view rather than a table
  • Source: datasette/views/table.py:1439-1440

private

  • Type: bool
  • Description: Whether this table/view requires authentication to access
  • Source: datasette/views/table.py:1581-1582

database_color

  • Type: str
  • Description: Hex color code assigned to the database for visual identification
  • Source: datasette/views/table.py:1516-1517

rows

  • Type: list[dict]
  • Description: List of dictionaries representing the raw SQLite rows for the current page
  • Source: datasette/views/table.py:1706

display_rows

  • Type: list[Row]
  • Description: List of Row objects containing formatted cell data for display, including foreign key links and special formatting
  • Source: datasette/views/table.py:1481-1482

columns

  • Type: list[str]
  • Description: List of column names returned by the query
  • Source: datasette/views/table.py:1408-1410

display_columns

  • Type: list[dict]
  • Description: List of column dictionaries with detailed info including name, sortable, is_pk, type, notnull, and description fields
  • Source: datasette/views/table.py:1478-1479

primary_keys

  • Type: list[str]
  • Description: List of primary key column names for the table
  • Source: datasette/views/table.py:1412-1414

count

  • Type: int | None
  • Description: Total count of rows matching the current filters (may be None if count timed out or was disabled with _nocount)
  • Source: datasette/views/table.py:1287-1314

count_sql

  • Type: str
  • Description: The SQL query used to count total rows
  • Source: datasette/views/table.py:1284-1285

query

  • Type: dict
  • Description: Dictionary with sql and params keys containing the SQL query and parameters used to fetch data
  • Source: datasette/views/table.py:1484-1489

metadata

  • Type: dict
  • Description: Metadata about the table including title, description, and column descriptions. Contains a columns sub-dict mapping column names to descriptions
  • Source: datasette/views/table.py:1491-1508

human_description_en

  • Type: str
  • Description: Human-readable English description of the applied filters and sort order
  • Source: datasette/views/table.py:1388-1397

next

  • Type: str | None
  • Description: Pagination token for the next page of results
  • Source: datasette/views/table.py:1696

next_url

  • Type: str | None
  • Description: Full absolute URL for the next page of results, or None if this is the last page
  • Source: datasette/views/table.py:1404-1406

filters

  • Type: Filters
  • Description: Filters object containing information about applied column filters
  • Source: datasette/views/table.py:1531-1532

filter_columns

  • Type: list[str]
  • Description: Combined list of columns available for filtering (includes query columns plus any additional table columns like rowid)
  • Source: datasette/views/table.py:1713-1717

sort

  • Type: str | None
  • Description: Name of the column being sorted in ascending order, or None
  • Source: datasette/views/table.py:1745

sort_desc

  • Type: str | None
  • Description: Name of the column being sorted in descending order, or None
  • Source: datasette/views/table.py:1746

facet_results

  • Type: dict
  • Description: Dictionary mapping facet names to facet result objects containing aggregated data for faceting UI
  • Source: datasette/views/table.py:1336-1362

facets_timed_out

  • Type: list[str]
  • Description: List of facet names that timed out during calculation
  • Source: datasette/views/table.py:1616-1617

suggested_facets

  • Type: list
  • Description: List of suggested facets that might provide interesting filtering options
  • Source: datasette/views/table.py:1364-1379

sorted_facet_results

  • Type: list[dict]
  • Description: Facet results sorted by number of results and name
  • Source: datasette/views/table.py:1541-1546

actions

  • Type: callable
  • Description: Callable function that returns list of action menu links from table_actions or view_actions plugin hooks
  • Source: datasette/views/table.py:1416-1437

renderers

  • Type: dict[str, str]
  • Description: Dictionary mapping renderer format names (e.g., 'json') to their URLs for the current page
  • Source: datasette/views/table.py:1554-1579

url_csv

  • Type: str
  • Description: URL for CSV export with maximum size and labels enabled
  • Source: datasette/views/table.py:1722-1724

url_csv_path

  • Type: str
  • Description: Path component of the CSV URL (without query string)
  • Source: datasette/views/table.py:1725-1726

url_csv_hidden_args

  • Type: list[tuple[str, str]]
  • Description: List of (key, value) tuples for hidden form inputs to preserve query parameters in CSV export
  • Source: datasette/views/table.py:1727-1736

table_definition

  • Type: str | None
  • Description: SQL CREATE TABLE statement for the table (None for views)
  • Source: datasette/views/table.py:1548-1549

view_definition

  • Type: str | None
  • Description: SQL CREATE VIEW statement for the view (None for tables)
  • Source: datasette/views/table.py:1551-1552

expandable_columns

  • Type: list[tuple]
  • Description: List of (foreign_key_dict, label_column) tuples for columns with foreign key relationships
  • Source: datasette/views/table.py:1584-1590

form_hidden_args

  • Type: list[tuple[str, str]]
  • Description: List of (key, value) tuples for hidden form inputs to preserve special query parameters (like _facet, _extra, etc.)
  • Source: datasette/views/table.py:1519-1529

custom_table_templates

  • Type: list[str]
  • Description: List of template names for custom table partials that can be included
  • Source: datasette/views/table.py:1534-1539

append_querystring

  • Type: function
  • Description: Utility function to append query string parameters to a URL
  • Source: datasette/views/table.py:907

path_with_replaced_args

  • Type: function
  • Description: Utility function to replace query string arguments in a URL path
  • Source: datasette/views/table.py:908

settings

  • Type: dict
  • Description: Dictionary of all Datasette settings
  • Source: datasette/views/table.py:910

datasette_allow_facet

  • Type: str
  • Description: String "true" or "false" indicating if faceting is allowed (used in JavaScript)
  • Source: datasette/views/table.py:913-915

is_sortable

  • Type: bool
  • Description: Whether any columns are sortable
  • Source: datasette/views/table.py:916

allow_execute_sql

  • Type: bool
  • Description: Whether the current user has permission to execute custom SQL
  • Source: datasette/views/table.py:917-919

query_ms

  • Type: float
  • Description: Query execution time in milliseconds
  • Source: datasette/views/table.py:920

top_table

  • Type: callable
  • Description: Slot function for rendering content at the top of the table via the top_table plugin hook
  • Source: datasette/views/table.py:925-931

count_limit

  • Type: int
  • Description: Maximum number of rows to count before returning count_limit + 1
  • Source: datasette/views/table.py:932

extra_wheres_for_ui

  • Type: list[dict] | None
  • Description: Additional where clauses added by plugins, each with text and remove_url keys
  • Source: datasette/views/table.py:1029-1044

supports_search

  • Type: bool | None
  • Description: Whether full-text search is supported for this table
  • Source: datasette/views/table.py:1029-1044

search

  • Type: str | None
  • Description: Current search query string if search is active
  • Source: datasette/views/table.py:1029-1044

query.html

The custom SQL query page template rendered by DatabaseView in datasette/views/database.py. Context is defined using the QueryContext dataclass (lines 795-846).

database

  • Type: str
  • Description: The name of the database being queried
  • Source: datasette/views/database.py:795

database_color

  • Type: str
  • Description: The color assigned to the database for visual styling
  • Source: datasette/views/database.py:796

query

  • Type: dict
  • Description: The SQL query object containing the sql string and params dictionary
  • Source: datasette/views/database.py:797-800

canned_query

  • Type: str | None
  • Description: The name of the canned query if this is a canned query, otherwise None
  • Source: datasette/views/database.py:801

private

  • Type: bool
  • Description: Whether this is a private database requiring authentication
  • Source: datasette/views/database.py:802

canned_query_write

  • Type: bool
  • Description: Whether this is a canned query that allows write operations
  • Source: datasette/views/database.py:803

metadata

  • Type: dict
  • Description: Metadata about the database or the canned query (canned query metadata takes precedence)
  • Source: datasette/views/database.py:830

db_is_immutable

  • Type: bool
  • Description: Whether this database is immutable (read-only)
  • Source: datasette/views/database.py:804

error

  • Type: str | None
  • Description: Any query error message to display
  • Source: datasette/views/database.py:805

hide_sql

  • Type: bool
  • Description: Whether the SQL should be hidden from view
  • Source: datasette/views/database.py:806

show_hide_link

  • Type: str
  • Description: The URL to toggle showing/hiding the SQL
  • Source: datasette/views/database.py:807

show_hide_text

  • Type: str
  • Description: The text for the show/hide SQL link ("show" or "hide")
  • Source: datasette/views/database.py:808

editable

  • Type: bool
  • Description: Whether the SQL can be edited (not editable for canned queries)
  • Source: datasette/views/database.py:809

allow_execute_sql

  • Type: bool
  • Description: Whether custom SQL can be executed
  • Source: datasette/views/database.py:810

tables

  • Type: list[dict]
  • Description: List of table objects in the database
  • Source: datasette/views/database.py:811

named_parameter_values

  • Type: dict
  • Description: Dictionary mapping parameter names to their values for SQL parameters
  • Source: datasette/views/database.py:812

edit_sql_url

  • Type: str | None
  • Description: URL to edit the SQL for a canned query (only if allowed)
  • Source: datasette/views/database.py:813

display_rows

  • Type: list
  • Description: List of result rows to display, processed for rendering (URLs linkified, binary data displayed as download links, etc.)
  • Source: datasette/views/database.py:814-816

columns

  • Type: list[str]
  • Description: List of column names from the query results
  • Source: datasette/views/database.py:822

renderers

  • Type: dict
  • Description: Dictionary mapping renderer name to URL for alternate formats
  • Source: datasette/views/database.py:823

url_csv

  • Type: str
  • Description: URL for CSV export of the query results
  • Source: datasette/views/database.py:824-827

show_hide_hidden

  • Type: markupsafe.Markup
  • Description: Hidden input field for the _show_sql or _hide_sql parameter
  • Source: datasette/views/database.py:829

table_columns

  • Type: dict[str, list]
  • Description: Dictionary mapping table names to their column lists (for autocomplete)
  • Source: datasette/views/database.py:817-821

top_query

  • Type: callable
  • Description: Callable to render the top_query plugin slot
  • Source: datasette/views/database.py:836-838

top_canned_query

  • Type: callable
  • Description: Callable to render the top_canned_query plugin slot
  • Source: datasette/views/database.py:839-845

query_actions

  • Type: callable
  • Description: Callable returning a list of action links for the query action menu
  • Source: datasette/views/database.py:846

truncated

  • Type: bool
  • Description: Whether the results were truncated
  • Source: Passed through from query results if present

row.html

The individual row page template rendered by RowView in datasette/views/row.py.

database

  • Type: str
  • Description: The name of the database containing the row
  • Source: datasette/views/row.py:100

table

  • Type: str
  • Description: The name of the table containing the row
  • Source: datasette/views/row.py:101

rows

  • Type: list[dict]
  • Description: List containing the row data (typically a single row)
  • Source: datasette/views/row.py:102

columns

  • Type: list[str]
  • Description: List of column names from the table
  • Source: datasette/views/row.py:103

primary_keys

  • Type: list[str]
  • Description: List of primary key column names
  • Source: datasette/views/row.py:104

primary_key_values

  • Type: list
  • Description: List of primary key values for this specific row
  • Source: datasette/views/row.py:105

private

  • Type: bool
  • Description: Whether this table is private (requires authentication)
  • Source: datasette/views/row.py:75

foreign_key_tables

  • Type: list[dict]
  • Description: List of objects describing incoming foreign key relationships
  • Source: datasette/views/row.py:76-78
  • Structure: Each dict contains:
    • other_table (str): The table with the foreign key
    • other_column (str): The column with the foreign key
    • count (int): Number of related rows
    • link (str): URL to view the related rows

database_color

  • Type: str
  • Description: The color assigned to the database for visual styling
  • Source: datasette/views/row.py:79

display_columns

  • Type: list[dict]
  • Description: List of column definition objects with name, sortable, and other properties
  • Source: datasette/views/row.py:80

display_rows

  • Type: list
  • Description: List of rows with processed values for display (URLs linkified, binary data as download links, etc.)
  • Source: datasette/views/row.py:81

custom_table_templates

  • Type: list[str]
  • Description: List of custom table template names that can be used for rendering the data table
  • Source: datasette/views/row.py:82-86

row_actions

  • Type: list
  • Description: List of action links for the row menu from plugins
  • Source: datasette/views/row.py:87

top_row

  • Type: callable
  • Description: Callable to render the top_row plugin slot
  • Source: datasette/views/row.py:88-95

metadata

  • Type: dict
  • Description: Metadata for the table
  • Source: datasette/views/row.py:96

renderers

  • Type: dict
  • Description: Dictionary mapping renderer name to URL for alternate formats
  • Source: Added by DataView.get() at datasette/views/base.py:355-375

error.html

The error page template rendered by handle_exception in datasette/handle_exception.py. Status-specific templates (404.html, 403.html, 500.html, etc.) can also be used.

ok

  • Type: bool
  • Description: Always False for error responses
  • Source: datasette/handle_exception.py:50

error

  • Type: str | Markup
  • Description: The error message to display
  • Source: datasette/handle_exception.py:51

status

  • Type: int
  • Description: HTTP status code (400, 403, 404, 500, etc.)
  • Source: datasette/handle_exception.py:52

title

  • Type: str | None
  • Description: Optional custom title for the error page
  • Source: datasette/handle_exception.py:53

Special Templates

csrf_error.html

Rendered when CSRF validation fails in datasette/app.py:1847-1856.

message_id

  • Type: int
  • Description: The CSRF error code/ID
  • Source: datasette/app.py:1852

message_name

  • Type: str
  • Description: The name of the CSRF error type from the Errors enum
  • Source: datasette/app.py:1852

logout.html

Rendered by LogoutView in datasette/views/special.py:98-102.

actor

  • Type: dict
  • Description: The current logged-in actor object
  • Source: datasette/views/special.py:101

create_token.html

Rendered by CreateTokenView in datasette/views/special.py:707-776.

actor

  • Type: dict
  • Description: The current actor creating the token
  • Source: datasette/views/special.py:690

all_permissions

  • Type: iterable[str]
  • Description: All available permission names
  • Source: datasette/views/special.py:691

database_permissions

  • Type: list[str]
  • Description: Permission names that take a database parameter
  • Source: datasette/views/special.py:692-696

resource_permissions

  • Type: list[str]
  • Description: Permission names that take a resource (database, table) parameter
  • Source: datasette/views/special.py:697-701

database_with_tables

  • Type: list[dict]
  • Description: List of databases with their tables
  • Source: datasette/views/special.py:662-688, 702
  • Structure: Each dict contains:
    • name (str): Database name
    • encoded (str): URL-encoded database name
    • tables (list): List of table dicts with name and encoded

errors

  • Type: list (optional)
  • Description: List of validation error messages (when POST fails)
  • Source: datasette/views/special.py:775

token

  • Type: str (optional)
  • Description: The generated API token (when POST succeeds)
  • Source: datasette/views/special.py:775

token_bits

  • Type: dict (optional)
  • Description: Decoded token information for display
  • Source: datasette/views/special.py:775

debug_allowed.html

Rendered by AllowedResourcesView in datasette/views/special.py:219-225.

supported_actions

  • Type: list[str]
  • Description: Sorted list of permission action names supported by this endpoint
  • Source: datasette/views/special.py:223

debug_check.html

Rendered by PermissionCheckView in datasette/views/special.py:515-521.

sorted_permissions

  • Type: list[str]
  • Description: Sorted list of all permission names
  • Source: datasette/views/special.py:519

debug_rules.html

Rendered by PermissionRulesView in datasette/views/special.py:394-400.

sorted_permissions

  • Type: list[str]
  • Description: Sorted list of all permission names
  • Source: datasette/views/special.py:398

allow_debug.html

Rendered by AllowDebugView in datasette/views/special.py:605-614.

result

  • Type: str | None
  • Description: String representation of actor_matches_allow() result ("True" or "False"), or None if there were errors
  • Source: datasette/views/special.py:609

error

  • Type: str
  • Description: Error messages joined with newlines, or empty string
  • Source: datasette/views/special.py:610

actor_input

  • Type: str
  • Description: JSON-formatted actor input (formatted with indent=4)
  • Source: datasette/views/special.py:611, 588-591

allow_input

  • Type: str
  • Description: JSON-formatted allow block input (formatted with indent=4)
  • Source: datasette/views/special.py:612, 594-599

permissions_debug.html

Rendered by PermissionsDebugView in datasette/views/special.py:134-153.

permission_checks

  • Type: list[dict]
  • Description: Recent permission check records from datasette._permission_checks
  • Source: datasette/views/special.py:139
  • Structure: Each dict contains:
    • when (timestamp): When the check occurred
    • actor (dict): The actor being checked
    • action (str): The permission action
    • resource (str): The resource being accessed
    • used_default (bool): Whether the default was used
    • result (bool): Whether permission was granted

filter

  • Type: str
  • Description: Current filter setting ("all", "exclude-yours", or "only-yours")
  • Source: datasette/views/special.py:140

permissions

  • Type: list[dict]
  • Description: All registered permissions with metadata
  • Source: datasette/views/special.py:141-151
  • Structure: Each dict contains:
    • name (str): Permission name
    • abbr (str): Abbreviation
    • description (str): Description
    • takes_database (bool): Whether it takes a database parameter
    • takes_resource (bool): Whether it takes a resource parameter
    • default (bool): Default permission value

api_explorer.html

Rendered by ApiExplorerView in datasette/views/special.py:917-925.

example_links

  • Type: list[dict]
  • Description: Structured list of API endpoints
  • Source: datasette/views/special.py:921, 783-896
  • Structure: Each database dict contains:
    • name (str): Database name
    • links (list): List of link dicts with path, label, method, and optional json
    • tables (list): List of table dicts with similar structure

api_path

  • Type: callable
  • Description: Function that builds URL fragments for API links with query parameters
  • Source: datasette/views/special.py:922, 906-915

private

  • Type: bool
  • Description: Whether the instance is private (requires authentication)
  • Source: datasette/views/special.py:923

Plugin-Provided Variables

All templates can receive additional variables from plugins via the extra_template_vars hook, which is called in datasette/app.py:1523-1536 and merged into the template context at line 1577.

Custom Jinja2 Filters

In addition to the standard Jinja2 filters, Datasette provides custom filters registered in datasette/app.py:452-456:

  • escape_css_string - Escapes strings for use in CSS
  • quote_plus - URL encoding (urllib.parse.quote_plus)
  • escape_sqlite - Escapes SQLite identifiers
  • to_css_class - Converts strings to valid CSS class names

Notes

  1. Dataclass Contexts: Some views (database.html, query.html) use dataclasses (DatabaseContext, QueryContext) to define their template context with type hints and field metadata.

  2. Plugin Extensibility: Many context variables can be extended or modified by plugins through various hook points (e.g., extra_template_vars, menu_links, table_actions).

  3. Conditional Variables: Some variables only appear when certain conditions are met (e.g., supports_search only appears when FTS is configured).

  4. Format-Specific: The contexts documented here are primarily for HTML format. JSON, CSV, and other formats receive different subsets of data.

  5. Template Inheritance: Most templates extend base.html and inherit all global variables. Custom templates can override specific blocks while maintaining access to the full context.

  6. AsyncInject System: Table views use the asyncinject Registry system with "extra_*" functions that are conditionally resolved based on the requested format and features.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment