Skip to content

Commit 17d8925

Browse files
olivierauverlotOlivier Auverlotlovasoa
authored
Adding an alias named contents to the html property of the shell-empty component (#1122)
* Adding an alias named contents to the html property of the shell-empty component * Changes for the shell-empty documentation * improve shell comoonent description * shell-empty docs clarification --------- Co-authored-by: Olivier Auverlot <[email protected]> Co-authored-by: lovasoa <[email protected]>
1 parent 215170e commit 17d8925

File tree

3 files changed

+50
-10
lines changed

3 files changed

+50
-10
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
.DS_STORE
12
/target
23
sqlpage.db
34
.idea/

‎examples/official-site/sqlpage/migrations/01_documentation.sql‎

Lines changed: 48 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1290,7 +1290,20 @@ GROUP BY name;
12901290
', NULL);
12911291

12921292
INSERT INTO component(name, icon, description) VALUES
1293-
('shell', 'layout-navbar', 'Personalize the "shell" surrounding your page contents. Used to set properties for the entire page.');
1293+
('shell', 'layout-navbar', '
1294+
Customize the overall layout, header and footer of the page.
1295+
1296+
This is a special component that provides the page structure wrapping all other components on your page.
1297+
1298+
It generates the complete HTML document including the `<head>` section with metadata, title, and stylesheets,
1299+
as well as the navigation bar, main content area, and footer.
1300+
1301+
If you don''t explicitly call the shell component at the top of your SQL file, SQLPage will automatically
1302+
add a default shell component before your first try to display data on the page.
1303+
1304+
Use the shell component to customize page-wide settings like the page title, navigation menu, theme, fonts,
1305+
and to include custom visual styles (with CSS) or interactive behavior (with JavaScript) that should be loaded on the page.
1306+
');
12941307

12951308
INSERT INTO parameter(component, name, description_md, type, top_level, optional) SELECT 'shell', * FROM (VALUES
12961309
('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),
@@ -1521,16 +1534,41 @@ SELECT
15211534
```
15221535
', NULL),
15231536
('shell', '
1524-
### A page without a shell
1525-
SQLPage provides the `shell-empty` component to create a page without a shell.
1526-
In this case, the `html` and `body` tags are not generated, and the components are rendered directly in the page
1527-
without any styling, navigation bar, footer, or dynamic content.
1528-
This is useful when you want to generate a snippet of HTML that can be dynamically included in a larger page.
1537+
### Returning custom HTML, XML, plain text, or other formats
1538+
1539+
Use `shell-empty` to opt out of SQLPage''s component system and return raw data directly.
1540+
1541+
By default, SQLPage wraps all your content in a complete HTML page with navigation and styling.
1542+
The `shell-empty` component tells SQLPage to skip this HTML wrapper and return only the raw content you specify.
15291543
1530-
Any component whose name starts with `shell` will be considered as a shell component,
1531-
so you can also [create your own shell component](custom_components.sql#custom-shell).
1544+
Use it to create endpoints that return things like
1545+
- XML (for JSON, use the [json](?component=json) component)
1546+
- plain text or markdown content (for instance for consumption by LLMs)
1547+
- a custom data format you need
15321548
1549+
When using `shell-empty`, you should use the [http_header](component.sql?component=http%5Fheader) component first
1550+
to set the correct [content type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type) (like `application/json` or `application/xml`).
1551+
',
1552+
json('[
1553+
{
1554+
"component":"http_header",
1555+
"Content-Type":"application/xml"
1556+
},
1557+
{
1558+
"component":"shell-empty",
1559+
"contents": "<?xml version=\"1.0\"?>\n <user>\n <account>42</account>\n <login>john.doe</login>\n </user>"
1560+
}
1561+
]')
1562+
),
1563+
('shell','
1564+
### Generate your own HTML
15331565
If you generate your own HTML from a SQL query, you can also use the `shell-empty` component to include it in a page.
1566+
This is useful when you want to generate a snippet of HTML that can be dynamically included in a larger page.
15341567
Make sure you know what you are doing, and be careful to escape the HTML properly,
1535-
as you are stepping out of the safe SQLPage framework and into the wild world of HTML.',
1536-
json('[{"component":"shell-empty", "html": "<!DOCTYPE html>\n<html>\n<head>\n <title>My page</title>\n</head>\n<body>\n <h1>My page</h1>\n</body>\n</html>"}]'));
1568+
as you are stepping out of the safe SQLPage framework and into the wild world of HTML.
1569+
1570+
In this scenario, you can use the `html` property, which serves as an alias for the `contents` property.
1571+
This property improves code readability by clearly indicating that you are generating HTML.
1572+
Since SQLPage returns HTML by default, there is no need to specify the content type in the HTTP header.
1573+
',
1574+
json('[{"component":"shell-empty", "html": "<!DOCTYPE html>\n<html>\n<head>\n <title>My page</title>\n</head>\n<body>\n <h1>My page</h1>\n</body>\n</html>"}]'));

‎sqlpage/templates/shell-empty.handlebars‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
{{{~html~}}}
2+
{{{~contents~}}}
23
{{~#each_row~}}{{~/each_row~}}

0 commit comments

Comments
 (0)