diff --git a/docs/_static/how-tos/htmx-demo.gif b/docs/_static/how-tos/htmx-demo.gif new file mode 100644 index 000000000..72e1a82dd Binary files /dev/null and b/docs/_static/how-tos/htmx-demo.gif differ diff --git a/docs/_static/how-tos/htmx-edit-delete.gif b/docs/_static/how-tos/htmx-edit-delete.gif new file mode 100644 index 000000000..89ee58e00 Binary files /dev/null and b/docs/_static/how-tos/htmx-edit-delete.gif differ diff --git a/docs/_static/how-tos/htmx-insert.gif b/docs/_static/how-tos/htmx-insert.gif new file mode 100644 index 000000000..9c678983e Binary files /dev/null and b/docs/_static/how-tos/htmx-insert.gif differ diff --git a/docs/_static/how-tos/htmx-simple.jpg b/docs/_static/how-tos/htmx-simple.jpg new file mode 100644 index 000000000..e15d13349 Binary files /dev/null and b/docs/_static/how-tos/htmx-simple.jpg differ diff --git a/docs/how-tos/providing-html-content-using-htmx.rst b/docs/how-tos/providing-html-content-using-htmx.rst index 0909fe5cf..625f3df00 100644 --- a/docs/how-tos/providing-html-content-using-htmx.rst +++ b/docs/how-tos/providing-html-content-using-htmx.rst @@ -1,10 +1,7 @@ -.. note:: - - This page is a work in progress. .. _providing_html_htmx: -Providing HTML Content Using htmx +Providing HTML Content Using Htmx ================================= :author: `Laurence Isla `_ @@ -12,6 +9,8 @@ Providing HTML Content Using htmx This how-to shows a way to return HTML content and use the `htmx library `_ to handle the AJAX requests. Htmx expects an HTML response and uses it to replace an element inside the DOM (see the `htmx introduction `_ in the docs). +.. image:: ../_static/how-tos/htmx-demo.gif + Preparatory Configuration ------------------------- @@ -22,6 +21,7 @@ To simplify things, we won't be using authentication, so grant all permissions o .. code-block:: postgres grant all on api.todos to web_anon; + grant usage, select on sequence api.todos_id_seq to web_anon; Next, add the ``text/html`` media type to the :ref:`raw-media-types` configuration. With this, PostgREST can identify the request made by your web browser (with the ``Accept: text/html`` header) and return a raw HTML document file. @@ -49,14 +49,14 @@ Let's create a function that returns a basic HTML file, using `Tailwind CSS - PostgREST To-Do list + PostgREST + HTMX To-Do List
-
PostgREST To-Do List
+
PostgREST + HTMX To-Do List
@@ -66,6 +66,8 @@ Let's create a function that returns a basic HTML file, using `Tailwind CSS ' || string_agg(api.html_todo(t), '' order by t.id) || '', - '

There is nothing else to do.

' + '

There is nothing else to do.

' ) from api.todos t; $$; -These two functions are used to build the to-do list template. We won't call them outside of PostgreSQL. +These two functions are used to build the to-do list template. We won't use them as PostgREST endpoints. -- The ``html_todo`` function uses the table ``api.todos`` as a parameter and is used to format each element into a list element ``
  • ``. - The PostgreSQL `format `_ function is useful to that end. - It replaces the values according to the position in the template, e.g. the ``%1$s`` in the template will be replaced with the value of ``$1.id`` (the first parameter). +- The ``api.html_todo`` function uses the table ``api.todos`` as a parameter and formats each item into a list element ``
  • ``. + The PostgreSQL `format `_ is useful to that end. + It replaces the values according to the position in the template, e.g. ``%1$s`` will be replaced with the value of ``$1.id`` (the first parameter). -- The ``html_all_todos`` function is the ``
      `` wrapper for all the list elements and uses `string_arg `_ to concatenate all the to-dos in a single text value. +- The ``api.html_all_todos`` function returns the ``
        `` wrapper for all the list elements. + It uses `string_arg `_ to concatenate all the to-dos in a single text value. It also returns an alternative message, instead of a list, when the ``api.todos`` table is empty. Next, let's add an endpoint to register a to-do in the database and modify the ``/rpc/index`` page accordingly. @@ -137,7 +140,7 @@ Next, let's add an endpoint to register a to-do in the database and modify the ` - PostgREST To-Do list + PostgREST + HTMX To-Do List @@ -147,9 +150,8 @@ Next, let's add an endpoint to register a to-do in the database and modify the ` hx-headers='{"Accept": "text/html"}'>
        -
        PostgREST To-Do List
        -
        PostgREST + HTMX To-Do List + @@ -179,20 +181,23 @@ Next, let's add an endpoint to register a to-do in the database and modify the ` + ``hx-target="#todo-list-area"``: the HTML content returned from the request will go inside ``
        `` (which is the list of to-dos). - + ``hx-trigger="submit"``: htmx will do this request when submitting the form (by pressing enter inside the ````). + + ``hx-trigger="submit"``: htmx will do this request when submitting the form (by pressing enter while inside the ````). + ``hx-on="htmx:afterRequest: this.reset()">``: this is a Javascript command that clears the form `after the request is done `_. With this, the ``http://localhost:3000/rpc/index`` page lists all the todos and adds new ones by submitting tasks in the input element. +Don't forget to refresh the :ref:`schema cache `. + +.. image:: ../_static/how-tos/htmx-insert.gif Editing and Deleting To-Dos --------------------------- -Now, let's modify the ``html_todo`` function and make it more functional. +Now, let's modify ``api.html_todo`` and make it more functional. .. code-block:: postgres - create or replace function api.html_todo_template(api.todos) returns text + create or replace function api.html_todo(api.todos) returns text language sql stable as $$ select format($html$ @@ -200,7 +205,6 @@ Now, let's modify the ``html_todo`` function and make it more functional.
        - -