From 1265b5f1a77b4ec3895b72b287b9b89afdd667e3 Mon Sep 17 00:00:00 2001 From: Olivier Auverlot Date: Sat, 22 Nov 2025 10:37:09 +0100 Subject: [PATCH 1/4] Adding an alias named contents to the html property of the shell-empty component --- .gitignore | 1 + .../sqlpage/migrations/01_documentation.sql | 12 +++++++++++- sqlpage/templates/shell-empty.handlebars | 1 + 3 files changed, 13 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index a1a6898f..9cf4a906 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ +.DS_STORE /target sqlpage.db .idea/ diff --git a/examples/official-site/sqlpage/migrations/01_documentation.sql b/examples/official-site/sqlpage/migrations/01_documentation.sql index cbef4971..4f8aa472 100644 --- a/examples/official-site/sqlpage/migrations/01_documentation.sql +++ b/examples/official-site/sqlpage/migrations/01_documentation.sql @@ -1533,4 +1533,14 @@ so you can also [create your own shell component](custom_components.sql#custom-s If you generate your own HTML from a SQL query, you can also use the `shell-empty` component to include it in a page. Make sure you know what you are doing, and be careful to escape the HTML properly, as you are stepping out of the safe SQLPage framework and into the wild world of HTML.', - json('[{"component":"shell-empty", "html": "\n\n\n My page\n\n\n

My page

\n\n"}]')); + json('[{"component":"shell-empty", "html": "\n\n\n My page\n\n\n

My page

\n\n"}]')), + ('shell',' +### Return data in a format other than HTML +If you create a RESTful API with SQLPage and the data format transmitted to the client is not HTML, +you can use an alias named `contents` to enhance the readability of your code. +This approach is particularly useful for returning data formats such as JSON or XML. + +Remember to use the [http_header](component.sql?component=http%5Fheader) component beforehand to inform the client about the format of the data being sent. +For example, for XML, the correct [MIME](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types/Common_types) type should be `application/xml`. +', + json('[{"component":"shell-empty", "contents": "\n \n 42\n john.doe\n "}]')); diff --git a/sqlpage/templates/shell-empty.handlebars b/sqlpage/templates/shell-empty.handlebars index f71ccfc0..5614a830 100644 --- a/sqlpage/templates/shell-empty.handlebars +++ b/sqlpage/templates/shell-empty.handlebars @@ -1,2 +1,3 @@ {{{~html~}}} +{{{~contents~}}} {{~#each_row~}}{{~/each_row~}} From f1446c6f9735ec2d046505c8c645343df6575f39 Mon Sep 17 00:00:00 2001 From: Olivier Auverlot Date: Sat, 22 Nov 2025 19:35:12 +0100 Subject: [PATCH 2/4] Changes for the shell-empty documentation --- .../sqlpage/migrations/01_documentation.sql | 40 +++++++++++++------ 1 file changed, 28 insertions(+), 12 deletions(-) diff --git a/examples/official-site/sqlpage/migrations/01_documentation.sql b/examples/official-site/sqlpage/migrations/01_documentation.sql index 4f8aa472..1cecf182 100644 --- a/examples/official-site/sqlpage/migrations/01_documentation.sql +++ b/examples/official-site/sqlpage/migrations/01_documentation.sql @@ -1525,22 +1525,38 @@ SELECT SQLPage provides the `shell-empty` component to create a page without a shell. In this case, the `html` and `body` tags are not generated, and the components are rendered directly in the page without any styling, navigation bar, footer, or dynamic content. -This is useful when you want to generate a snippet of HTML that can be dynamically included in a larger page. - Any component whose name starts with `shell` will be considered as a shell component, so you can also [create your own shell component](custom_components.sql#custom-shell). +This is particularly useful when creating a [RESTful API](https://en.wikipedia.org/wiki/REST) with SQLPage. +Typically, the data returned to the client is not formatted in HTML but rather in JSON or XML. +With the `shell-empty` component, you simply need to construct the formatted data and assign it to the contents property. + +Remember to use the [http_header](component.sql?component=http%5Fheader) component beforehand to inform the client about the format of the data being sent. + +In the example below, SQLPage returns data formatted in XML. +The correct [MIME](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types/Common_types) type should be `application/xml`. +', + json('[ + { + "component":"http_header", + "Content-Type":"application/xml" + }, + { + "component":"shell-empty", + "contents": "\n \n 42\n john.doe\n " + } + ]') + ), + ('shell',' +### Generate your own HTML If you generate your own HTML from a SQL query, you can also use the `shell-empty` component to include it in a page. +This is useful when you want to generate a snippet of HTML that can be dynamically included in a larger page. Make sure you know what you are doing, and be careful to escape the HTML properly, -as you are stepping out of the safe SQLPage framework and into the wild world of HTML.', - json('[{"component":"shell-empty", "html": "\n\n\n My page\n\n\n

My page

\n\n"}]')), - ('shell',' -### Return data in a format other than HTML -If you create a RESTful API with SQLPage and the data format transmitted to the client is not HTML, -you can use an alias named `contents` to enhance the readability of your code. -This approach is particularly useful for returning data formats such as JSON or XML. +as you are stepping out of the safe SQLPage framework and into the wild world of HTML. -Remember to use the [http_header](component.sql?component=http%5Fheader) component beforehand to inform the client about the format of the data being sent. -For example, for XML, the correct [MIME](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types/Common_types) type should be `application/xml`. +In this scenario, you can use the `html` property, which serves as an alias for the `contents` property. +This property improves code readability by clearly indicating that you are generating HTML. +Since SQLPage returns HTML by default, there is no need to specify the content type in the HTTP header. ', - json('[{"component":"shell-empty", "contents": "\n \n 42\n john.doe\n "}]')); + json('[{"component":"shell-empty", "html": "\n\n\n My page\n\n\n

My page

\n\n"}]')); \ No newline at end of file From ac7bc97d6fedf49618390a2b0020cff3823a800e Mon Sep 17 00:00:00 2001 From: lovasoa Date: Sat, 22 Nov 2025 23:31:53 +0100 Subject: [PATCH 3/4] improve shell comoonent description --- .../sqlpage/migrations/01_documentation.sql | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/examples/official-site/sqlpage/migrations/01_documentation.sql b/examples/official-site/sqlpage/migrations/01_documentation.sql index 1cecf182..ac3d5686 100644 --- a/examples/official-site/sqlpage/migrations/01_documentation.sql +++ b/examples/official-site/sqlpage/migrations/01_documentation.sql @@ -1290,7 +1290,20 @@ GROUP BY name; ', NULL); INSERT INTO component(name, icon, description) VALUES - ('shell', 'layout-navbar', 'Personalize the "shell" surrounding your page contents. Used to set properties for the entire page.'); + ('shell', 'layout-navbar', ' +Customize the overall layout, header and footer of the page. + +This is a special component that provides the page structure wrapping all other components on your page. + +It generates the complete HTML document including the `` section with metadata, title, and stylesheets, +as well as the navigation bar, main content area, and footer. + +If you don''t explicitly call the shell component at the top of your SQL file, SQLPage will automatically +add a default shell component before your first try to display data on the page. + +Use the shell component to customize page-wide settings like the page title, navigation menu, theme, fonts, +and to include custom visual styles (with CSS) or interactive behavior (with JavaScript) that should be loaded on the page. +'); INSERT INTO parameter(component, name, description_md, type, top_level, optional) SELECT 'shell', * FROM (VALUES ('favicon', 'The URL of the icon the web browser should display in bookmarks and tabs. This property is particularly useful if multiple sites are hosted on the same domain with different [``site_prefix``](https://github.com/sqlpage/SQLPage/blob/main/configuration.md#configuring-sqlpage).', 'URL', TRUE, TRUE), @@ -1523,7 +1536,7 @@ SELECT ('shell', ' ### A page without a shell SQLPage provides the `shell-empty` component to create a page without a shell. -In this case, the `html` and `body` tags are not generated, and the components are rendered directly in the page +In this case, the `` and `` tags are not generated, and the components are rendered directly in the page without any styling, navigation bar, footer, or dynamic content. Any component whose name starts with `shell` will be considered as a shell component, so you can also [create your own shell component](custom_components.sql#custom-shell). From f60ba2111db64ab53010fa87e9c32d732376d878 Mon Sep 17 00:00:00 2001 From: lovasoa Date: Sat, 22 Nov 2025 23:45:26 +0100 Subject: [PATCH 4/4] shell-empty docs clarification --- .../sqlpage/migrations/01_documentation.sql | 23 +++++++++---------- 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/examples/official-site/sqlpage/migrations/01_documentation.sql b/examples/official-site/sqlpage/migrations/01_documentation.sql index ac3d5686..17bafdee 100644 --- a/examples/official-site/sqlpage/migrations/01_documentation.sql +++ b/examples/official-site/sqlpage/migrations/01_documentation.sql @@ -1534,21 +1534,20 @@ SELECT ``` ', NULL), ('shell', ' -### A page without a shell -SQLPage provides the `shell-empty` component to create a page without a shell. -In this case, the `` and `` tags are not generated, and the components are rendered directly in the page -without any styling, navigation bar, footer, or dynamic content. -Any component whose name starts with `shell` will be considered as a shell component, -so you can also [create your own shell component](custom_components.sql#custom-shell). +### Returning custom HTML, XML, plain text, or other formats -This is particularly useful when creating a [RESTful API](https://en.wikipedia.org/wiki/REST) with SQLPage. -Typically, the data returned to the client is not formatted in HTML but rather in JSON or XML. -With the `shell-empty` component, you simply need to construct the formatted data and assign it to the contents property. +Use `shell-empty` to opt out of SQLPage''s component system and return raw data directly. -Remember to use the [http_header](component.sql?component=http%5Fheader) component beforehand to inform the client about the format of the data being sent. +By default, SQLPage wraps all your content in a complete HTML page with navigation and styling. +The `shell-empty` component tells SQLPage to skip this HTML wrapper and return only the raw content you specify. -In the example below, SQLPage returns data formatted in XML. -The correct [MIME](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types/Common_types) type should be `application/xml`. +Use it to create endpoints that return things like + - XML (for JSON, use the [json](?component=json) component) + - plain text or markdown content (for instance for consumption by LLMs) + - a custom data format you need + +When using `shell-empty`, you should use the [http_header](component.sql?component=http%5Fheader) component first +to set the correct [content type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type) (like `application/json` or `application/xml`). ', json('[ {