feat: Add sqlpage.set_variable function

Co-authored-by: contact <[email protected]>

Author: cursoragent

CHANGELOG.md

@@ -1,6 +1,9 @@
 # CHANGELOG.md
 
 ## unrelease
+ - **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.

examples/official-site/component.sql

@@ -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/examples/layouts.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/functions.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/sqlpage/migrations/70_set_variable.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'
+    );

src/webserver/database/sqlpage_functions/functions.rs

@@ -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>);
@@ -612,6 +613,39 @@ 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_map = serde_json::Map::with_capacity(context.url_params.len() + 1);
+
+    for (k, v) in &context.url_params {
+        params_map.insert(k.clone(), serde_json::to_value(v)?);
+    }
+
+    if let Some(value) = value {
+        params_map.insert(
+            name.into_owned(),
+            serde_json::Value::String(value.into_owned()),
+        );
+    } else {
+        params_map.remove(&*name);
+    }
+
+    let json_val = serde_json::Value::Object(params_map);
+    let encoded: URLParameters = serde_json::from_value(json_val)?;
+
+    let mut url = context.path.clone();
+    let encoded_str = encoded.get();
+    if !encoded_str.is_empty() {
+        url.push('?');
+        url.push_str(encoded_str);
+    }
+
+    Ok(url)
+}
+
 #[tokio::test]
 async fn test_hash_password() {
     let s = hash_password(Some("password".to_string()))

tests/sql_test_files/it_works_set_variable.sql

@@ -1,2 +1,7 @@
-set what_does_it_do = 'wo' || 'rks';
-select 'text' as component, 'It ' || $what_does_it_do || ' !' as contents;
+set url = sqlpage.set_variable('y', '2');
+set path = sqlpage.path();
+select 'text' as component,
+    case
+        when $url = $path || '?x=1&y=2' OR $url = $path || '?y=2&x=1' THEN 'It works !'
+        else 'error: ' || $url
+    end as contents;

tests/sql_test_files/it_works_set_variable_null.sql

@@ -0,0 +1,7 @@
+set url = sqlpage.set_variable('x', null);
+set path = sqlpage.path();
+select 'text' as component,
+    case
+        when $url = $path THEN 'It works !'
+        else 'error: ' || $url
+    end as contents;

tests/sql_test_files/it_works_set_variable_replace.sql

@@ -0,0 +1,7 @@
+set url = sqlpage.set_variable('x', '2');
+set path = sqlpage.path();
+select 'text' as component,
+    case
+        when $url = $path || '?x=2' THEN 'It works !'
+        else 'error: ' || $url
+    end as contents;