From 6efdf206fb0bc5a9d7777347cb6535d5d800b6dc Mon Sep 17 00:00:00 2001 From: lovasoa Date: Mon, 6 Nov 2023 01:35:21 +0100 Subject: [PATCH] document custom component creation --- configuration.md | 2 + examples/official-site/custom_components.sql | 137 ++++++++++++++++++ examples/official-site/documentation.sql | 5 +- examples/official-site/prism-tabler-theme.css | 13 ++ sqlpage/templates/README.md | 3 +- 5 files changed, 156 insertions(+), 4 deletions(-) create mode 100644 examples/official-site/custom_components.sql diff --git a/configuration.md b/configuration.md index 790ab2ba..30f28534 100644 --- a/configuration.md +++ b/configuration.md @@ -51,6 +51,8 @@ For instance, if you want to create a custom `my_component` component, that disp ``` +[See the full custom component documentation](https://sql.ophir.dev/custom_components.sql). + ## Connection initialization scripts SQLPage allows you to run a SQL script when a new database connection is opened, diff --git a/examples/official-site/custom_components.sql b/examples/official-site/custom_components.sql new file mode 100644 index 00000000..5862dc69 --- /dev/null +++ b/examples/official-site/custom_components.sql @@ -0,0 +1,137 @@ +select 'dynamic' as component, properties FROM example WHERE component = 'shell' LIMIT 1; + +select 'text' as component, ' + +# Creating your own SQLPage components + + +If you have some frontend development experience, you can create your own components, by placing +[`.handlebars`](https://handlebarsjs.com/guide/) files in a folder called `sqlpage/templates` at the root of your server. + +## Web page structure + +### The [`shell`](./documentation.sql?component=shell#component) component + +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 +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. + +## Component template syntax + +Components are written in [handlebars](https://handlebarsjs.com/guide/), +which is a simple templating language that allows you to insert data in your HTML. + +Here is a simple example of a component that displays a list of items: + +```handlebars +

{{title}}

