MODULES
Building Custom Modules

2. Create Folder Structure

10min

A Module can contain any code that will run on Siteglide, but that code does need to be split into the relevant folders (notifications, views, etc.) and folder structures. Below, we'll take a look at how to do just that along with all the various options available to you, depending on what you would like to build.

Quick Start

You can also use our boilerplate template on Github https://github.com/Siteglide/Siteglide-Module-Boilerplate

<module_name>

The Module name is written in the following format: module_<vanity_id> . Replace vanity_id with the Vanity ID generated in your Module listing in Portal.

For example, with our Siteglide Theme Demo Module this would generate a name of module_76. Your module name (based on your generated Vanity ID) should be used anywhere the tag <module_name> is referenced in this documentation.

Create Your Staging Site

Create a new staging site within your agency to build your module on. Ideally you'll want to use a blank site, so pick the "Build a Custom Site" option on creation. Only you will see what your site is called, so you can call it anything you like.

Document image


Once you have successfully created your staging site, create a project folder on your machine to work within, connect to your site via CLI and then pull the site down onto your local machine so that you are ready to begin building your module.

Top Level Folders

When you begin building a Module, there are two top level folders that should be created alongside the marketplace_builder folder of your staging site. The top level module folders are:

  • modules/<module_name>/private
  • modules/<module_name>/public



Any information that is stored in the private folder will not be accessible to users within the Siteglide Site Admin, CLI and GraphQL. Here you should store any logic that you don’t want anyone to be able to see or edit. If you are following our example Siteglide Theme Demo Module, as it is a theme we do not have any private files and so this folder can be ignored.

Any information stored in the public folder will be accessible to users within the Siteglide Site Admin, CLI, and GraphQL. This folder should be used for any content that you would like to be visible and editable to the user.

Sub Level Folders

Under each top level folder you have the option to create any relevant folders for the information you are wanting to create and use, such as assets , views , notifications etc.

Full Folder Structure


You can view and download this full folder structure from the example directory-structure Git Repo. Alternatively, run the init command in CLI to automatically create the structure within the marketplace_builder folder and then move them into your module.

Directory/file

Explanation

Learn more

Assets

Used to store any assets (Images, Files, CSS etc) that you would like to ensure are accessible when your module is installed.



Views

Contains all layouts/partials/pages/templates visible from Admin & Front-end of a site the module is installed on.



Notifications

Email and API notifications



GraphQL

GraphQL Queries and other data handling









Module Setup Files

Beyond the standard site files that will be in your Module (GraphQL, Liquid, partials etc), the Module installation process will look for 3 other files in the root folder of your Module Project (alongside /modules/).

Folder Structure Example


setup.json

The setup.json file contains information about your module, including any tables (data) you want to create when installing your Module to a site. You can view an example of this file here.

Files generated from this JSON file:

  • Model - <module_name>.yml stored at modules/<module_name>/public/custom_model_types/modules/<module_name>.yml
  • Form Configuration - <module_name>.liquid stored at modules/<module_name>/public/form_configurations/modules/<module_name>.liquid
  • Detail Page (if applicable) - <module_name>.liquid stored at modules/<module_name>/public/views/pages/modules/<module_name>.liquid

You can find details on field types in this document

ignore-on-update.json

This file should contain a list of files you don’t want to be overwritten on sites when updating to a new version of your Module. Typically these would be any layout or asset files in your Module that a user will have edited in the last version.

Each array’s key should be the version they are created at. For example, if you want a file to be ignored when updating to any version above 1.0.0, set the key as 1.0.0.

You can see an example structure here

In this example, an update above 1.0.1 will ignore all 6 files in the list.

install-process.json

The install process file will run a Siteglide created process while the module is installed on the site. A list of all of the scripts that are relevant for each module type can be found here ::create and link::

In this example we will need a page to be set as the homepage of the site after installing the module. This is done using the set_homepage process. We will create a file with the version number of our module and set_homepage as our process as seen here.