Academy

Welcome to the Building Custom Modules training session. Here's what we'll cover:

• Module Setup
• Creating Folder Structures
• Submitting For Approval
• Maintaining Modules

If you've not followed a training session before, then there are a few things to note about how you can use this page:

1. First, click a "Segment" on on the right-hand side of a page to skip the video to the beginning of that specific segment and start watching.
2. Second, any important links and pages we discuss during a training session can also be found on the right hand side of this page, below Segments.
3. Finally, the Overview section will outline key steps you can follow to achieve what is shown in the video. Either follow along with the video, or follow the Segment Overview, it's totally up to you!

Step 1 - Creating your Module

The first step to building your module is to create a listing for it in Siteglide. Within your Portal from the left-hand menu, select “Custom Modules” and then click the blue “+ Add New Module” button in the top right-hand corner.

Next, fill in the Module Details form. For now, you only need to provide the following basic information:

• Name: The name of your module shown in the Marketplace and Siteglide Admin.
• Version: A version number following the Semantic Versioning standard. Usually this would start as 1.0.0.
• Description: Small text description of what the Module is - appears in ? icon in ‘name’ column on the Module installation page.
• Type: Which category you would put your module into.
• Show Menu Item: Does your module need to be within the sites menu under “Modules”? For example for a theme that has no items then this would be set to No.

Now that you have created your new module, when you view it you will see that it has a “Vanity ID” field. Make a note of this number for later as it will be used within the Module.

If you would like more context or information about this step, checkout the Module Setup doc.

Step 2 - Setup before building

Module Name

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

Theme Demo

We will use the Siteglide Theme Demo as an example of a pre-built Module which is available on the Marketplace which you can install on your own staging site to view. With that in mind, anywhere in this documentation where you see text wrapped in <> are placeholders. For example would be module_76 with the Siteglide Theme Demo module (more on this later!).

Click the "Siteglide Theme Demo" link above to access the GitHub Repo and download the project to your machine before you continue.

Step 1 - Creating a 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.

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.

Step 2 - Create Public Structure

Next, create a top level folder called modules//public within your project folder. Because we are creating a basic theme Module, we don’t need to create the private top level folder. Checkout Top Level Folders for more info. 

Assets

Within the public folder, we want to add in the core assets our Theme Module will use. There are three folders we want to copy in to our own Module project folder:

• bootstrap5-plain-assets - Core Bootstrap 5 image assets which our Theme pages will display.
• js - Core Bootstrap 5 JS files along with a custom JS file which our Theme pages will run using.
• scss - Core Bootstrap 5 CSS files along with a custom CSS file which will Style our Theme pages.

Open the Module_Siteglide_ThemeDemo project folder you downloaded earlier and navigate into modules/module_name/public/assets. From here, drag and drop all three bootstrap5-plain-assets, js & scss folders into your own Module project assets folder.

Views

Next we’re going to add in various core elements such as Pages, a Page Template, Header & Footer.

First, within your modules/module_name/public folder, create a new folder called views. Inside the views folder, we’ll be creating several new folder structures to house the various files we’d like to include. Below I’ll list each of these directories and give an explanation as to what they will be used for:

• layouts/templates - A Page Template file used to wrap all of our theme pages.
• pages - Several Pages we would like to include in our module and display on the site.
• partials/includes/header - Page Header file used to store the Header including main navigation.
• partials/includes/footer - Page Footer file used to store the Footer including secondary navigation.

Open the Module_Siteglide_ThemeDemo project folder you downloaded earlier and navigate into modules/module_name/public/views. From here, drag and drop all three layouts, pages & partials folders into your own Module project views folder.

Step 4 - Correcting Your Files

As we’ve been copying files from the Theme Demo Module, we’ll need to update the module name in some paths written in the files. Open up your IDE and bulk find/replace module_76 with your .

Step 3 - Install Process JSON

Next, we want to create one of the setup file options available: install-process.json.

