MODULES
Building Custom Modules
Example: Theme Module
15min
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 create 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 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 create your folder structure 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 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 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 https //help siteglide com/en/article/templates getting started jbynlb/ 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 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 \<module name> module setup files 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 install process json { "1 0 0" "set homepage" } 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 view your staging module site 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 https //module siteglide theme demo staging oregon platform os com/ 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 submit module for approval 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 preparing to submit follow the checklist to confirm your theme module 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 \<module name> 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 here is what your project folder should now look like github 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 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 sending your module to siteglide 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 mailto\ api\@siteglide com ) as a collaborator for the github repository checkout the after submitting your module doc for more information updating & maintaining your module 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