+ + +``` + +If you save this file as `sqlpage/templates/my_list.handlebars`, you can use it in your SQL queries +by calling the `my_list` component: + +```sql +SELECT ''my_list'' AS component, ''My list'' AS title; +SELECT first_name AS my_property, last_name AS other_property FROM clients; +``` + +### Styling + +SQLPage uses [tabler](https://tabler.io/) for its default styling. +You can include any of the tabler classes in your components to style them. +Since tabler inherits from [bootstrap](https://getbootstrap.com/), you can also use bootstrap classes. + +For instance, you can easily create a multi-column layout with the following code: + +```handlebars +
+{{#each_row}} +
+ {{my_property}} +
+{{/each_row}} +
+``` + +For custom styling, you can write your own CSS files +and include them in your page header. +You can use the `css` parameter of the default [`shell`](./documentation.sql?component=shell#component) component, +or create your own custom `shell` component with a `` tag. + +### Helpers + +Handlebars has a concept of [helpers](https://handlebarsjs.com/guide/expressions.html#helpers), +which are functions that you can call from your templates to perform some operations. + +Handlebars comes with [a few built-in helpers](https://handlebarsjs.com/guide/builtin-helpers.html), +and SQLPage adds a few more: + +- `eq`, `ne`: compares two values for equality (equal, not equal) +- `gt`, `gte`, `lt`, `lte`: compares two values (greater than, greater than or equal, less than, less than or equal) +- `or`, `and`: combines two boolean values (logical operators) +- `not`: negates a boolean value (logical operator) +- `len`: returns the length of a list or string, or the number of keys in an object +- `stringify`: converts a value to its json string representation, useful to pass parameters from the database to javascript functions +- `parse_json`: parses a json string into a value, useful to accept complex parameters from databases that don''t have a native json type +- `default`: returns the first argument if it is not null, otherwise returns the second argument. For instance: `{{default my_value ''default value''}}`. +- `entries`: returns the entries of an object as a list of `{key, value}` objects. +- `delay` and `flush_delayed`: temporarily saves a value to memory, and outputs it later. For instance: + - ```handlebars + {{#if complex_condition}} + + {{#delay}} + + {{/delay}} + {{/if}} + ... + {{flush_delayed}} + ``` +- `sort`: sorts a list of values +- `plus`, `minus`, `sum`: mathematical operators +- `starts_with`: returns true if a string starts with another string +- `to_array`: useful to accept parameters that can optionally be repeated: + - if the argument is a list, returns it unchanged, + - if the argument is a string containing a valid json list, returns the parsed list, + - otherwise returns a list containing only the argument +- `array_contains`: returns true if a list contains a value +- `icon_img`: generate an svg icon from a *tabler* icon name +- `markdown`: renders markdown text +- `each_row`: iterates over the rows of a query result + +## Overwriting the default components + +You can overwrite the default components, including the `shell` component, + by creating a file with the same name in the `sqlpage/templates` folder. + +For example, if you want to change the appearance of the `shell` component, +you can create a file called `sqlpage/templates/shell.handlebars` and write your own HTML in it. +If you don''t want to start from scratch, you can copy the default `shell` component +[from the SQLPage source code](https://github.com/lovasoa/SQLpage/blob/main/sqlpage/templates/shell.handlebars). + +## Examples + +All the default components are written in handlebars, and you can read their source code to learn how to write your own. +[See the default components source code](https://github.com/lovasoa/SQLpage/blob/main/sqlpage/templates). + +Some interesting examples are: + + - [The `shell` component](https://github.com/lovasoa/SQLpage/blob/main/sqlpage/templates/shell.handlebars) + - [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. + - [The `table` component](https://github.com/lovasoa/SQLpage/blob/main/sqlpage/templates/table.handlebars): more complex example of a component that uses + - the `eq`, `or`, and `sort` handlebars helpers, + - the `../` syntax to access the parent context, + - and the `@key` to work with objects whose keys are not known in advance. + +' as contents_md; \ No newline at end of file diff --git a/examples/official-site/documentation.sql b/examples/official-site/documentation.sql index 7c7e01aa..603db664 100644 --- a/examples/official-site/documentation.sql +++ b/examples/official-site/documentation.sql @@ -39,9 +39,8 @@ This page documents all the components provided by default in SQLPage and their Use this as a reference when building your SQL application. If at any point you need help, you can ask for it on the [SQLPage forum](https://github.com/lovasoa/SQLpage/discussions). -If you have some frontend development experience, you can also create your own components, by placing -[`.handlebars`](https://handlebarsjs.com/guide/) files in a folder called `sqlpage/templates` at the root of your server. -[See example](https://github.com/lovasoa/SQLpage/blob/main/sqlpage/templates/list.handlebars). +If you know some [HTML](https://developer.mozilla.org/en-US/docs/Learn/Getting_started_with_the_web/HTML_basics), +you can also easily [create your own components for your application](./custom_components.sql). ' as contents_md; select 'list' as component, 'components' as title; diff --git a/examples/official-site/prism-tabler-theme.css b/examples/official-site/prism-tabler-theme.css index 8b3a84c4..63b4611f 100644 --- a/examples/official-site/prism-tabler-theme.css +++ b/examples/official-site/prism-tabler-theme.css @@ -16,6 +16,15 @@ .token.property, .token.tag { color: #f92672; + + /* We need to reset the 'tag' styles set by tabler */ + border: 0; + display: inherit; + height: inherit; + border-radius: inherit; + padding: 0; + background: inherit; + box-shadow: inherit; } .token.number { @@ -76,4 +85,8 @@ code::selection, code ::selection { code .token.keyword::selection, code .token.punctuation::selection { color: var(--tblr-gray-800); +} + +pre code { + padding: 0; } \ No newline at end of file diff --git a/sqlpage/templates/README.md b/sqlpage/templates/README.md index f25b8957..b1521b0a 100644 --- a/sqlpage/templates/README.md +++ b/sqlpage/templates/README.md @@ -11,7 +11,8 @@ These are documented on https://sql.ophir.dev/components.sql ## Custom components -You can write your own component templates and place them in the `sqlpage/templates` directory. +You can [write your own component templates](https://sql.ophir.dev/custom_components.sql) +and place them in the `sqlpage/templates` directory. To override a default component, create a file with the same name as the default component. If you want to start from an existing component, you can copy it from the `sqlpage/templates` directory in the SQLPage source code[^2].