Update query param name and add docs

Author: lorefnon

examples/cards-with-remote-content/index.sql

@@ -12,10 +12,10 @@ This is useful if you want to display a lot of text in the card, with many optio
  - etc.' as description_md;
 select 
     'A card with lazy-loaded chart' as title,
-	'/chart-example.sql?embed' as embed;
+	'/chart-example.sql?_sqlpage_embed' as embed;
 select 
     'A card with lazy-loaded map' as title,
-	'/map-example.sql?embed' as embed;
+	'/map-example.sql?_sqlpage_embed' as embed;
 select 
     'A card with lazy-loaded table' as title,
-	'/table-example.sql?embed' as embed;
+	'/table-example.sql?_sqlpage_embed' as embed;

examples/official-site/custom_components.sql

@@ -16,8 +16,8 @@ Each page in SQLPage is composed of a `shell` component,
 which contains the page title and the navigation bar,
 and a series of normal components that display the data.
 
-The `shell` component is always present. If you don''t call it explicitly,
-it will be invoked with the default parameters automatically before your first component
+The `shell` component is always present unless explicitly skipped via the `?_sqlpage_embed` query parameter. 
+If you don''t call it explicitly, it will be invoked with the default parameters automatically before your first component
 invocation that tries to render data on the page.
 
 There can be only one `shell` component per site, but you can customize its appearance as you see fit.
@@ -135,4 +135,4 @@ Some interesting examples are:
     - the `../` syntax to access the parent context,
     - and the `@key` to work with objects whose keys are not known in advance.
 
-' as contents_md;
+' as contents_md;

examples/official-site/safety.sql

@@ -115,7 +115,8 @@ website, and have it perform an action on your website in the user''s name,
 because the browser will not send the cookies to your website.
 
 SQLPage differentiates between POST variables (accessed with the `:variable` syntax), and 
-variables that can come from URL parameters (accessible with `$variable`).
+variables that can come from URL parameters (accessible with `$variable`). Note that URL parameters
+prefixed with `_sqlpage_` are reserved for internal use.
 
 When a user submits a form, you should use POST variables to access the form data.
 This ensures that you only use data that indeed comes from the form, and not from a
@@ -138,4 +139,4 @@ create a specific user for SQLPage that only has access to the specific tables y
 
 If your entire application is read-only, you can even create a user that only has the `SELECT` privilege on your database,
 
-' as contents_md;
+' as contents_md;

examples/official-site/sqlpage/migrations/31_card_docs_update.sql

@@ -0,0 +1,33 @@
+DELETE FROM component WHERE name = 'card';
+
+INSERT INTO component(name, icon, description) VALUES
+    ('card', 'credit-card', 'A grid where each element is a small card that displays a piece of data.');
+INSERT INTO parameter(component, name, description, type, top_level, optional) SELECT 'card', * FROM (VALUES
+    -- top level
+    ('title', 'Text header at the top of the list of cards.', 'TEXT', TRUE, TRUE),
+    ('description', 'A short paragraph displayed below the title.', 'TEXT', TRUE, TRUE),
+    ('description_md', 'A short paragraph displayed below the title - formatted using markdown.', 'TEXT', TRUE, TRUE),
+    ('columns', 'The number of columns in the grid of cards. This is just a hint, the grid will adjust dynamically to the user''s screen size, rendering fewer columns if needed to fit the contents.', 'INTEGER', TRUE, TRUE),
+    -- item level
+    ('title', 'Name of the card, displayed at the top.', 'TEXT', FALSE, FALSE),
+    ('description', 'The body of the card, where you put the main text contents of the card.
+        This does not support rich text formatting, only plain text.
+        If you want to use rich text formatting, use the `description_md` property instead.', 'TEXT', FALSE, TRUE),
+    ('description_md', '
+        The body of the card, in Markdown format.
+        This is useful if you want to display a lot of text in the card, with many options for formatting, such as
+        line breaks, **bold**, *italics*, lists, #titles, [links](target.sql), ![images](photo.jpg), etc.', 'TEXT', FALSE, TRUE),
+    ('top_image', 'The URL (absolute or relative) of an image to display at the top of the card.', 'URL', FALSE, TRUE),
+    ('footer', 'Muted text to display at the bottom of the card.', 'TEXT', FALSE, TRUE),
+    ('footer_md', 'Muted text to display at the bottom of the card, with rich text formatting in Markdown format.', 'TEXT', FALSE, TRUE),
+    ('link', 'An URL to which the user should be taken when they click on the card.', 'URL', FALSE, TRUE),
+    ('footer_link', 'An URL to which the user should be taken when they click on the footer.', 'URL', FALSE, TRUE),
+    ('icon', 'Name of an icon to display on the left side of the card.', 'ICON', FALSE, TRUE),
+    ('color', 'The name of a color, to be displayed on the left of the card to highlight it.', 'COLOR', FALSE, TRUE),
+    ('active', 'Whether this item in the grid is considered "active". Active items are displayed more prominently.', 'BOOLEAN', FALSE, TRUE),
+    ('embed', 'A url whose contents will be fetched and injected into the body of this card.
+        This can be used to inject arbitrary html content, but is especially useful for injecting
+        the output of other sql files rendered by SQLPage. For the latter case you can pass the
+        `?_sqlpage_embed` query parameter, which will skip the shell layout', 'TEXT', FALSE, TRUE)
+) x;
+

src/webserver/http.rs

@@ -225,7 +225,7 @@ async fn render_sql(
     let (resp_send, resp_recv) = tokio::sync::oneshot::channel::<HttpResponse>();
     actix_web::rt::spawn(async move {
         let layout_context = &LayoutContext {
-            is_embedded: req_param.get_variables.get("embed").is_none(),
+            is_embedded: req_param.get_variables.get("_sqlpage_embed").is_some(),
         };
         let database_entries_stream =
             stream_query_results(&app_state.db, &sql_file, &mut req_param);