Codebase Introduction

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.

Required directory structure

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.

Views: pages, layouts, and partials

Views are divided into three categories in your codebase, each with a mandatory subdirectory:

• layouts
• pages
• partials

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 extension.

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 with sample files:

Lib

The 'lib' directory helps you organize your code by allowing you to place partials not only in , but also in . Both and function tags invoke TAG partial, however semantically they are different. The first one usually is used for presentation layer and include for example HTML, wheras the second one is meant to invoke business logic and return a valule. To not have to mix files for presentation with business logic, we've created a dedicated directory .

Example directory structure of TAG lib with sample files:

Assets

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. , for Javascript files, for CSS files, etc. This structure will be used by the command in creating the codebase.

Example directory structure of with sample files:

Migrations

Migrations are liquid files invoked only once per environment during a . The file name must follow the pattern . The timestamp is used for uniqueness and to know in which order migrations should be executed (which might be important).

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 with sample files:

Forms

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:

• which fields for a defined resource can be persisted
• what authorisation rules apply to be able to submit the form (i.e. if you want to edit a comment, you might want to specify that only the creator or the administrator can do it)
• what should happen when the form is submitted successfully (i.e. without validation errors), e.g. send an email/SMS Notifications or API call to a third-party system
• where the user should be redirected

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 with sample files:

Users

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 with the property.

Example directory structure:

Records

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 with sample files:

Notifications

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:

Authorization Policies

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 with sample files:

Translations

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 with sample files:

Config

Config: Used to control the behaviour of the application developed. The config file is located at app/config.yml

Modules

Modules allow code reuse and sharing while protecting the IP of creators.

In your codebase, the directory needs to be at the same level as the directory.

Module code is split into two directories to protect IP. To create a module, split the module code into and folders, and place all that code into the directory.

These directories have the same structure as the standard folder, but if developers try to download files after the module has been deployed to an Instance (), they will only have access to the files from the folder.

Example directory structure of with sample files: