From 3a4c8ed36aa97211e46849d32a09f2f386f342dd Mon Sep 17 00:00:00 2001
From: Simon Willison <swillison@gmail.com>
Date: Sun, 16 Aug 2020 11:09:53 -0700
Subject: [PATCH] Added columns argument to various extra_ plugin hooks, closes
 #938

---
 datasette/app.py           |   5 +-
 datasette/hookspecs.py     |  12 +-
 docs/plugin_hooks.rst      | 254 +++++++++++++++++--------------------
 tests/plugins/my_plugin.py |  13 +-
 tests/test_plugins.py      |  25 +++-
 5 files changed, 159 insertions(+), 150 deletions(-)

diff --git a/datasette/app.py b/datasette/app.py
index 180ba246..2185a3ab 100644
--- a/datasette/app.py
+++ b/datasette/app.py
@@ -713,6 +713,7 @@ class Datasette:
             template=template.name,
             database=context.get("database"),
             table=context.get("table"),
+            columns=context.get("columns"),
             view_name=view_name,
             request=request,
             datasette=self,
@@ -729,6 +730,7 @@ class Datasette:
             template=template.name,
             database=context.get("database"),
             table=context.get("table"),
+            columns=context.get("columns"),
             view_name=view_name,
             request=request,
             datasette=self,
@@ -779,9 +781,10 @@ class Datasette:
             template=template.name,
             database=context.get("database"),
             table=context.get("table"),
-            datasette=self,
+            columns=context.get("columns"),
             view_name=view_name,
             request=request,
+            datasette=self,
         ):
             if callable(hook):
                 hook = hook()
diff --git a/datasette/hookspecs.py b/datasette/hookspecs.py
index 0e9c20cf..f7e90e4e 100644
--- a/datasette/hookspecs.py
+++ b/datasette/hookspecs.py
@@ -26,22 +26,26 @@ def prepare_jinja2_environment(env):
 
 
 @hookspec
-def extra_css_urls(template, database, table, view_name, request, datasette):
+def extra_css_urls(template, database, table, columns, view_name, request, datasette):
     "Extra CSS URLs added by this plugin"
 
 
 @hookspec
-def extra_js_urls(template, database, table, view_name, request, datasette):
+def extra_js_urls(template, database, table, columns, view_name, request, datasette):
     "Extra JavaScript URLs added by this plugin"
 
 
 @hookspec
-def extra_body_script(template, database, table, view_name, request, datasette):
+def extra_body_script(
+    template, database, table, columns, view_name, request, datasette
+):
     "Extra JavaScript code to be included in <script> at bottom of body"
 
 
 @hookspec
-def extra_template_vars(template, database, table, view_name, request, datasette):
+def extra_template_vars(
+    template, database, table, columns, view_name, request, datasette
+):
     "Extra template variables to be made available to the template - can return dict or callable or awaitable"
 
 
diff --git a/docs/plugin_hooks.rst b/docs/plugin_hooks.rst
index 426134fa..96a1cd7f 100644
--- a/docs/plugin_hooks.rst
+++ b/docs/plugin_hooks.rst
@@ -80,150 +80,11 @@ You can now use this filter in your custom templates like so::
 
     Table name: {{ table|uppercase }}
 
