Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Building Modules could be the perfect way to keep your workflow "DRY" (don't repeat yourself)! If you find a common requirement on more than one site, and no-one is currently offering a solution, or you think you can build a better one, building Modules might be for you.
This documentation section is a work in progress. If you have any questions in the meantime, please don't hesitate to get in touch and we'd be happy to help!
For some types of Module, anyone can have a go, for example building a Site Template could be done by a Designer with a little bit of HTML and CSS knowledge:
For other kinds of Module, we recommend getting hold of a developer. If you don't have one, check out Sitegurus who can provide this service.
One way to start building Modules is to build them as an internal tool for your Agency. This doesn't require any approval from Siteglide.
Or, you can publish your Module on the marketplace. This requires Siteglide approval so we can check the module is transparent about the kind of code it runs. You can either:
Make the Module Open-Source
You can either all Siteglide users access, or require them to contact you before you decide whether to give their organisation access
You can optionally allow others to contribute to your Github repository
or Accept Payments
This section is for developers that want to build Templates and Modules for the Marketplace.
Here we will outline the process involved in creating, building, submitting, and maintaining a Module in the following series of docs.
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 <module_name>
would be module_76
with the Siteglide Theme Demo module (more on this later!).
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.
We will come back later to enter information into the remaining fields, so for now click the blue “Save” button in the bottom right-hand corner to save your new module. Your module will only be visible to yourself at this point as it is not marked as “Public” and has not been approved for the Marketplace.
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.
Templates are whole sites which have been saved so that you and other users can easily create copies of it moving forward. They are excellent for creating turnkey solutions for specific industries and client types, allowing you to sell a theme and then customise to each client on top.
Build out as much of a site as you’d like on a Trial site, then turn it into a template on the marketplace, making it publicly available to be installed during the creation of new sites.
First, find a template you’d like to use for a new site in the Marketplace. You can use the filter category at the top of the Marketplace page to filter ‘Templates’ only to find options more quickly.
Click on a template to view the popup for more information and images. If you would like to use this template, then continue to the next step below.
Once the template popup appears, you can create a new trial site using this template by selecting an owner in the “Site Owner” field, and then entering a name for your new site in the “Site Name” field.
Click the blue 'Create Site from Template' button, and then wait for the template copying process to complete.
Once you receive your email notification to tell you the site is ready, your new template site will appear in your sites list. From here you can edit the site just like any other, by clicking the 'Admin' button.
Have you created a site that you’d like to turn into a reusable template?
Head over to Marketplace and click the blue “+add a new Module” button. Next, follow the usual Module creation process, but be sure to select the “Template” category from “Category” the dropdown field in the Module Details tab.
Select the trial site you want to convert to a Template Module using the “Site” dropdown field displayed below the Name, Category & Description fields.
Note: Only trial sites can be converted to a Template Module.
Once you have created your Template Module, you can either keep it for internal use within your team, or allow the template to be publicly viewable and installable.
If a template is both publicly viewable and installable, then the master trial site will be locked for editing (with a status of “Locked - Template”). The site is locked to prevent other users making copies of a site that has any ongoing work.
If the site were not locked, then the copy process could be triggered whilst there are unfinished changes from the managing development team. If you wish to make edits to the master trial site, at any time you can remove the template from the Marketplace by toggling either the 'Publicly viewable' or 'Publicly installable' values to 'No'.
The master trial site will then be editable again until you toggle both of those values back to 'Yes'.
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.
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 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.
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.
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.
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.
https://documentation.platformos.com/developer-guide/platformos-workflow/codebase
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/
).
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
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.
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.
Here I will outline key tips and information in maintaing your existing module once it has been created.
When anyone (yourself or someone else) 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.
Create a new branch and call staging
for example. From now on, send your initial commits to staging while you are testing. When you are ready to release an update to your module, merge into the master
branch in Git.
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.
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
You can set your Module up to require payment before a user can install it.
All payments are handled through your Stripe account.
Follow the steps below to add this requirement:
You need to link your Stripe account to your Agency in order to take payments. Go to your Agency edit view, and click the 'Marketplace Payment Details' tab. Read the details shown on this screen and then enter your Stripe Secret Key (found here)
Go to the Module edit view, and click the 'Payment Details' tab. Here you can toggle 'Take Payment?' to 'Yes' if it is required.
Enter the Stripe Product ID for your Module. This Product will need a Price attached to it in Stripe.
Select the Access Type you want to grant. There's 2 options:
User only - This will grant access to the paying User
Agency-wide - This will grant access to the entire Agency of the paying User
You can manually manage User/Agency IDs in the 'Access List' field if you need to do so. This field will auto-update when a User pays for your Module.
That's it! Now, when a User sees your Module in the Marketplace they'll be required to pay before they can install the Module.
In this example we're going walk through, step by step, how to create a Website Theme Module that could either be used as a private module for your agency or shared publicly in the marketplace to deliver turnkey site solutions to your clients and more.
It is recommended that you download our example Theme Demo Module Repository from GitHub so that you have all of the code and asset files available at each step of this guide and can easily follow along to and have your module end up looking exactly the same.
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.
You only need to fill in basic information into the core fields. Checkout the Create Create your Module in Siteglide doc for more information.
Remember to note down your newly generated Vanity ID.
First, create a fresh staging site for your module. Checkout Create Your Staging Site : for more information on this step.
Second, create a folder for your project on your local machine. Working within your new project folder, connect to your new staging site via CLI to pull the initial site files down onto your computer.
Next, create a top level folder called modules/<module_name>/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.
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.
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.
Setting Pages up with appropriate Template, Header & Footer files allows us to only write the code once and apply it consistently across all of our theme pages. It also makes it easier to update later if we’d like to. For more information on page structure checkout: Templates - Getting Started.
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.
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 <module_name>
.
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.
Now that we have added all of the core assets and views to our module, let’s see it in action!
Using CLI run the deploy command to send all of the files within your project folder up to your staging site.
Open your staging site to view your work both front-end and back end.
Your site should now look and behave like this front-end: Module Siteglide Theme Demo.
If you’re happy everything looks as it should, continue to the final step. If not, check back along the steps above to make sure you’ve not missed anything.
First, delete the marketplace_builder
folder from your project folder on your local machine. We don’t want to include this to avoid overwriting any pre-existing content on sites which install our module.
Follow the checklist to confirm your Theme Module is ready for submission:
Here is what your project folder should now look like:
Now that we have prepared our files, if you haven’t already create a new GitHub Repository and commit your project folder to it.
Please ensure:
Next we will need to update the Module item that you made in Admin earlier to include some extra information. Checkout the Sending your Module to Siteglide doc for more information.
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. Checkout the After Submitting your Module doc for more information.
There are a couple of key things you should be aware of when managing and updating your module moving forward. Checkout this doc for more info: Updating Existing Modules.
In this section, we'll add reference code which is relevant across Modules. Specific Modules may have further relevant reference material in their own sections of the docs.
These Fields are available to all standard modules:
<div data-gb-custom-block data-tag="-" data-0='module' data-1=', id: ' data-2='3' data-3='3' data-4='default' data-5='default' data-6='1' data-7='1' data-8='1' data-9='1' data-10='1' data-11='1' data-12='1' data-13='properties.release_date' data-14=', sort_order: ' data-15='asc' data-16='asc'></div>
`
`
id
- the Module's ID
item_ids
- output one or more module items, comma separated
category_ids
- output all items in one or more categories, comma separated
layout
- default is /default/ - 'layout' values are relative to the folder: layouts/modules/Blog (module_3)/[layout name]
per_page
- defines the number of items outputted on the page
show_pagination
- default is true - defines if items should be paginated when the per_page is met.
sort_type
- defines the type by which items are ordered
properties.name
- name of the Module item (alphabetical)
created_at
- date the Module item was created
updated_at
- date the Module item was last edited
properties.weighting
- weighting of the Module item
properties.release_date
- date the item is set to be released
properties.module_field_3_1
- Sort by a core or custom field
sort_order
- defines the order in which the type is sorted asc - sort items in ascending order desc - sort items in descending order
collection
- default is 'false' - If you set it as collection: 'true' then any layout is suppressed.Data is accessible via {{context.exports.webapp_1.data}}. For Example, name would be: {{context.exports.webapp_1.data.result.items[0]['name']}}
use_search
- Allows the Module to be searched by keyword parameter in URL
use_adv_search
- Allows the Module to be filtered by core/custom field IDs in URL parameters
If you nest any more Module or WebApp layouts inside this Module Layout, they will inherit the type parameter. This means if you want to input a nested list layout, you may need to reset the type parameter back to list with type: 'list'
.
To get the most recently "released" item, you can use the sort_type
parameter to sort by properties.release_date
. You can alternatively use created_at
to sort by the Item you most recently added to the Admin.
`
`
Then just output one post- to get the first Item. To do this, set per_page
to 1
.
Use the sort_order
to control whether you get the first or last item. To get the latest Item by date, the date will have a higher value, so use 'desc'
(starts with highest number) rather then 'asc'
.
Field Name
Liquid Tag
Description
Item Name
{{ this['name'] }}
name of the Blog Post
Item Slug
{{ this['slug'] }}
item URL
Weighting
{{ this['weighting'] }}
weight of item, used for sorting
Release Date
{{ this['release_date'] }}
release date of the item
Expiry Date
{{ this['expiry_date'] }}
expiry date of the item
Enabled
{{ this['enabled'] }}
enable/disable the item
In general there are two main types of folder structure for Modules, though within that, there will be variation on the types of file available, so check each individual module.
The form directory stores the form layout for Module create/ edit Forms.
Most Siteglide published Modules will have a folder structure a little like this:
The private folder will exist, but will not be possible to pull using CLI or view in the Code Editor UI. It is for storing functional code which will be used by the Module behind the scenes.
Read more about Module Directory Structure on platformOS: https://documentation.platformos.com/developer-guide/platformos-workflow/directory-structure#modules
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:
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.
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.
Public - Do you want this Module to be visible within the marketplace?
You can also find these notes in the tooltips on each field.
Once you have clicked "Save" with the above fields populated, your module will be submitted to the Siteglide team for review.
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
In this example we’re going walk through, step by step, how to create a Module with a Custom UI that could either be used as a private module for your agency or shared publicly in the marketplace to deliver turnkey site solutions to your clients and more.
It is recommended that you download our example Custom UI Demo Module Repository from GitHub so that you have all of the code and asset files available at each step of this guide and can easily follow along to and have your module end up looking exactly the same.
:::hint{type="info"} If developing a Custom UI then you will have to supply all elements of the Module, including but not limited to tables, GraphQL, data processing etc. :::
Custom UI modules open up the ability for complete flexibiltiy within Siteglide Admin and allows for truly unique experiences for your customers.
A module with a Custom UI will securely load a page within a frame in Siteglide Admin. This page can be developed in any language that can run on a Siteglide site.
A 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.
To ensure that the Custom UI is only being accessed by logging in users of Siteglide Admin, we require authentication to be added to each page that will be used within the Custom UI. This is stored in the YAML of the pages and is as follows:
The response_headers
YML allows Siteglide Admin to view the content of the file when it is loaded. The authorization_policies
YML will run a check to ensure that the user has an active session within Siteglide Admin, if not then it will display an error page.
As well as the YAML, any links within your Custom UI has to include a Liquid tag to apply the authencation string on the link. For example if you are linking from your Custom UI's index page to the add new item page, your link would be as follows:
This include will create a hash onto the end of the URL that is then used in the above authorization policy to decide whether to show the page. If the include is missing then following the link will throw an error within Siteglide Admin.
You can also control access to certain areas of a page with the module_is_in_admin
function:
Once your module is created, you will need to tell Siteglide Admin to load your Custom UI. You will need to take the slug of the Custom UI's homepage and enter that into your Module Detials within Portal. When editing the details about your module, there is a field called "Custom UI Path", entering in the slug there will change the menu item for your module to then load your Custom UI instead of the default Siteglide module UI. In our example the path for our Custom UI homepage is module_72/module_iframe/index