The Insites codebase includes both the code for the application's backend, which is responsible for managing data and performing business logic and the code for the frontend, which is responsible for rendering the user interface and interacting with the backend through APIs.
The codebase is where you write your code for an Insites Instance in your local machine or environment. It is organised into several directories that contain code for an Instance's backend, frontend, config, and routes files. Organising files into separate directories ensures that your code is maintainable and scalable.
To correctly communicate with the Insites engine and API, your codebase should be organised into a specific directory structure. The root directory of your project should contain the
| Directory/file | File type | Description |
|---|---|---|
| .pos | The configuration file that specifies available endpoints. Usually, you want to have at least two endpoints – staging and production. | |
| assets | asset | Directory for static assets, like fonts, images, stylesheets, and scripts. |
| authorization_policies | Liquid | Directory for .liquid files that contain Authorization Policy configuration files. Authorisation Policies define rules that control whether a user has access to a form or page. |
| schema | YAML | Directory for .yml files that define Tables. Tables define custom objects, including their fields and associations, allowing you to create persistence containers for your custom forms. |
| emails | Liquid | Directory for .liquid files that define Email notifications. |
| api_calls | Liquid | Directory for .liquid files that define API call notifications. |
| smses | Liquid | Directory for .liquid files that define SMS notifications. |
| graphql | GraphQL | Directory for .graphql files, each defining one GraphQL Query. GraphQL queries retrieve information from or insert information into the databases. Retrieved information is made available in Liquid. |
| views/pages | Liquid | Directory for files that define pages, an essential building block of an Insites application. |
| views/layouts | Liquid | Directory for layouts. Layouts are wrappers around your page content. They ensure consistent outer content for similarly designed pages. |
| views/partials | Liquid | Directory for partials – reusable snippets of Liquid code usually used to render HTML. |
| translations | YAML | A directory for .yml files of Translations for multilingual sites that is also used to define date format or flash messages. Each file is a map of translations that can be used on your pages via Liquid. |
| user_profile_types | YAML | Directory for .yml files that define User Profiles. Each instance includes one user role, called 'default', so each instance needs to include the default.yml file inside this directory. |
| user.yml | YAML | A .yml file containing properties for all users |
| config.yml | YAML | A .yml file containing configuration flags for backward incompatible changes |
Views are divided into three categories in your codebase, each with a mandatory subdirectory:
Pages are essential building blocks of an Insites application that define content displayed at a given path. A single file represents each page with a
Insites allows you to use Liquid pages to create different endpoints beyond HTML, such as JavaScript, JSON, PDF, RSS, XML, etc. The page type can be specified in the page configuration.
Layouts are Liquid views that store repeatable code on pages that surround page content (e.g. header, footer). Without layouts, pages would share a lot of duplicated code, and changing anything would become time-consuming and error-prone. You can create as many layouts as you need and decide which page uses which layout.
Partials (partial templates) allow you to easily organise and reuse your code by extracting pieces of code to separate files. They help you improve code readability and follow the principle of DRY (Don't Repeat Yourself). You can parameterise partials and use them in various places, e.g. layouts, pages, Authorization Policies, and Forms.
Example directory structure of
The 'lib' directory helps you organize your code by allowing you to place partials not only in
The maintenance page is displayed only for valid pages and
Example directory structure of TAG lib with sample files:
Assets are files that an HTTP web server can serve without any backend/server processing. They are usually Javascript files, stylesheets (CSS), documents (HTML, pdf, doc), fonts, or media (audio, video) files.
Although only the assets directory is required, and you can put your assets there, we recommend you further organise your assets into subdirectories inside the assets directory, e.g.
Example directory structure of
Migrations are liquid files invoked only once per environment during a
To generate a migration with the current timestamp, you can use the following command:
Migrations are useful if you are making changes to the schema in a project with existing data and need to modify them slightly; for example, provide an initial value.
Example directory structure of
Just like in every web application, HTML forms are essential in Insites. Because using plain HTML forms can be difficult to maintain with complex data structures, we provide multiple tools that make working with forms much easier.
Forms are the main tool for rendering forms, persisting data, and sending notifications (email/SMS/API) in a secure and customisable way.
They give you full control when defining:
On top of that, you can define callbacks (synchronous or asynchronous) for further modifications to the system using GraphQL mutations. For example, you can define a signup form that creates User records, and if the user input is valid, also creates a few sample products for them so that they don't have to start from scratch.
Example directory structure of
Users are accounts that any of your users can have. Users are identified by their unique email addresses. You can define properties for all users in the user.yml file.
User Profiles: This feature is deprecated. We advise creating a table called
Example directory structure:
Table: An object that describes all Record objects that belong to it. Think of Tables as a custom database table, which allows you to build highly customised features. Use them to group Properties, and allow the user to provide multiple values for each.
Properties are fields that you attach to a User Profile, Table, etc. Think of them as custom database columns (though complex types, like attachments and images, should be treated as separate database tables). We also provide some Properties to jumpstart your development.
Example directory structure of
Notifications are messages sent to Insites users (including admins) when a trigger event happens. A message can be an email, SMS, or programmatic call to a 3rd party API.
Notifications can be delayed, and you can use Liquid, GraphQL, and trigger conditions to decide if a notification should be sent. They are a powerful mechanism used, for example, to welcome new users, follow up after adding their first item, or reach out to them if they have been inactive for a while.
Each notification has its own directory:
Authorisation Policies allow you to restrict access to forms and pages flexibly. Each form or page can have multiple policies attached to it.
Each policy is parsed using Liquid, and the system checks them according to their appearance in the code. Depending on policy configuration, it redirects the user to a URL provided by the developer if the condition is not met or renders an error status, for example, a 403. You can also add a flash message for the user who failed authorisation.
Example directory structure of
You can use Insites to build sites in any language, and each site can have multiple language versions. Translations are yml files used for multilingual sites but also used to define date formats, flash messages or system-wide default error messages like "can't be blank".
Example directory structure of
Config: Used to control the behaviour of the application developed. The config file is located at app/config.yml
Modules allow code reuse and sharing while protecting the IP of creators.
In your codebase, the
Module code is split into two directories to protect IP. To create a module, split the module code into
These directories have the same structure as the standard
Example directory structure of
Didn't quite find what you are looking for or have feedback on how we can make the content better then we would love to hear from you. Please provide us feedback and we will get back to you shortly.