-.. _plugin_hook_extra_css_urls:
-
-extra_css_urls(template, database, table, view_name, request, datasette)
-------------------------------------------------------------------------
-
-``template`` - string
-    The template that is being rendered, e.g. ``database.html``
-
-``database`` - string or None
-    The name of the database, or ``None`` if the page does not correspond to a database (e.g. the root page)
-
-``table`` - string or None
-    The name of the table, or ``None`` if the page does not correct to a table
-
-``view_name`` - string
-    The name of the view being displayed. (``index``, ``database``, ``table``, and ``row`` are the most important ones.)
-
-``request`` - object or None
-    The current HTTP :ref:`internals_request`. This can be ``None`` if the request object is not available.
-
-``datasette`` - :ref:`internals_datasette`
-    You can use this to access plugin configuration options via ``datasette.plugin_config(your_plugin_name)``
-
-Return a list of extra CSS URLs that should be included on the page. These can
-take advantage of the CSS class hooks described in :ref:`customization`.
-
-This can be a list of URLs:
-
-.. code-block:: python
-
-    from datasette import hookimpl
-
-    @hookimpl
-    def extra_css_urls():
-        return [
-            'https://stackpath.bootstrapcdn.com/bootstrap/4.1.0/css/bootstrap.min.css'
-        ]
-
-Or a list of dictionaries defining both a URL and an
-`SRI hash <https://www.srihash.org/>`_:
-
-.. code-block:: python
-
-    from datasette import hookimpl
-
-    @hookimpl
-    def extra_css_urls():
-        return [{
-            'url': 'https://stackpath.bootstrapcdn.com/bootstrap/4.1.0/css/bootstrap.min.css',
-            'sri': 'sha384-9gVQ4dYFwwWSjIDZnLEWnxCjeSWFphJiwGPXr1jddIhOegiu1FwO5qRGvFXOdJZ4',
-        }]
-
-This function can also return an awaitable function, useful if it needs to run any async code:
-
-.. code-block:: python
-
-    from datasette import hookimpl
-
-    @hookimpl
-    def extra_css_urls(datasette):
-        async def inner():
-            db = datasette.get_database()
-            results = await db.execute("select url from css_files")
-            return [r[0] for r in results]
-
-        return inner
-
-Examples: `datasette-cluster-map <https://github.com/simonw/datasette-cluster-map>`_, `datasette-vega <https://github.com/simonw/datasette-vega>`_
-
-.. _plugin_hook_extra_js_urls:
-
-extra_js_urls(template, database, table, view_name, request, datasette)
------------------------------------------------------------------------
-
-Same arguments as ``extra_css_urls``.
-
-This works in the same way as ``extra_css_urls()`` but for JavaScript. You can
-return a list of URLs, a list of dictionaries or an awaitable function that returns those things:
-
-.. code-block:: python
-
-    from datasette import hookimpl
-
-    @hookimpl
-    def extra_js_urls():
-        return [{
-            'url': 'https://code.jquery.com/jquery-3.3.1.slim.min.js',
-            'sri': 'sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo',
-        }]
-
-You can also return URLs to files from your plugin's ``static/`` directory, if
-you have one:
-
-.. code-block:: python
-
-    from datasette import hookimpl
-
-    @hookimpl
-    def extra_js_urls():
-        return [
-            '/-/static-plugins/your-plugin/app.js'
-        ]
-
-Examples: `datasette-cluster-map <https://github.com/simonw/datasette-cluster-map>`_, `datasette-vega <https://github.com/simonw/datasette-vega>`_
-
-.. _plugin_hook_extra_body_script:
-
-extra_body_script(template, database, table, view_name, request, datasette)
----------------------------------------------------------------------------
-
-Extra JavaScript to be added to a ``<script>`` block at the end of the ``<body>`` element on the page.
-
-``template`` - string
-    The template that is being rendered, e.g. ``database.html``
-
-``database`` - string or None
-    The name of the database, or ``None`` if the page does not correspond to a database (e.g. the root page)
-
-``table`` - string or None
-    The name of the table, or ``None`` if the page does not correct to a table
-
-``view_name`` - string
-    The name of the view being displayed. (``index``, ``database``, ``table``, and ``row`` are the most important ones.)
-
-``request`` - object or None
-    The current HTTP :ref:`internals_request`. This can be ``None`` if the request object is not available.
-
-``datasette`` - :ref:`internals_datasette`
-    You can use this to access plugin configuration options via ``datasette.plugin_config(your_plugin_name)``
-
-The ``template``, ``database``, ``table`` and ``view_name`` options can be used to return different code depending on which template is being rendered and which database or table are being processed.
-
-The ``datasette`` instance is provided primarily so that you can consult any plugin configuration options that may have been set, using the ``datasette.plugin_config(plugin_name)`` method documented above.
-
-The string that you return from this function will be treated as "safe" for inclusion in a ``<script>`` block directly in the page, so it is up to you to apply any necessary escaping.
-
-You can also return an awaitable function that returns a string.
-
-Example: `datasette-cluster-map <https://github.com/simonw/datasette-cluster-map>`_
 
 .. _plugin_hook_extra_template_vars:
 
-extra_template_vars(template, database, table, view_name, request, datasette)
------------------------------------------------------------------------------
+extra_template_vars(template, database, table, columns, view_name, request, datasette)
+--------------------------------------------------------------------------------------
 
 Extra template variables that should be made available in the rendered template context.
 
@@ -236,6 +97,9 @@ Extra template variables that should be made available in the rendered template
 ``table`` - string or None
     The name of the table, or ``None`` if the page does not correct to a table
 
+``columns`` - list of strings or None
+    The names of the database columns that will be displayed on this page. ``None`` if the page does not contain a table.
+
 ``view_name`` - string
     The name of the view being displayed. (``index``, ``database``, ``table``, and ``row`` are the most important ones.)
 
