You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
select'dynamic'as component, properties FROM example WHERE component ='shell'LIMIT1;
2
+
3
+
select'text'as component, '
4
+
5
+
# Creating your own SQLPage components
6
+
7
+
8
+
If you have some frontend development experience, you can create your own components, by placing
9
+
[`.handlebars`](https://handlebarsjs.com/guide/) files in a folder called `sqlpage/templates` at the root of your server.
10
+
11
+
## Web page structure
12
+
13
+
### The [`shell`](./documentation.sql?component=shell#component) component
14
+
15
+
Each page in SQLPage is composed of a `shell` component,
16
+
which contains the page title and the navigation bar,
17
+
and a series of normal components that display the data.
18
+
19
+
The `shell` component is always present. If you don''t call it explicitly,
20
+
it will be invoked with the default parameters automatically before your first component
21
+
invocation that tries to render data on the page.
22
+
23
+
There can be only one `shell` component per site, but you can customize its appearance as you see fit.
24
+
25
+
## Component template syntax
26
+
27
+
Components are written in [handlebars](https://handlebarsjs.com/guide/),
28
+
which is a simple templating language that allows you to insert data in your HTML.
29
+
30
+
Here is a simple example of a component that displays a list of items:
31
+
32
+
```handlebars
33
+
<h1>{{title}}</h1>
34
+
35
+
<ul>
36
+
{{#each_row}}
37
+
<li>{{my_property}} {{other_property}}</li>
38
+
{{/each_row}}
39
+
</ul>
40
+
```
41
+
42
+
If you save this file as `sqlpage/templates/my_list.handlebars`, you can use it in your SQL queries
43
+
by calling the `my_list` component:
44
+
45
+
```sql
46
+
SELECT ''my_list'' AS component, ''My list'' AS title;
47
+
SELECT first_name AS my_property, last_name AS other_property FROM clients;
48
+
```
49
+
50
+
### Styling
51
+
52
+
SQLPage uses [tabler](https://tabler.io/) for its default styling.
53
+
You can include any of the tabler classes in your components to style them.
54
+
Since tabler inherits from [bootstrap](https://getbootstrap.com/), you can also use bootstrap classes.
55
+
56
+
For instance, you can easily create a multi-column layout with the following code:
57
+
58
+
```handlebars
59
+
<div class="row">
60
+
{{#each_row}}
61
+
<div class="col">
62
+
{{my_property}}
63
+
</div>
64
+
{{/each_row}}
65
+
</div>
66
+
```
67
+
68
+
For custom styling, you can write your own CSS files
69
+
and include them in your page header.
70
+
You can use the `css` parameter of the default [`shell`](./documentation.sql?component=shell#component) component,
71
+
or create your own custom `shell` component with a `<link>` tag.
72
+
73
+
### Helpers
74
+
75
+
Handlebars has a concept of [helpers](https://handlebarsjs.com/guide/expressions.html#helpers),
76
+
which are functions that you can call from your templates to perform some operations.
77
+
78
+
Handlebars comes with [a few built-in helpers](https://handlebarsjs.com/guide/builtin-helpers.html),
79
+
and SQLPage adds a few more:
80
+
81
+
- `eq`, `ne`: compares two values for equality (equal, not equal)
82
+
- `gt`, `gte`, `lt`, `lte`: compares two values (greater than, greater than or equal, less than, less than or equal)
83
+
- `or`, `and`: combines two boolean values (logical operators)
84
+
- `not`: negates a boolean value (logical operator)
85
+
- `len`: returns the length of a list or string, or the number of keys in an object
86
+
- `stringify`: converts a value to its json string representation, useful to pass parameters from the database to javascript functions
87
+
- `parse_json`: parses a json string into a value, useful to accept complex parameters from databases that don''t have a native json type
88
+
- `default`: returns the first argument if it is not null, otherwise returns the second argument. For instance: `{{default my_value ''default value''}}`.
89
+
- `entries`: returns the entries of an object as a list of `{key, value}` objects.
90
+
- `delay` and `flush_delayed`: temporarily saves a value to memory, and outputs it later. For instance:
91
+
- ```handlebars
92
+
{{#if complex_condition}}
93
+
<a href="{{link}}">
94
+
{{#delay}}
95
+
</a>
96
+
{{/delay}}
97
+
{{/if}}
98
+
...
99
+
{{flush_delayed}}
100
+
```
101
+
- `sort`: sorts a list of values
102
+
- `plus`, `minus`, `sum`: mathematical operators
103
+
- `starts_with`: returns true if a string starts with another string
104
+
- `to_array`: useful to accept parameters that can optionally be repeated:
105
+
- if the argument is a list, returns it unchanged,
106
+
- if the argument is a string containing a valid json list, returns the parsed list,
107
+
- otherwise returns a list containing only the argument
108
+
- `array_contains`: returns true if a list contains a value
109
+
- `icon_img`: generate an svg icon from a *tabler* icon name
110
+
- `markdown`: renders markdown text
111
+
- `each_row`: iterates over the rows of a query result
112
+
113
+
## Overwriting the default components
114
+
115
+
You can overwrite the default components, including the `shell` component,
116
+
by creating a file with the same name in the `sqlpage/templates` folder.
117
+
118
+
For example, if you want to change the appearance of the `shell` component,
119
+
you can create a file called `sqlpage/templates/shell.handlebars` and write your own HTML in it.
120
+
If you don''t want to start from scratch, you can copy the default `shell` component
121
+
[from the SQLPage source code](https://github.com/lovasoa/SQLpage/blob/main/sqlpage/templates/shell.handlebars).
122
+
123
+
## Examples
124
+
125
+
All the default components are written in handlebars, and you can read their source code to learn how to write your own.
126
+
[See the default components source code](https://github.com/lovasoa/SQLpage/blob/main/sqlpage/templates).
- [The `card` component](https://github.com/lovasoa/SQLpage/blob/main/sqlpage/templates/card.handlebars): simple yet complete example of a component that displays a list of items.
132
+
- [The `table` component](https://github.com/lovasoa/SQLpage/blob/main/sqlpage/templates/table.handlebars): more complex example of a component that uses
133
+
- the `eq`, `or`, and `sort` handlebars helpers,
134
+
- the `../` syntax to access the parent context,
135
+
- and the `@key` to work with objects whose keys are not known in advance.
0 commit comments