Create a file called install-process.json on the root folder of your Module Project (alongside /modules/). Checkout Module Setup Files for more info.

Add the following Code Snippet to your newly created Install Process file:

Adding this line of code to the install-process.json file will ensure that when a user installs our module, the home/start page is automatically applied as part of the installation. Otherwise, the existing home/start page on a site will be honoured.

Step 1 - Approval Checklist

Before submitting your Module for approval, you should check that your GitHub Repository is ready.

See the following checklist to confirm it is ready for submission:

• You’ve got all your files (assets, logic, layouts etc.) in the correct folders (private, or public)
• Your module folder is named in the correct format of
• You have not included a marketplace_builder folder
• You’ve prepared your setup.json file if a model is required for this Module and the Module ID in setup.json matches the Vanity ID in Siteglide Admin
• You’ve prepared your ignore-on-update.json file
• You’ve prepared your install-process.json file if this is required for your module
• Your Module is in a branch named master in your GitHub Repository. This is the only branch Siteglide will read from. Note that Github may name your branch main by default. If that happens you can change that here.

For more information or context to this step, checkout the Submit Module For Approval doc.

Step 2 - Send Module to Siteglide

Now that you have created your module, you will need to update the Module item that you made in Admin earlier.

You will need to edit the item with the following information:

• Menu Name - If applicable, the name to show in the left hand menu when viewing a Site Admin: Modules > My Module.
• Path- The folder name within the modules folder. This is the placeholder discussed above.
• GitHub Repo Account - The name of the GitHub account that your Module’s repository is in.
• GitHub Repo Name - The name of the GitHub repository that your Module’s code is in
• Installation Notes - Any notes on installation - appears in ! icon in ‘action’ column on the Module installation page.
• Changelog- A link to your Module’s changelog documentation, this will display within the Marketplace and next to the “Install” button.
• Live - Do you want this Module to show on the Module installation page as ready to install?

Once you have clicked "Save" with the above fields populated, your module will be submitted to the Siteglide team for review.

Step 3 - Invite Siteglide API

Once you’ve submitted your Module for approval you’ll need to give us access to see the Module. This is needed for the initial approval, but also for ongoing access to be able to install the latest version of the Module.

To provide us with access you need to invite Siteglide API (api@siteglide.com) as a collaborator for the GitHub Repository. You can do this in your repository settings.

After accepting the invitation we will review your module. This includes reading the code, installing the module onto a site and testing some of its functionality. We will create a ticket within our Support Tickets area so that you are kept up to date with progress. Once your Module is approved by us then we will allow it to be shown within the Siteglide Marketplace so any user can see and install the Module on their sites

Step 1 - Create a Staging Site

Follow the information in the Create Your Staging Site doc section for more information.

Step 2 - Create Private Structure

Custom UI Modules will follow the same folder setup as other Modules, except when you come to build the UI itself to display in Siteglide Admin. The UI will be kept in the private folder of the module as we do not want it to be discoverable outside of the frame within Siteglide Admin.

Within our private folder we can store any files that Siteglide natively supports, such as GraphQL, Liquid, Assets etc. More information about folder structure can be found at Top Level Folders.

Step 3 - Create Public Structure

If your module has any code or front-end structure you want to make available to people who install it, then you'll need to write files in the public folder structure. 

Checkout the Create Folder Structure > Top Level Folders doc for more information. 

Step 4 - Submit for approval

Follow the information in the Submit Module For Approval doc for more information.

GitHub - Maintaining Branches

When anyone installs your module, it will automatically take a copy of anything currently within the master branch of your Git Repo.

If you would like to work on updates or new additions to your module, it is strongly recommended that you create a new branch in your repository so that it does not impact what is installed until your are ready.

For more information checkout the Maintaining Your Git Repo doc section.

Siteglide - Notify Customers

Once you have committed a new version to your master branch in Git, edit your module in Siteglide Portal to update the version number and let people know there is a new version available to install.

For more information checkout the Notifying Users Of An Update doc section.