Creating your own SQLPage components

If you have some frontend development experience, you can create your own components, by placing .handlebars files in a folder called sqlpage/templates at the root of your server.

Web page structure

The shell 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, 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:


    <li>{{my_property}} {{other_property}}</li>

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:

SELECT 'my_list' AS component, 'My list' AS title;
SELECT first_name AS my_property, last_name AS other_property FROM clients;


SQLPage uses tabler for its default styling. You can include any of the tabler classes in your components to style them. Since tabler inherits from bootstrap, you can also use bootstrap classes.

For instance, you can easily create a multi-column layout with the following code:

<div class="row">
    <div class="col">

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 component, or create your own custom shell component with a <link> tag.


Handlebars has a concept of helpers, which are functions that you can call from your templates to perform some operations.

Handlebars comes with a few built-in helpers, and SQLPage adds a few more:

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.


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.

Some interesting examples are:

Official SQLPage documentation