Merge pull request #494 from lovasoa/sqlpage.link

new sqlpage.link function

Author: lovasoa

CHANGELOG.md

@@ -27,6 +27,16 @@
  - Updated apexcharts.js to [v3.50.0](https://github.com/apexcharts/apexcharts.js/releases/tag/v3.50.0)
  - Improve truncation of long page titles
    - ![screenshot long title](https://github.com/lovasoa/SQLpage/assets/552629/9859023e-c706-47b3-aa9e-1c613046fdfa)
+ - new function: [`sqlpage.link`](https://sql.ophir.dev/functions.sql?function=link#function) to easily create links with parameters between pages. For instance, you can now use
+      ```sql
+      select 'list' as component;
+      select
+        product_name as title,
+        sqlpage.link('product.sql', json_object('product', product_name)) as link
+      from products;
+      ```
+    - Before, you would usually build the link manually with `CONCAT('/product.sql?product=', product_name)`, which would fail if the product name contained special characters like '&'. The new `sqlpage.link` function takes care of encoding the parameters correctly.
+ - Calls to `json_object` are now accepted as arguments to SQLPage functions. This allows you to pass complex data structures to functions such as `sqlpage.fetch`, `sqlpage.run_sql`, and `sqlpage.link`. 
 
 ## 0.24.0 (2024-06-23)
  - in the form component, searchable `select` fields now support more than 50 options. They used to display only the first 50 options. 

Dockerfile

@@ -1,4 +1,4 @@
-FROM --platform=$BUILDPLATFORM rust:1.78-slim as builder
+FROM --platform=$BUILDPLATFORM rust:1.79-slim as builder
 WORKDIR /usr/src/sqlpage
 ARG TARGETARCH
 ARG BUILDARCH

examples/CRUD - Authentication/README.md

@@ -21,7 +21,7 @@ SET $_username = (
 ```sql
 SELECT
     'redirect' AS component,
-    '/login.sql?path=' || $_curpath AS link
+    sqlpage.link('/login.sql', json_object('path', $_curpath)) AS link
 WHERE $_username IS NULL AND $_session_required;
 ```
 4. The login page renders the login form, accepts the user credentials, and redirects to create_session.sql, passing the login credentials as POST variables.

examples/CRUD - Authentication/www/create_session.sql

@@ -2,7 +2,7 @@
 
 SELECT
     'authentication' AS component,
-    'login.sql?' || ifnull('path=' || $path, '') || '&error=1' AS link,
+    'login.sql?' || ifnull('path=' || sqlpage.url_encode($path), '') || '&error=1' AS link,
     :password AS password,
     (SELECT password_hash
      FROM accounts

examples/charts, computations and custom components/index.sql

@@ -11,7 +11,7 @@ SELECT 'hero' as component,
         'Tap Tempo' as title,
         'Tap Tempo is a tool to **measure a tempo in bpm** by clicking a button in rythm.' as description_md,
         'drums by Nana Yaw Otoo.jpg' as image,
-        'taptempo.sql?session=' || random() as link,
+        sqlpage.link('taptempo.sql', json_object('session', random())) as link,
         'Start tapping !' as link_text;
 
 SELECT 'text' as component,

examples/charts, computations and custom components/taptempo.sql

@@ -8,7 +8,7 @@ SELECT 'big_button' as component,
             (SELECT bpm || ' bpm' FROM tap_bpm WHERE tapping_session = $session ORDER BY day DESC LIMIT 1),
             'Tap'
           ) AS text,
-         'taptempo.sql?session=' || $session as link;
+         sqlpage.link('taptempo.sql', json_object('session', $session)) as link;
 
 SELECT 'chart' as component, 'BPM over time' as title, 'area' as type, 'indigo' as color, 0 AS ymin, 200 AS ymax, 'BPM' as ytitle;
 SELECT * FROM (

examples/corporate-conundrum/New Game.sql

@@ -1,7 +1,5 @@
 INSERT INTO games(id)
 VALUES(random())
 RETURNING
-    'http_header' as component,
-    'game.sql?id='||id as "Location";
-
-SELECT 'text' as component, 'redirecting to game...' as contents;
+    'redirect' as component,
+    CONCAT('game.sql?id=', id) as link;

examples/corporate-conundrum/game.sql

@@ -5,10 +5,17 @@ INSERT INTO players(name, game_id)
 SELECT $Player as name,
     $id::integer as game_id
 WHERE $Player IS NOT NULL;
+
 SELECT 'list' as component,
     'Players' as title;
 SELECT name as title,
-    'next-question.sql?game_id=' || game_id || '&player=' || name as link
+    sqlpage.link(
+        'next-question.sql', 
+        json_object(
+            'game_id', game_id,
+            'player', name
+        )
+     ) as link
 FROM players
 WHERE game_id = $id::integer;
 ---------------------------

examples/corporate-conundrum/next-question.sql

@@ -1,21 +1,32 @@
-SELECT 'http_header' as component,
-    COALESCE(
-        (
-            SELECT 'question.sql?game_id=' || $game_id || '&question_id=' || game_questions.question_id || '&player=' || $player as "Location"
-            FROM game_questions
-            WHERE game_id = $game_id::integer
-                AND NOT EXISTS (
-                    -- This will filter out questions that have already been answered by the player
-                    SELECT 1
-                    FROM answers
-                    WHERE answers.game_id = game_questions.game_id
-                        AND answers.player_name = $player
-                        AND answers.question_id = game_questions.question_id
-                )
-            ORDER BY game_order
-            LIMIT 1
-        ),
-        'game-over.sql?game_id=' || $game_id
-    ) as 'Location';
-SELECT 'text' as component,
-    'redirecting to next question...' as contents;
+-- We need to redirect the user to the next question in the game if there is one, or to the game over page if there are no more questions.
+with next_question as (
+    SELECT 
+        'question.sql' as page,
+        json_object(
+            'game_id', $game_id,
+            'question_id', game_questions.question_id,
+            'player', $player
+        ) as params
+    FROM game_questions
+    WHERE game_id = $game_id::integer
+        AND NOT EXISTS (
+            -- This will filter out questions that have already been answered by the player
+            SELECT 1
+            FROM answers
+            WHERE answers.game_id = game_questions.game_id
+                AND answers.player_name = $player
+                AND answers.question_id = game_questions.question_id
+        )
+    ORDER BY game_order
+    LIMIT 1
+),
+next_page as (
+        SELECT * FROM next_question
+    UNION ALL
+        SELECT 'game-over.sql' as page, json_object('game_id', $game_id) as params
+        WHERE NOT EXISTS (SELECT 1 FROM next_question)
+)
+SELECT 'redirect' as component,
+    sqlpage.link(page, params) as link
+FROM next_page
+LIMIT 1;

examples/corporate-conundrum/question.sql

@@ -3,7 +3,7 @@ select * FROM sqlpage_shell;
 SELECT 'form' as component,
     question_text as title,
     'Submit your answer' as validate,
-    'wait.sql?game_id='|| $game_id ||'&question_id=' || $question_id ||'&player=' || $player as action
+    sqlpage.link('wait.sql', json_object('game_id', $game_id, 'question_id', $question_id, 'player', $player)) as action
 FROM questions
 where id = $question_id::integer;
 

examples/corporate-conundrum/wait.sql

@@ -1,12 +1,14 @@
 -- Redirect to the next question when all players have answered
+set page_params = json_object('game_id', $game_id, 'player', $player);
 select CASE
         (SELECT count(*) FROM answers WHERE question_id = $question_id AND game_id = $game_id::integer)
         WHEN (SELECT count(*) FROM players WHERE game_id = $game_id::integer)
-        THEN '0; next-question.sql?game_id=' || $game_id || '&player=' || $player
+        THEN '0; ' || sqlpage.link('next-question.sql', $page_params)
         ELSE 3
     END as refresh,
     sqlpage_shell.*
 FROM sqlpage_shell;
+
 -- Insert the answer into the answers table
 INSERT INTO answers(game_id, player_name, question_id, answer_value)
 SELECT $game_id::integer as game_id,

examples/official-site/blog.sql

@@ -10,11 +10,9 @@ SELECT 'list' AS component,
 SELECT title,
     description,
     icon,
-    CASE 
-        WHEN external_url IS NOT NULL
-        THEN external_url
-    ELSE 
-        '?post=' || title
-    END AS link
+    sqlpage.link(
+        COALESCE(external_url, ''),
+        CASE WHEN external_url IS NULL THEN json_object('post', title) ELSE NULL END
+    ) AS link
 FROM blog_posts
 ORDER BY created_at DESC;

examples/official-site/sqlpage/migrations/47_link.sql

@@ -0,0 +1,74 @@
+INSERT INTO
+    sqlpage_functions (
+        "name",
+        "introduced_in_version",
+        "icon",
+        "description_md"
+    )
+VALUES
+    (
+        'link',
+        '0.25.0',
+        'link',
+        'Returns the URL of a SQLPage file with the given parameters.
+
+### Example
+
+Let''s say you have a database of products, and you want the main page (`index.sql`) to link to the page of each product (`product.sql`) with the product name as a parameter.
+
+In `index.sql`, you can use the `link` function to generate the URL of the product page for each product:
+
+```sql
+select ''list'' as component;
+select
+    name as title,
+    sqlpage.link(''product.sql'', json_object(''product_name'', name)) as link;
+```
+
+Using `sqlpage.link` is better than manually constructing the URL with `CONCAT(''product.sql?product_name='', name)`, because it ensures that the URL is properly encoded.
+The former works when the product name contains special characters like `&`, while the latter would break the URL.
+
+In `product.sql`, you can then use `$product_name` to get the name of the product from the URL parameter:
+
+```sql
+select ''text'' as component;
+select CONCAT(''Product: '', $product_name) as contents;
+```
+
+### Parameters
+ - `file` (TEXT): The name of the SQLPage file to link to.
+ - `parameters` (JSON): The parameters to pass to the linked file.
+ - `fragment` (TEXT): An optional fragment (hash) to append to the URL. This is useful for linking to a specific section of a page. For instance if `product.sql` contains `select ''text'' as component, ''product_description'' as id;`, you can link to the product description section with `sqlpage.link(''product.sql'', json_object(''product_name'', name), ''product_description'')`.
+'
+    );
+
+INSERT INTO
+    sqlpage_function_parameters (
+        "function",
+        "index",
+        "name",
+        "description_md",
+        "type"
+    )
+VALUES
+    (
+        'link',
+        1,
+        'file',
+        'The path of the SQLPage file to link to, relative to the current file.',
+        'TEXT'
+    ),
+    (
+        'link',
+        2,
+        'parameters',
+        'A JSON object with the parameters to pass to the linked file.',
+        'JSON'
+    ),
+    (
+        'link',
+        3,
+        'fragment',
+        'An optional fragment (hash) to append to the URL to link to a specific section of the target page.',
+        'TEXT'
+    );

lambda.Dockerfile

@@ -1,4 +1,4 @@
-FROM rust:1.78-alpine as builder
+FROM rust:1.79-alpine as builder
 RUN rustup component add clippy rustfmt
 RUN apk add --no-cache musl-dev zip
 WORKDIR /usr/src/sqlpage

src/webserver/database/sql.rs

@@ -587,14 +587,26 @@ fn expr_to_stmt_param(arg: &mut Expr) -> Option<StmtParam> {
                     ..
                 }),
             ..
-        }) if func_name_parts.len() == 1
-            && func_name_parts[0].value.eq_ignore_ascii_case("concat") =>
-        {
-            let mut concat_args = Vec::with_capacity(args.len());
-            for arg in args {
-                concat_args.push(function_arg_to_stmt_param(arg)?);
+        }) if func_name_parts.len() == 1 => {
+            let func_name = func_name_parts[0].value.as_str();
+            if func_name.eq_ignore_ascii_case("concat") {
+                let mut concat_args = Vec::with_capacity(args.len());
+                for arg in args {
+                    concat_args.push(function_arg_to_stmt_param(arg)?);
+                }
+                Some(StmtParam::Concat(concat_args))
+            } else if func_name.eq_ignore_ascii_case("json_object")
+                || func_name.eq_ignore_ascii_case("json_build_object")
+            {
+                let mut json_obj_args = Vec::with_capacity(args.len());
+                for arg in args {
+                    json_obj_args.push(function_arg_to_stmt_param(arg)?);
+                }
+                Some(StmtParam::JsonObject(json_obj_args))
+            } else {
+                log::warn!("SQLPage cannot emulate the following function: {func_name}");
+                None
             }
-            Some(StmtParam::Concat(concat_args))
         }
         _ => {
             log::warn!("Unsupported function argument: {arg}");

src/webserver/database/sqlpage_functions/functions.rs

@@ -1,6 +1,10 @@
 use super::RequestInfo;
 use crate::webserver::{
-    database::execute_queries::DbConn, http::SingleOrVec, request_variables::ParamMap,
+    database::{
+        execute_queries::DbConn, sqlpage_functions::url_parameter_deserializer::URLParameters,
+    },
+    http::SingleOrVec,
+    request_variables::ParamMap,
     ErrorWithStatus,
 };
 use anyhow::{anyhow, Context};
@@ -23,6 +27,8 @@ super::function_definition_macro::sqlpage_functions! {
     hash_password(password: Option<String>);
     header((&RequestInfo), name: Cow<str>);
 
+    link(file: Cow<str>, parameters: Option<Cow<str>>, hash: Option<Cow<str>>);
+
     path((&RequestInfo));
     persist_uploaded_file((&RequestInfo), field_name: Cow<str>, folder: Option<Cow<str>>, allowed_extensions: Option<Cow<str>>);
     protocol((&RequestInfo));
@@ -188,6 +194,29 @@ async fn header<'a>(request: &'a RequestInfo, name: Cow<'a, str>) -> Option<Cow<
     request.headers.get(&*name).map(SingleOrVec::as_json_str)
 }
 
+/// Builds a URL from a file name and a JSON object conatining URL parameters.
+/// For instance, if the file is "index.sql" and the parameters are {"x": "hello world"},
+/// the result will be "index.sql?x=hello%20world".
+async fn link<'a>(
+    file: Cow<'a, str>,
+    parameters: Option<Cow<'a, str>>,
+    hash: Option<Cow<'a, str>>,
+) -> anyhow::Result<String> {
+    let mut url = file.into_owned();
+    if let Some(parameters) = parameters {
+        url.push('?');
+        let encoded = serde_json::from_str::<URLParameters>(&parameters).with_context(|| {
+            format!("link: invalid URL parameters: not a valid json object:\n{parameters}")
+        })?;
+        url.push_str(encoded.get());
+    }
+    if let Some(hash) = hash {
+        url.push('#');
+        url.push_str(&hash);
+    }
+    Ok(url)
+}
+
 /// Returns the path component of the URL of the current request.
 async fn path(request: &RequestInfo) -> &str {
     &request.path

src/webserver/database/sqlpage_functions/mod.rs

@@ -2,6 +2,7 @@ mod function_definition_macro;
 mod function_traits;
 pub(super) mod functions;
 mod http_fetch_request;
+mod url_parameter_deserializer;
 
 use sqlparser::ast::FunctionArg;