From b85ee953b725fd104221b710083b2bb84d0b2cc9 Mon Sep 17 00:00:00 2001 From: Steve Chavez Date: Sat, 28 Oct 2023 12:00:37 -0500 Subject: [PATCH] doc: media type handlers (#689) * reference: media type handlers * Use function instead of computed field in editable task --------- Co-authored-by: Laurence Isla --- .../providing-html-content-using-htmx.rst | 250 ++++++++---------- docs/references/api/media_type_handlers.rst | 29 ++ postgrest.dict | 2 + 3 files changed, 138 insertions(+), 143 deletions(-) create mode 100644 docs/references/api/media_type_handlers.rst diff --git a/docs/how-tos/providing-html-content-using-htmx.rst b/docs/how-tos/providing-html-content-using-htmx.rst index 625f3df00..82db9e7ec 100644 --- a/docs/how-tos/providing-html-content-using-htmx.rst +++ b/docs/how-tos/providing-html-content-using-htmx.rst @@ -23,13 +23,12 @@ To simplify things, we won't be using authentication, so grant all permissions o 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. +Next, add the ``text/html`` media type as a DOMAIN. 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. -.. code-block:: ini +.. code-block:: postgres - # tutorial.conf - raw-media-types = "text/html" + create domain "text/html" as text; Creating an HTML Response ------------------------- @@ -38,31 +37,27 @@ Let's create a function that returns a basic HTML file, using `Tailwind CSS - - - - - PostgREST + HTMX To-Do List - - - - -
-
-
PostgREST + HTMX To-Do List
-
-
- - - $html$; - end $$; + create or replace function api.index() returns "text/html" as $$ + select $html$ + + + + + + PostgREST + HTMX To-Do List + + + + +
+
+
PostgREST + HTMX To-Do List
+
+
+ + + $html$; + $$ language sql; The web browser will open the web page at ``http://localhost:3000/rpc/index``. @@ -77,33 +72,29 @@ Now, let's show a list of the to-dos already inserted in the database. .. code-block:: postgres - create or replace function api.html_todo(api.todos) returns text - language sql stable - as $$ - select format($html$ -
  • - - %3$s - -
    • - $html$, - $1.id, - case when $1.done then 'line-through text-gray-400' else '' end, - $1.task - ); - $$; + create or replace function api.html_todo(api.todos) returns text as $$ + select format($html$ +
  • + + %3$s + +
    • + $html$, + $1.id, + case when $1.done then 'line-through text-gray-400' else '' end, + $1.task + ); + $$ language sql stable; - create or replace function api.html_all_todos() returns text - language sql - as $$ - select coalesce( - '
      ' - || string_agg(api.html_todo(t), '' order by t.id) || - '
    ', - '

    There is nothing else to do.

    ' - ) - from api.todos t; - $$; + create or replace function api.html_all_todos() returns text as $$ + select coalesce( + '
      ' + || string_agg(api.html_todo(t), '' order by t.id) || + '
    ', + '

    There is nothing else to do.

    ' + ) + from api.todos t; + $$ language sql; These two functions are used to build the to-do list template. We won't use them as PostgREST endpoints. @@ -119,56 +110,47 @@ Next, let's add an endpoint to register a to-do in the database and modify the ` .. code-block:: postgres - create or replace function api.add_todo(_task text) returns text - language plpgsql - as $$ - begin - perform set_config('response.headers','[{"Content-Type": "text/html; charset=utf-8"}]', true); + create or replace function api.add_todo(_task text) returns "text/html" as $$ insert into api.todos(task) values (_task); - return api.html_all_todos(); - end; - $$; + select api.html_all_todos(); + $$ language sql; - create or replace function api.index() returns text - language plpgsql - as $$ - begin - perform set_config('response.headers','[{"Content-Type": "text/html; charset=utf-8"}]', true); - return $html$ - - - - - - PostgREST + HTMX To-Do List - - - - - - -
    -
    -
    PostgREST + HTMX To-Do List
    -
    - -
    -
    - $html$ - || api.html_all_todos() || - $html$ -
    + create or replace function api.index() returns "text/html" as $$ + select $html$ + + + + + + PostgREST + HTMX To-Do List + + + + + + +
    +
    +
    PostgREST + HTMX To-Do List
    +
    + +
    +
    + $html$ + || api.html_all_todos() || + $html$ +
    +
    -
    - - - $html$; - end $$; + + + $html$; + $$ language sql; - The ``/rpc/add_todo`` endpoint allows us to add a new to-do using the ``_task`` parameter and returns an ``html`` with all the to-dos in the database. @@ -197,9 +179,7 @@ Now, let's modify ``api.html_todo`` and make it more functional. .. code-block:: postgres - create or replace function api.html_todo(api.todos) returns text - language sql stable - as $$ + create or replace function api.html_todo(api.todos) returns text as $$ select format($html$
  • @@ -216,8 +196,8 @@ Now, let's modify ``api.html_todo`` and make it more functional.