Add sqlpage.set_variable(name, value) function and update docs (#1124)

* feat: Add sqlpage.set_variable function

Co-authored-by: contact <contact@ophir.dev>

* Refactor: Fix set_variable serialization and update tests

Co-authored-by: contact <contact@ophir.dev>

* fix tests: no json_extract on mssql

* Refactor: Update URLParameters handling in set_variable function

- Replaced serde_json::Map with a custom URLParameters struct for better management of URL parameters.
- Introduced methods for handling single and vector values in URLParameters.
- Updated tests to reflect changes in the set_variable function's behavior.

* cargo fmt

* clippy

* retsore set var test

* remove redundant test

* ensure set_variable only takes into account GET variables, not SET

* factor url parameter setting code

* v0.40

* sqlpage.set_variable links to "?" when no parameter is present

- Renamed URLParameters module for clarity and removed the deprecated url_parameter_deserializer.
- Updated the set_variable function to return parameters directly instead of appending to a URL.
- Adjusted related function calls to reflect changes in URL parameter management.

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>

Author: lovasoa

CHANGELOG.md

@@ -1,20 +1,22 @@
 # CHANGELOG.md
 
-## unrelease
+## 0.40.0 (unreleased)
+ - Fixed a bug in `sqlpage.link`: a link with no path (link to the current page) and no url parameter now works as expected. It used to keep the existing url parameters instead of removing them. `sqlpage.link('', '{}')` now returns `'?'` instead of the empty string.
+ - **New Function**: `sqlpage.set_variable(name, value)`
+   - Returns a URL with the specified variable set to the given value, preserving other existing variables.
+   - This is a shorthand for `sqlpage.link(sqlpage.path(), json_patch(sqlpage.variables('get'), json_object(name, value)))`.
  - **Variable System Improvements**: URL and POST parameters are now immutable, preventing accidental modification. User-defined variables created with `SET` remain mutable.
    - **BREAKING**: `$variable` no longer accesses POST parameters. Use `:variable` instead.
      - **What changed**: Previously, `$x` would return a POST parameter value if no GET parameter named `x` existed.
      - **Fix**: Replace `$x` with `:x` when you need to access form field values.
      - **Example**: Change `SELECT $username` to `SELECT :username` when reading form submissions.
-   - **BREAKING**: `SET $name` no longer overwrites GET (URL) parameters when a URL parameter with the same name exists.
+   - **BREAKING**: `SET $name` no longer makes GET (URL) parameters inaccessible when a URL parameter with the same name exists.
      - **What changed**: `SET $name = 'value'` would previously overwrite the URL parameter `$name`. Now it creates an independent SET variable that shadows the URL parameter.
      - **Fix**: This is generally the desired behavior. If you need to access the original URL parameter after setting a variable with the same name, extract it from the JSON returned by `sqlpage.variables('get')`.
      - **Example**: If your URL is `page.sql?name=john`, and you do `SET $name = 'modified'`, then:
        - `$name` will be `'modified'` (the SET variable)
        - The original URL parameter is still preserved and accessible:
-         - PostgreSQL: `sqlpage.variables('get')->>'name'` returns `'john'`
-         - SQLite: `json_extract(sqlpage.variables('get'), '$.name')` returns `'john'`
-         - MySQL: `JSON_UNQUOTE(JSON_EXTRACT(sqlpage.variables('get'), '$.name'))` returns `'john'`
+         - `sqlpage.variables('get')->>'name'` returns `'john'`
    - **New behavior**: Variable lookup now follows this precedence:
      - `$variable` checks SET variables first, then URL parameters
      - `:variable` checks SET variables first, then POST parameters  

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "sqlpage"
-version = "0.39.1"
+version = "0.40.0"
 edition = "2021"
 description = "Build data user interfaces entirely in SQL. A web server that takes .sql files and formats the query result using pre-made configurable professional-looking components."
 keywords = ["web", "sql", "framework"]

Cargo.toml

@@ -149,6 +149,6 @@ select
 select
     name as title,
     icon,
-    sqlpage.link('component.sql', json_object('component', name)) as link
+    sqlpage.set_variable('component', name) as link
 from component
 order by name;

examples/official-site/component.sql

@@ -30,7 +30,7 @@ For more information on how to use layouts, see the [shell component documentati
 select 'list' as component, 'Available SQLPage shell layouts' as title;
 select 
     column1 as title,
-    sqlpage.link('', json_object('layout', lower(column1), 'sidebar', $sidebar)) as link,
+    sqlpage.set_variable('layout', lower(column1)) as link,
     $layout = lower(column1) as active,
     column3 as icon,
     column2 as description
@@ -43,7 +43,7 @@ from (VALUES
 select 'list' as component, 'Available Menu layouts' as title;
 select
     column1 as title,
-    sqlpage.link('', json_object('layout', $layout, 'sidebar', column1 = 'Sidebar')) as link,
+    sqlpage.set_variable('sidebar', column1 = 'Sidebar') as link,
     (column1 = 'Sidebar' AND $sidebar = 1) OR (column1 = 'Horizontal' AND $sidebar = 0) as active,
     column2 as description,
     column3 as icon

examples/official-site/examples/layouts.sql

@@ -11,7 +11,7 @@ FROM example WHERE component = 'shell' LIMIT 1;
 select 'breadcrumb' as component;
 select 'SQLPage' as title, '/' as link, 'Home page' as description;
 select 'Functions' as title, '/functions.sql' as link, 'List of all functions' as description;
-select $function as title, sqlpage.link('functions.sql', json_object('function', $function)) as link where $function IS NOT NULL;
+select $function as title, sqlpage.set_variable('function', $function) as link where $function IS NOT NULL;
 
 select 'text' as component, 'SQLPage built-in functions' as title where $function IS NULL;
 select '
@@ -60,7 +60,7 @@ select
 select
     name as title,
     icon,
-    sqlpage.link('functions.sql', json_object('function', name)) as link
+    sqlpage.set_variable('function', name) as link
 from sqlpage_functions
 where $function IS NOT NULL
 order by name;

examples/official-site/functions.sql

@@ -0,0 +1,60 @@
+INSERT INTO
+    sqlpage_functions (
+        "name",
+        "introduced_in_version",
+        "icon",
+        "description_md"
+    )
+VALUES
+    (
+        'set_variable',
+        '0.40.0',
+        'variable',
+        'Returns a URL that is the same as the current page''s URL, but with a variable set to a new value.
+        
+This function is useful when you want to create a link that changes a parameter on the current page, while preserving other parameters.
+
+It is equivalent to `sqlpage.link(sqlpage.path(), json_patch(sqlpage.variables(''get''), json_object(name, value)))`.
+
+### Example
+
+Let''s say you have a list of products, and you want to filter them by category. You can use `sqlpage.set_variable` to create links that change the category filter, without losing other potential filters (like a search query or a sort order).
+
+```sql
+select ''button'' as component, ''sm'' as size, ''center'' as justify;
+select 
+    category as title,
+    sqlpage.set_variable(''category'', category) as link,
+    case when $category = category then ''primary'' else ''secondary'' end as color
+from categories;
+```
+
+### Parameters
+ - `name` (TEXT): The name of the variable to set.
+ - `value` (TEXT): The value to set the variable to. If `NULL` is passed, the variable is removed from the URL.
+'
+    );
+
+INSERT INTO
+    sqlpage_function_parameters (
+        "function",
+        "index",
+        "name",
+        "description_md",
+        "type"
+    )
+VALUES
+    (
+        'set_variable',
+        1,
+        'name',
+        'The name of the variable to set.',
+        'TEXT'
+    ),
+    (
+        'set_variable',
+        2,
+        'value',
+        'The value to set the variable to.',
+        'TEXT'
+    );

examples/official-site/sqlpage/migrations/72_set_variable.sql

@@ -2,7 +2,7 @@ use super::{ExecutionContext, RequestInfo};
 use crate::webserver::{
     database::{
         blob_to_data_url::vec_to_data_uri_with_mime, execute_queries::DbConn,
-        sqlpage_functions::url_parameter_deserializer::URLParameters,
+        sqlpage_functions::url_parameters::URLParameters,
     },
     http_client::make_http_client,
     request_variables::ParamMap,
@@ -46,6 +46,7 @@ super::function_definition_macro::sqlpage_functions! {
     read_file_as_text((&RequestInfo), file_path: Option<Cow<str>>);
     request_method((&RequestInfo));
     run_sql((&ExecutionContext, &mut DbConn), sql_file_path: Option<Cow<str>>, variables: Option<Cow<str>>);
+    set_variable((&ExecutionContext), name: Cow<str>, value: Option<Cow<str>>);
 
     uploaded_file_mime_type((&RequestInfo), upload_name: Cow<str>);
     uploaded_file_path((&RequestInfo), upload_name: Cow<str>);
@@ -376,11 +377,7 @@ async fn link<'a>(
         let encoded = serde_json::from_str::<URLParameters>(&parameters).with_context(|| {
             format!("link: invalid URL parameters: not a valid json object:\n{parameters}")
         })?;
-        let encoded_str = encoded.get();
-        if !encoded_str.is_empty() {
-            url.push('?');
-            url.push_str(encoded_str);
-        }
+        encoded.append_to_path(&mut url);
     }
     if let Some(hash) = hash {
         url.push('#');
@@ -612,6 +609,27 @@ async fn run_sql<'a>(
     Ok(Some(Cow::Owned(String::from_utf8(json_results_bytes)?)))
 }
 
+async fn set_variable<'a>(
+    context: &'a ExecutionContext,
+    name: Cow<'a, str>,
+    value: Option<Cow<'a, str>>,
+) -> anyhow::Result<String> {
+    let mut params = URLParameters::new();
+
+    for (k, v) in &context.url_params {
+        if k == &name {
+            continue;
+        }
+        params.push_single_or_vec(k, v.clone());
+    }
+
+    if let Some(value) = value {
+        params.push_single_or_vec(&name, SingleOrVec::Single(value.into_owned()));
+    }
+
+    Ok(params.with_empty_path())
+}
+
 #[tokio::test]
 async fn test_hash_password() {
     let s = hash_password(Some("password".to_string()))

src/webserver/database/sqlpage_functions/functions.rs

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