@@ -299,6 +163,114 @@ You can then use the new function in a template like so::
 
 Examples: `datasette-search-all <https://github.com/simonw/datasette-search-all>`_, `datasette-template-sql <https://github.com/simonw/datasette-template-sql>`_
 
+.. _plugin_hook_extra_css_urls:
+
+extra_css_urls(template, database, table, columns, view_name, request, datasette)
+---------------------------------------------------------------------------------
+
+Same arguments as :ref:`extra_template_vars(...) <plugin_hook_extra_template_vars>`
+
+Return a list of extra CSS URLs that should be included on the page. These can
+take advantage of the CSS class hooks described in :ref:`customization`.
+
+This can be a list of URLs:
+
+.. code-block:: python
+
+    from datasette import hookimpl
+
+    @hookimpl
+    def extra_css_urls():
+        return [
+            'https://stackpath.bootstrapcdn.com/bootstrap/4.1.0/css/bootstrap.min.css'
+        ]
+
+Or a list of dictionaries defining both a URL and an
+`SRI hash <https://www.srihash.org/>`_:
+
+.. code-block:: python
+
+    from datasette import hookimpl
+
+    @hookimpl
+    def extra_css_urls():
+        return [{
+            'url': 'https://stackpath.bootstrapcdn.com/bootstrap/4.1.0/css/bootstrap.min.css',
+            'sri': 'sha384-9gVQ4dYFwwWSjIDZnLEWnxCjeSWFphJiwGPXr1jddIhOegiu1FwO5qRGvFXOdJZ4',
+        }]
+
+This function can also return an awaitable function, useful if it needs to run any async code:
+
+.. code-block:: python
+
+    from datasette import hookimpl
+
+    @hookimpl
+    def extra_css_urls(datasette):
+        async def inner():
+            db = datasette.get_database()
+            results = await db.execute("select url from css_files")
+            return [r[0] for r in results]
+
+        return inner
+
+Examples: `datasette-cluster-map <https://github.com/simonw/datasette-cluster-map>`_, `datasette-vega <https://github.com/simonw/datasette-vega>`_
+
+.. _plugin_hook_extra_js_urls:
+
+extra_js_urls(template, database, table, columns, view_name, request, datasette)
+--------------------------------------------------------------------------------
+
+Same arguments as :ref:`extra_template_vars(...) <plugin_hook_extra_template_vars>`
+
+This works in the same way as ``extra_css_urls()`` but for JavaScript. You can
+return a list of URLs, a list of dictionaries or an awaitable function that returns those things:
+
+.. code-block:: python
+
+    from datasette import hookimpl
+
+    @hookimpl
+    def extra_js_urls():
+        return [{
+            'url': 'https://code.jquery.com/jquery-3.3.1.slim.min.js',
+            'sri': 'sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo',
+        }]
+
+You can also return URLs to files from your plugin's ``static/`` directory, if
+you have one:
+
+.. code-block:: python
+
+    from datasette import hookimpl
+
+    @hookimpl
+    def extra_js_urls():
+        return [
+            '/-/static-plugins/your-plugin/app.js'
+        ]
+
+Examples: `datasette-cluster-map <https://github.com/simonw/datasette-cluster-map>`_, `datasette-vega <https://github.com/simonw/datasette-vega>`_
+
+.. _plugin_hook_extra_body_script:
+
+extra_body_script(template, database, table, columns, view_name, request, datasette)
+------------------------------------------------------------------------------------
+
+Extra JavaScript to be added to a ``<script>`` block at the end of the ``<body>`` element on the page.
+
+Same arguments as :ref:`extra_template_vars(...) <plugin_hook_extra_template_vars>`
+
+The ``template``, ``database``, ``table`` and ``view_name`` options can be used to return different code depending on which template is being rendered and which database or table are being processed.
+
+The ``datasette`` instance is provided primarily so that you can consult any plugin configuration options that may have been set, using the ``datasette.plugin_config(plugin_name)`` method documented above.
+
+The string that you return from this function will be treated as "safe" for inclusion in a ``<script>`` block directly in the page, so it is up to you to apply any necessary escaping.
+
+You can also return an awaitable function that returns a string.
+
+Example: `datasette-cluster-map <https://github.com/simonw/datasette-cluster-map>`_
+
 .. _plugin_hook_publish_subcommand:
 
 publish_subcommand(publish)
diff --git a/tests/plugins/my_plugin.py b/tests/plugins/my_plugin.py
index 0f6e80f3..1dc348cc 100644
--- a/tests/plugins/my_plugin.py
+++ b/tests/plugins/my_plugin.py
@@ -26,7 +26,7 @@ def prepare_connection(conn, database, datasette):
 
 
 @hookimpl
-def extra_css_urls(template, database, table, view_name, request, datasette):
+def extra_css_urls(template, database, table, view_name, columns, request, datasette):
     async def inner():
         return [
             "https://plugin-example.com/{}/extra-css-urls-demo.css".format(
@@ -43,6 +43,7 @@ def extra_css_urls(template, database, table, view_name, request, datasette):
                             "added": (
                                 await datasette.get_database().execute("select 3 * 5")
                             ).first()[0],
+                            "columns": columns,
                         }
                     ).encode("utf8")
                 ).decode("utf8")
@@ -61,7 +62,9 @@ def extra_js_urls():
 
 
 @hookimpl
-def extra_body_script(template, database, table, view_name, request, datasette):
+def extra_body_script(
+    template, database, table, view_name, columns, request, datasette
+):
     async def inner():
         return "var extra_body_script = {};".format(
             json.dumps(
@@ -77,6 +80,7 @@ def extra_body_script(template, database, table, view_name, request, datasette):
                     "added": (
                         await datasette.get_database().execute("select 3 * 5")
                     ).first()[0],
+                    "columns": columns,
                 }
             )
         )
@@ -102,12 +106,15 @@ def render_cell(value, column, table, database, datasette):
 
 
 @hookimpl
-def extra_template_vars(template, database, table, view_name, request, datasette):
+def extra_template_vars(
+    template, database, table, view_name, columns, request, datasette
+):
     return {
         "extra_template_vars": json.dumps(
             {
                 "template": template,
                 "scope_path": request.scope["path"] if request else None,
+                "columns": columns,
             },
             default=lambda b: b.decode("utf8"),
         )
diff --git a/tests/test_plugins.py b/tests/test_plugins.py
index 2ca79839..c535810c 100644
--- a/tests/test_plugins.py
+++ b/tests/test_plugins.py
@@ -65,6 +65,7 @@ def test_hook_plugin_prepare_connection_arguments(app_client):
                 "view_name": "index",
                 "request_path": "/",
                 "added": 15,
+                "columns": None,
             },
         ),
         (
@@ -76,6 +77,7 @@ def test_hook_plugin_prepare_connection_arguments(app_client):
                 "view_name": "database",
                 "request_path": "/fixtures",
                 "added": 15,
+                "columns": None,
             },
         ),
         (
@@ -87,6 +89,15 @@ def test_hook_plugin_prepare_connection_arguments(app_client):
                 "view_name": "table",
                 "request_path": "/fixtures/sortable",
                 "added": 15,
+                "columns": [
+                    "pk1",
+                    "pk2",
+                    "content",
+                    "sortable",
+                    "sortable_with_nulls",
+                    "sortable_with_nulls_2",
+                    "text",
+                ],
             },
         ),
     ],
@@ -234,6 +245,7 @@ def test_plugin_config_file(app_client):
                 "view_name": "index",
                 "request_path": "/",
                 "added": 15,
+                "columns": None,
             },
         ),
         (
@@ -246,6 +258,7 @@ def test_plugin_config_file(app_client):
                 "view_name": "database",
                 "request_path": "/fixtures",
                 "added": 15,
+                "columns": None,
             },
         ),
         (
@@ -258,11 +271,20 @@ def test_plugin_config_file(app_client):
                 "view_name": "table",
                 "request_path": "/fixtures/sortable",
                 "added": 15,
+                "columns": [
+                    "pk1",
+                    "pk2",
+                    "content",
+                    "sortable",
+                    "sortable_with_nulls",
+                    "sortable_with_nulls_2",
+                    "text",
+                ],
             },
         ),
     ],
 )
-def test_hook__extra_body_script(app_client, path, expected_extra_body_script):
+def test_hook_extra_body_script(app_client, path, expected_extra_body_script):
     r = re.compile(r"<script>var extra_body_script = (.*?);</script>")
     json_data = r.search(app_client.get(path).text).group(1)
     actual_data = json.loads(json_data)
@@ -286,6 +308,7 @@ def test_hook_extra_template_vars(restore_working_directory):
         assert {
             "template": "show_json.html",
             "scope_path": "/-/metadata",
+            "columns": None,
         } == extra_template_vars
         extra_template_vars_from_awaitable = json.loads(
             Soup(response.body, "html.parser")