Introduction

A collection of 3rd party links that our partners find useful when developing websites.

These sites are full of useful content, but any advice and examples published by 3rd party Sites is their own. We do not recommend any particular Front End library and encourage your agency to find the front-end tools and techniques that work for you.

platformOS Features

Siteglide is built upon platformOS, so their documentation is a fantastic resource for adding custom functionality to your Siteglide Website: https://documentation.platformos.com/

Liquid Documentation:

We also recommend the platformOS docs as the ultimate authority on using Liquid in your Siteglide Site. They include documentation on the original Liquid features and the additional features platformOS have added themselves: https://documentation.platformos.com/api-reference/liquid/introduction

Working with JSON

You'll come across JSON when you are working on Migrations and commonly when working with Liquid. It's a common language for storing data-structures, so if you output {{this}} in a Layout- we'll show you the JSON which stores the fields you need.

Using a third party JSON tool is useful to actually take the raw data and make it easy to read. Everyone has a different favourite tool, but you can see a third party comparison here to help you get started and find one: https://geekflare.com/json-online-tools/

Front End Resources (CSS & JavaScript)

General Front End Reference:

w3schools give a fantastic introduction to all web development topics, including reference guides and examples on HTML, JS, CSS, accessibility and more. https://www.w3schools.com/

MDN is another fantastic reference guide. It's useful if you need a little bit of extra depth and context. https://developer.mozilla.org/en-US/

Bootstrap is a useful library of Front-End components and features that we've made fully compatible with the Siteglide Design System because it is so widely used and familiar. If you have Design System enabled on your Page, there is no need to install https://getbootstrap.com/docs/4.5/getting-started/introduction/

Stack Overflow is fantastic for FAQs on every aspect of development. https://stackoverflow.com/

Code Pen is a great source of inspiration for all things CSS and JavaScript. It is full of fancinating community generated examples of everything from User-interfaces to animations:https://codepen.io/

JavaScript

Wes Bos has earned a reputation for teaching courses in JavaScript that are accessible to beginners and experts alike: https://wesbos.com/courses

We use the Glide.js plugin to power out Slider Module Layouts. Check out the docs to customise your Layouts and build new ones: https://glidejs.com/

Google Maps are used by the Events Module. Read the docs and customise here: https://developers.google.com/maps/documentation

FullCalendar.io is the plugin which powers the Calendar Layout of the Events Module. Read the docs and customise here: https://fullcalendar.io/

CSS

CSS tricks is a great resource for staying up to date on the latest in CSS and specialises in helping you tackle those issues that leave you scratching your head: https://css-tricks.com/

We're constantly putting together Tutorials and Guides to help you get started with each area of Siteglide.

Build Better AND Faster with SiteBuilder

Want to build from scratch?

Siteglide Command Line Interface (CLI)

Build and Manage Pages

Build and Manage Forms

Automate Processes with Automations

Use Our API to Integrate with Other Tools

Which Tools Should I Use to Work with Siteglide?

There are a few main ways to work with your Siteglide Site:

• Using the Siteglide Admin - Create an Account and use the User Interface to explore and build your Site. If you have any questions, use our live chat button to get help.

• Using the Siteglide CLI - Efficiently work directly with your Site's code on your own machine.

Which Coding Languages are used in Siteglide?

In the course of this Documentation, you will probably come across the following languages that we use in many of our features and examples:

• HTML - The standard Markup Language of the web. Learn more at MDN

• JavaScript - The standard client-side scripting language of the web. Learn more at MDN

• YAML - Used by Siteglide to store settings like page metadata, normally at the top of Liquid files.

• Liquid - Used by Siteglide for dynamic server-side rendering of HTML and other languages.

• GraphQL - Used by Siteglide to query the database and modify data. Often for beginners this will be tucked away inside our features, but learning it allows you to unlock more powerful possibilities.

Partner and 3rd Party Documentation

Siteglide works very closely with our partners at platformOS to provide you with all the benefits of a modern cloud-based infrastructure like AWS, while at the same time making your life easier so you can focus on delivering the best for your clients.

platformOS are behind a lot of the code used on Siteglide sites, developing everything from new Liquid filters on top of Liquid's open-source starting point and a fully functional GraphQL schema you can plug into for making database queries and mutating to modify data. We also work with a range of other open-source and 3rd party technologies to bring you our full suite of features.

In our documentation we will often direct you to the pOS documentation and those of other 3rd parties to help you dig deeper into what it is possible to build. platformOS have won awards for their innovative documentation and we will try not to re-invent the wheel when we cover the same topics as them, but instead hope to present topics like GraphQL with a more beginner-friendly slant.

Most platformOS features can be built on Siteglide - if you find one you like and are not sure if it's supported yet, we encourage you to let us know about it.

This guide will walk you through the process of creating a new site using Siteglide's admin area.

Step 1: Access the Dashboard

Once you're logged into the portal, you'll find yourself on the dashboard.

If you don't see a 'Create a Website' button (as per 2nd screenshot) please contact us via Live Chat to prove you're human and we'll get you setup!

Once you're account is approved you should see the Create a Website button:

If you already have 1 or more site you'll see options to create a site, manage existing sites, or manage your company:

Step 2: Choose Site Creation Method

You have the option to create a new site from scratch or use a Template.

If you're new to Siteglide or less technical, it's recommended to start with a template because they're built with SiteBuilder, a tool to help you rapidly build and customise websites:

The rest of this Quickstart guide will focus on building a Custom Site. Click the 'Build a Custom Site' button.

Step 3: Name your Custom Site

Give the site a name and it will automatically create the URL. You will need to ensure it's unique, if it turns red please amend by making it more unique. Then click Create Site.

Step 5: Manage Your New Site Once Ready

And that's it! You've successfully created a new site, you will need to wait for it to be ready to use:

You will receive an email when it's done but can also find it under the Sites area:

The Status will show as Trial and there will be a new blue button in the bottom bar that will likely say Sign up for Admin Access if you've not yet used it, otherwise it'll say Admin going forwards:

Next Steps:

Click through to Administer the Site and you'll end up on the Dashboard:

If you're a developer you'll likely want to set up our CLI:

Siteglide allows agencies to take control over code and data via API, CLI or UI. With the right blend of out-of-the-box tools and freedom to develop - without limits.

Where do I start?

If you're new to Siteglide we recommend starting from a pre-built Template that leverages our SiteBuilder tool: .

If you're looking for help with a site and not sure where to look you can check out our .

If you're already working on a site and you're code savvy we strongly recommend setting up our CLI so you can get the most from Siteglide via VSCode or your preferred IDE:

Looking for something else? Use the Search (top right) or navigate through the left menu which is organised to match the menu you will see in Siteglide.

Types of Articles

1. Quickstart: Bare essential guides with links to more detailed articles if you get stuck

2. About / Introduction: A brief overview of the topic

3. Step by Step Articles: How to Implement a Feature or Solve a Problem

4. Concept: Will take a feature and explain it in a little more depth

5. SiteBuilder: How to get setup and get the most from the SiteBuilder module

6. Reference: A brief reference guide to this feature for developers and anyone interested in code

7. File Structure: This will show you which folders and files are necessary and where to add them to your codebase. This will be presented in the format from which you would see it in Siteglide CLI

8. Troubleshooting: Find answers to common challenges

9. Go Further: This is where you'd find more detailed docs that help you really push the boundaries of all things web development

10. API: Endpoints and articles related to our API

11. Changelogs: Releases, Updates and any important changes to Siteglide

12. Billing/Account: Articles related to Billing, Payments and Subscriptions

13. Agencies: Articles specific to Digital Agency partners

Our Agency Success team here at Siteglide are dedicated to providing exceptional support and assistance to Digital Agencies and Siteglide Experts which ensures they are able to deliver the best solutions for their customers.

Please note: Website owners need to contact their Digital Agency for assistance, if you do not have one let us know and we'll recommend a reliable local agency or you can use our services team, .

Here we'll outline the ways in which we can help you and a few things that fall outside of our scope that we cannot assist with but we'll point you in the right direction whether it's via our Community or external resources.

How do I access Siteglide Support?

• Live Chat - Click the blue bubble in the bottom right hand corner of our services to speak with the team. Please leave as much information as possible by answering any questions that appear.

• Documentation - Access our growing library of Docs, FAQs, examples, videos and more, right here

• Discord Community - Have a question that needs a creative solution or a project scope you'd would like some suggestions on from other experienced partners?

Please note our working hours are 8am - 6pm GMT (London). We aim to answer queries outside these hours where possible.

What kind of Support do we offer?

We assist agencies and developers with the following types of issues/queries:

1. Platform Issues/Bugs: If you experience an issue with the core platform please report it to us and we'll help resolve it asap.

2. High Level Platform Capabilities: We're always here to help answer questions about the platform and confirm whether it has specific features/capabilities.

3. Account and Sales Questions: If you have a billing, account or sales related question we're always here to assist.

4. Troubleshooting: If you're struggling with a feature in Siteglide we'll point you in the right direction.

5. Technical Queries: Initial guidance but then you would need to use Sitegurus for assistance implementing Siteglide features.

What can we not assist with?

Community Support and Resources

We have a fantastic community of Siteglide Experts that can assist in various ways where we simply cannot (we want to stay focused on supporting you with the platform itself):

Go to a specific site in Portal and click the Modules tab. This will show all Modules in the Marketplace but it will not show Marketplace Templates because they cannot be installed onto an existing site).

You can filter to see which Modules are installed:

You can filter in the Name field if you're looking for a specific module:

Clicking a module will give you more information:

When ready just click install to install it to that site.

Next Steps:

June 25, 2024

We strive to support all recent versions of major browsers front-end JavaScript features that we deliver to your site, such as eCommerce or Forms.

For the sake of security and providing the best experience to the majority of customers, we do not support browsers that are no longer receiving security updates and represent a small minority of traffic.

Supported browser versions

• We support Edge v79 onwards per . We do not support Legacy Edge or Internet Explorer versions as they are .

• We support Chrome, Safari and Firefox on desktop platforms.

• We support the Android native browser on Android 4.4 and later.

• iOS and iPadOS version 10 and later. This also includes browser variants on iOS such as Chrome, Firefox, Brave etc.

• We respond to bug reports but do not proactively test other browsers.

If you have any system related issues in the browsers above then please don't hesitate to contact us for support.

Check and update your browser version

We recommend always using the latest browser version available to your operating system for the best support and security while using the internet. You can use the links below for your browser’s documentation to learn more about checking and updating your version:

For Safari, and Microsoft Edge browsers, this may depend on your device's operating system so check your OS is up to date as well.

Ready to build a Site?

Need to Invite or Manage Users?

Want to Install or Manage Modules?

Ready to Go Live or Need to Manage Domains?

Great news! You're ready to Go Live? Just follow these steps or contact us if you get stuck.

Step 1: Billing Setup

Head to the Go Live tab on the Site in the Siteglide Portal, if this is your first Site you'll likely see a message asking you to add your billing information:

Just click the link which will take you to the Billing Setup page, you just need to fill out the form:

More information on Billing Setup:

Step 2: Check Usage

The Subscription tab will show your current usage and recommend which plan you need, it'll only suggest the lowest plan that your Site currently fits into. We'd recommend considering picking a higher plan if you know usage is going to increase, this will help avoid paying overages:

Step 3: Go Live

On the Go Live tab there are a few options, firstly pick your currency then select the Plan (based on Step 2) and finally pick your preferred/closest Datacenter (this cannot be changed).

The button will not turn blue until you've selected a Plan:

It will then confirm the last 4 digits of the card that will be used and that you will be charged pro-rata for the remainder of the month based on the selected plan. When ready click Start Subscription. Please contact us if you are unsure about any of these steps, we cannot make changes once the site is Live.

Next Steps:

Ready to add your domain?

Want to Add a New Domain?

You can either Fully Delegate your DNS to Siteglide or manage it externally:

Click the 'Sites' button in the left hand menu in Portal to see your list of sites, then click the Name of the site you want to view the settings for:

This is where you manage the site including Users, Modules and the Subscription:

Details Fields:

• ID - Unique identifier for this site

• Site Name - Name of the site - this can be edited

• URL - The site's live or developmental URL - this can be edited (keeping the same format. e.g. Staging/Trial Sites = https://sitename.staging.oregon.platform-os.com/ and Production/Live Sites = https://sitename.prod01.oregon.platform-os.com/ )

• Status - This will be 'Trial', 'Trial Expired - Locked', 'Trial Expired - Redirected' or 'Live'.

• Datacenter - One of three datacenters that was picked when this site was created (London, Oregon, Sydney)

• Company (listed as Owner in 'Sites' area) - The Agency or Client that owns this site

• Create Date - The date that this site was created

• Created By - Email address of the user that created this site

• Latest Activity - The date that this site was last edited

• API Key - You can click here to reveal your key

• CLI Command - A shortcut to add this Site to CLI to begin working with, e.g:

siteglide-cli add staging --email richard.hendricks@siteglide.com --url https://my-new-site-pied-piper.staging.oregon.platform-os.com/

Note: Here, you can also see how long is left on your trial. When your trial has reached 0, an email will be sent out to the agency who owns this site, and this site will enter the expiry flow.

• You can extend this trial by clicking 'extend' next to the Status. Sites will automatically extend their trial when users visit this site's admin or connect to this site via CLI.

• After 14 days of this trial being locked and with no user extending this trial; a reminder email is sent out and this Site will now redirect to https://www.siteglide.com/ .

• After 13 days of this trial being redirected; another reminder email is sent to notify the agency owner that this Site will be deleted if no action is taken.

• After 1 day of this second email being sent out, this trial Site will be locked and greyed out in Siteglide.

• Within 24 hours of this site being greyed out, this Site will be fully deleted.

Using the buttons at the bottom, you can also 'View' this site, edit this Site's 'Admin', 'Save' any changes made to the name or URL, or 'Delete Site'.

You can view who has access to the site on the Users tab as well as invite existing users to the site.

You can only invite existing Siteglide users to Sites, you might be working with an external Siteglide Expert, you would give them access to this Site here.

Want to invite new Users to your account?

If you're looking to invite your own team to manage the site you would need to add them to your Account:

Account Details

You can manage your company profile and account settings here:

Account Users

This is also where you invite Account level users who have access to all sites:

Simply add a name and email address of a person you'd like to add to the Account:

Sites

This shows all the Sites directly under your account (this will not show any Sites in Client folders):

Launchpad

Launchpad shows you how much of Siteglide you've used and setup. It's a great way to ensure your team learns the platform:

Step 1: Add a Domain

Navigate to the Domains tab on the Site and click Add Domain:

Step 2: Choose Fully Delegated

Just click the Fully Delegated box:

Once you select Fully Delegated you need to type in your root domain (without www) and then decide if it's going to be your default domain (most likely):

You should also ensure 'Enable WWW Redirect is on unless you're adding a subdomain. Finally you can choose to add other DNS records but you can always do this later too. If you toggle to add them now you just add records and fill in the fields.

Step 3: Wait for it to process

Sit back and relax or go and make a coffee while the system does the work!

If you click the domain at this stage you'll just see the records you've added as Pending, there's nothing you can do at this stage so go grab that coffee!

Step 4: Change the Nameservers

You can refresh the page until you see the Status as 'Awaiting Propagation':

Then click into the domain and you'll see any records you've added plus the NS Records you need to add in your Domain Control Panel (GoDaddy etc):

To add more Records just click Edit Records and add new rows as required:

Step 5: Wait and Check it's Propagated

No matter how many times you've put sites live you'll no doubt be refreshing and questioning if it's worked from the moment you change the Nameservers!

You're looking for the Status to show as 'Live' in Siteglide but there are other ways to check progress listed below:

Typically you'll see some positive signals within minutes but you really do need to give it an hour or so (registrars will say 24-48 hours) before stepping in.

We recommend using the following tools to monitor propagation:

This is where you manage Account users, they would get access to all sites in your Portal

Invite Portal Users

To invite users to your Account you can only do this from the Users tab on your Account (your company name in the left menu):

You will not see the blue invite button on the Users page (left hand menu Users link):

If you click a user you can see what Sites they have access to and their User Role:

Find out more on Users and User Roles:

If you have a domain that is managed in GoDaddy or another registrar and would like to point it to a Siteglide website you can use our External Domain feature. This means that you can continue to manage your DNS through GoDaddy/other registrar.

Step 1: Add a Domain

Navigate to the Domains tab on the Site and click Add Domain:

Step 2: Choose External

Step 3: Enter Domain Details

Type in the root domain without www and you'll likely want to set it as the Default Domain and Enable WWW Redirect. Then click Add Domain:

Step 4: Add SSL Verification CNAME

Once your domain has finished creating in the system, it's status will change to "Ownership Verification Pending" which means it is now ready.

Add the generated CNAME record to in your DNS control panel to verify ownership, generate an SSL certificate and automatically apply it to your site during the next step.

GoDaddy example:

Once you have saved the record in your registrar, allow some time for propagation, check back and refresh the page.

Step 5: Add WWW CNAME Record

Once the verification CNAME record has propagated the WWW CNAME Record needs to be added in your DNS Control Panel (GoDaddy example):

The site will now be live via WWW (https://www.domain.com) but not via the root domain (https://domain.com). Complete Step 5 to fully setup the domain correctly. The domain should show as 'Live' under the Status column in Siteglide:

Step 5: Forward the Root/@ to the www (with SSL)

Most DNS Control Panels cannot correctly redirect the root traffic to the WWW over SSL so we recommend using an external service called Redirect.Pizza.

Just follow these steps to redirect your non-www to the www variant. The non-www is also sometimes called naked record or "apex" (screenshots below):

2. Add your source. This should be the domain without www. For instance, enter example.com as your source.

3. Set the destination to the variant with www. Example: www.example.com

4. Press "Create redirect"

6. The DNS change is made! It may take up to 24 hours before the DNS is fully propagated.

The following code example can be added to a Page Template and applied to the home/start page of a site to load a different start page for different domains added to the site.

This method does however remove some of the ease of editing for the client, as they will not be able to use Visual Editor to manage the pages that are setup this way. We'll look at adding a smoother point and click version to Admin later.

One use case for this approach would be where a client has a small chain of businesses that each have their own domain to target the area closest to them. Each of the sites are very small and the website structure is reasonably similar, and so it makes sense for the client to be able to manage all of them from the same Admin.

I'll now explain the code snippet above and how it works.

On the first line we get the current domain (context.location.host ) when the page loads and assign it so that it has a name of domain .

Next, we open a case to check the result of domain .

We then add an else at the end of the case to cover the default domain e.g. "if neither of these alternate domains are used, then do this" which acts somewhat like a catch all.

Finally, we close the case.

Using the above example, visitors will see unique page content to each domain when they visit. When they click on links on the page, they will continue to other pages on the site while keeping the same domain unless you hard code a full domain URL on a link. Please note that by adding more than one domain to a site, technically all content is accessible via all domains. Though you can effectively make content hidden from domains by not adding it to pages, it could still be accessed.

User Roles determine what users can see and do within Siteglide. Account owners have granular control over this and can set others as Admins or limit what they can do.

Manage Roles

You can then change or add additional Roles for that User:

Create a New User Role

To create a New Role just give it a name and select the granular controls they have access to:

You can also copy permissions from an existing role to save time:

See Roles Assigned to Users

You can see what Role a User has by clicking the Roles tab on a User:

Next Steps:

Simply fill in the form to add your card details to the Account. Please note this card will be used for ALL payments unless otherwise stated on the Go Live tab.

If you haven't previously setup Billing on Siteglide it will ask for your Company Name and Address:

If you already have a card on file with us it'll show the last 4 digits but you can replace this card with a new one:

The Subscription tab will show your Site Usage and what plan you're on or which plan we recommend if the site is not yet Live:

The Records Table shows a breakdown of all Records and how many have been deleted this month:

Want to Check what Plans are Available?

Ready to Go Live? Add a Payment Method

Looking for Invoices?

Sites can be automatically upgraded to the next available plan on the 1st of the following month if the cost of Extras exceeds the difference in cost to upgrade to the appropriate plan. Automatic upgrades by the system ensure that if usage increases on a site, the cheapest option is chosen and charged.

The default "Agency Global Preferences" is to not allow automatic upgrades. The "Site Preferences Override" has no override set and so will follow your Agency Preference. You can change this setting by following the information below.

Setting Up Your Automatic Upgrade Preferences

Site owners and agencies have granular control over automatic upgrades via Siteglide Portal. You can choose to control the setting either Globally for all of your sites, or individually for specific sites.

Please ensure you set this up to suit your billing preferences.

Agency Global Preferences

Within your in Portal, you can choose for the default setting to enable or disable automatic upgrades for all sites within your Agency and Clients.

The "Automatic Site Upgrades?" toggle can be set to two different states:

• Yes - Automatic upgrades are turned on for all sites unless you override at site level. Upgrades will take place if it is cheaper than paying Extras

• No - Automatic upgrades are turned off for all sites unless you override at site level. No upgrades will take place unless you action them yourself

Once you have chosen a state, make sure to save.

Note: This preference can be overridden by a selected state applied at the site level.

Site Preferences Override

Above the peak usage table, you'll see the current state for this site and an option to change this.

Click "Change" to open a pop up modal, where you'll be shown the current state for this site and an option to override Global Preferences in two ways.

To override, tick the "Override?" checkbox and select the appropriate state you would like to apply as an override.

To remove an override, untick the "Override?" checkbox.

An override can be set to either of the following states:

• Automatic - Automatic upgrades are turned on for this site only. Upgrades will take place if it is cheaper than paying Extras

• Manual - Automatic upgrades are turned off for this site only. No upgrades will take place unless you action them yourself

Once you have chosen an override state, make sure you click save.

The Siteglide Marketplace has a variety of useful Modules, Templates, Themes and Integrations.

Core Modules

Some of which have been built by Siteglide so that you can pick and choose which to install onto each site and reduce clutter/usage if they're not required. These are called Core Modules and are denoted by the 'by Siteglide' text under each title:

Find out more about the Core Modules:

Community Modules, Templates, Themes & Integrations

Other Modules, Templates, Themes and Integrations have been built by the Siteglide Community of Experts including our services team, Sitegurus.

Sitegurus have built SiteBuilder, a tool to speed up development of web projects while ensuring best practice and quality. Check out the Marketplace Templates that leverage SiteBuilder:

The Clients feature in Portal is only available to Agencies and gives you an extra level of management allowing you to group multiple Sites under one Client and control who can see it.

Create Client Companies

You can create unlimited Clients and Invite Users who would then only have access to that Client area and any Sites linked to it.

You can access this from the left hand side menu but also from within your Agency Account.

Invite & Manager Client Users

If you invite a User within a Client they only have access to that Client Company and any Sites within it. It's very useful when a customer has multiple Sites but it's also a good way to keep Siteglide organised and clutter free!

Create & Manage Client Sites

The Sites tab shows the Sites linked to this Client Company. Create a new Site here to ensure it can only be seen by the right Clients (your Agency users can see ALL sites):

You can view your previous and upcoming invoices on the Invoices page:

This is where you can contact us about an issue by logging a Support Ticket:

Just give it a title, select which site it relates to (if applicable) and please provide as much information as you can:

An Agency only feature is being able to make copies of existing sites either to a blank Staging or to an existing Site (can be a Production Site):

To copy to a new Staging Site click the first radio button and then choose the Site Owner (your Agency or a Client folder) and give the Site a Name/URL:

To copy to an existing site (Trial or Production) click the second radio button and then choose the Site from the dropdown:

​Whitelabelling enables your Agency to re-brand the Siteglide portal by replacing our logo with your own. Re-branding the platform in this way means you are able to provide a more consistent, branded and streamlined service to your clients and maintain a single point of contact with them.

Over time we will continue increasing coverage of the whitelabling capabilities to include things like domain name, among others.

Admin Logo

To re-brand your Portal and Admin, head over to the Agency Details page, upload your logo and enable "whitelabelling".

Login

Below is an Endpoint and example snippets of code you can use to enable your Clients to login to Admin directly from your own Agency website.

You'll need the code below as a minimum. You can then add your own HTML/CSS/JS designs and branding on top.

HTML and JavaScript

```liquidEmail Password

WebApps in Siteglide rely on 3 different files to work correctly.

1. JSON Structure - Used by Siteglide Admin and front-end to define structure of the WebApp with user-friendly names, and other UI metadata.

2. Schema - Used to define the database structure itself

3. Form Configuration - Used when submitting WebApp items front-end

There are 2 ways to create/edit a WebApp via CLI.

1. Safest - Create/Edit the JSON structure file (marketplace_builder/views/partials/tables/webapps/99.liquid), and then in Siteglide Admin simply click 'Save' in the Table Builder view. This will generate a matching Form Configuration and Schema file.

2. Most flexible - Create/Edit each of the 3 files manually. However, this relies on you keeping all 3 files in sync.

JSON Structure

This is used by Siteglide Admin to output WebApp field data with user-friendly names and other UI options (order, field type, etc.)

Location: marketplace_builder/views/partials/tables/webapps/99.liquid

Contents:

{
	"id": 99,
	"type": "webapp",
	"name": "My CLI WebApp",
	"slug": "my-cli-webapp",
	"detail": true,
	"detail_template": "templates/1",
	"detail_default_layout": "default",
	"sz": false,
	"sz_updated": true,
	"sz_display_type": "404",
	"system_fields": {
		"name": {
			"type": "string",
			"editable": true,
			"hidden": false,
			"live": true,
			"order": 0,
			"required": false
		},
		"slug": {
			"type": "string",
			"editable": true,
			"hidden": false,
			"live": true,
			"order": 0,
			"required": false
		},
		"weighting": {
			"type": "integer",
			"editable": true,
			"hidden": false,
			"live": true,
			"order": 0,
			"required": false
		},
		"release_date": {
			"type": "integer",
			"editable": true,
			"hidden": false,
			"live": true,
			"order": 0,
			"required": false
		},
		"expiry_date": {
			"type": "integer",
			"editable": true,
			"hidden": false,
			"live": true,
			"order": 0,
			"required": false
		},
		"enabled": {
			"type": "boolean",
			"editable": true,
			"hidden": false,
			"live": true,
			"order": 0,
			"required": false
		},
		"category_array": {
			"type": "array",
			"editable": true,
			"hidden": false,
			"live": true,
			"order": 0,
			"required": false
		},
		"meta_title": {
			"type": "string",
			"editable": true,
			"hidden": false,
			"live": true,
			"order": 0,
			"required": false
		},
		"meta_desc": {
			"type": "string",
			"editable": true,
			"hidden": false,
			"live": true,
			"order": 0,
			"required": false
		},
		"og_title": {
			"type": "string",
			"editable": true,
			"hidden": false,
			"live": true,
			"order": 0,
			"required": false
		},
		"og_desc": {
			"type": "string",
			"editable": true,
			"hidden": false,
			"live": true,
			"order": 0,
			"required": false
		},
		"og_type": {
			"type": "string",
			"editable": true,
			"hidden": false,
			"live": true,
			"order": 0,
			"required": false
		},
		"twitter_type": {
			"type": "string",
			"editable": true,
			"hidden": false,
			"live": true,
			"order": 0,
			"required": false
		},
		"secure_zone_array": {
			"type": "array",
			"editable": true,
			"hidden": false,
			"live": true,
			"order": 0,
			"required": false
		},
		"location": {
			"type": "geojson",
			"editable": true,
			"hidden": false,
			"live": true,
			"order": 0,
			"required": false
		},
		"address": {
			"type": "string",
			"editable": true,
			"hidden": false,
			"live": true,
			"order": 0,
			"required": false
		},
		"og_image": {
			"type": "string",
			"editable": true,
			"hidden": false,
			"live": true,
			"order": 0,
			"required": false
		},
		"og_url": {
			"type": "string",
			"editable": true,
			"hidden": false,
			"live": true,
			"order": 0,
			"required": false
		}
	},
	"custom_fields": {
		"webapp_field_99_1": {
			"name": "Custom Field",
			"type": "input_text",
			"live": true,
			"order": 1,
			"editable": true,
			"hidden": false,
			"required": false
		}
	},
	"automations": {},
	"install_to_site": true,
	"use_standard_fields": true
}

Please see the Field Types document for all the relevant types.

Schema File

This is what defines the database table structure, and how data will be stored.

Location: marketplace_builder/custom_model_types/webapps/webapp_99.yml

Contents:

---
name: webapp_99
properties:
- name: name
  type: string
- name: slug
  type: string
- name: weighting
  type: integer
- name: release_date
  type: integer
- name: expiry_date
  type: integer
- name: enabled
  type: boolean
- name: category_array
  type: array
- name: meta_title
  type: text
- name: meta_desc
  type: text
- name: og_title
  type: text
- name: og_desc
  type: text
- name: og_image
  type: text
- name: og_type
  type: string
- name: twitter_type
  type: string
- name: full_slug
  type: string
- name: secure_zone_array
  type: array
- name: location
  type: geojson
- name: address
  type: text
- name: webapp_field_99_1
  attribute_type: string
---

The above are all the default fields that are needed, the last field is an example of a standard text field. Please see the Field Types document for all the relevant types.

Form Configuration

This is used when submitting a WebApp item front-end. This file was also previously used to output WebApp structure data in Siteglide Admin, but that is now the job of the JSON structure file.

Location: marketplace_builder/form_configurations/webapps/webapp_99.liquid

Contents:

---
name: webapp_99
resource: webapp_99
resource_owner: anyone
configuration:
  properties:
    webapp_name:
      name: webapp_name
      value: 'My CLI WebApp'
      property_options:
        virtual: true
    webapp_slug:
      name: webapp_slug
      value: 'my-cli-webapp'
      property_options:
        virtual: true
    webapp_detail:
      name: webapp_detail
      value: true
      property_options:
        virtual: true
    webapp_detail_template:
      name: webapp_detail_template
      value: 'templates/1'
      property_options:
        virtual: true
    webapp_detail_default_layout:
      name: webapp_detail_default_layout
      value: 'default'
      property_options:
        virtual: true
    webapp_sz:
      name: webapp_sz
      value: false
      property_options:
        virtual: true
    webapp_sz_updated:
      name: webapp_sz_updated
      value: false
      property_options:
        virtual: true
    webapp_sz_display_type:
      name: webapp_sz_display_type
      value: '404'
      property_options:
        virtual: true
    name:
      name: name
      type: string
    slug:
      name: slug
      type: string
    weighting:
      name: weighting
      type: integer
    release_date:
      name: release_date
      type: integer
    expiry_date:
      name: expiry_date
      type: integer
    enabled:
      name: enabled
      type: boolean
    category_array:
      name: category_array
      type: array
    meta_title:
      name: meta_title
      type: string
    meta_desc:
      name: meta_desc
      type: string
    og_title:
      name: og_title
      type: string
    og_desc:
      name: og_desc
      type: string
    og_image:
      name: og_image
      type: string
    og_type:
      name: og_type
      type: string
    twitter_type:
      name: twitter_type
      type: string
    full_slug:
      name: full_slug
      type: string
    secure_zone_array:
      name: secure_zone_array
      type: array
    location:
      name: location
      type: geojson
    address:
      name: address
      type: string
    webapp_field_99_1:
      name: "Custom Field"
      type: input_text
      live: true
      hidden: false
      order: 1
      editable: true
      required: false
      validation: {}
---

{%- capture form_layout -%}layouts/webapps/webapp_99/form/{{_layout}}{%- endcapture -%}
{%- include form_layout -%}

After both the above files are synced you will then need to refresh Siteglide Admin and your WebApp will appear under WebApps in the sites left hand menu

Layouts

If you need layouts for your WebApp, these will be saved to:

marketplace_builder/views/partials/layouts/webapps/webapp_99/detail/default.liquid

marketplace_builder/views/partials/layouts/webapps/webapp_99/list/default.liquid

Both files contain the following layout by default: <p>{{this['name']}}</p>

The pOS documentation covers Liquid comprehensibly and includes Liquid functionality specific to the pOS Platform and Siteglide.

Siteglide runs on platformOS and we use their implementation of Liquid which adds a large range of useful functionality.

The best place to start learning is their Introduction to Liquid documentation, which will explain the different types of Liquid syntax. From there, you can find more helpful documentation on the Liquid topic you are interested in.

Siteglide CLI (Command Line Interface) is a tool that enables you to work on your project from your local IDE or Code Editor; it has similar behaviours to FTP (File Transfer Protocol), in that you can sync up and pull down changes from your website.

Who is it for?

Developers will be at home with the Siteglide CLI. It allows them to work faster than they can using the User Interface of the website. It also allows them to access the full suite of time-saving extensions and search tools in IDEs like VSCode and Atom.

But it's not just for Developers! Designers, SEO specialists and Agency Leaders may also find benefits to learning and using Siteglide CLI - allowing them to see an overview over their entire project and quickly find the files they're looking for.

How to Navigate Around?

Check the "File Structure" in each documentation topic, and this will help you find your way around the folders and files.

Benefits of CLI over FTP:

Validation

With CLI, we can validate code sent to the site. This is especially useful if you are syncing Liquid or GraphQL code where there are fewer 3rd party tools for linting. If there is a problem we can pick up automatically- the sync will fail and an error message will try to help you find the problem.

Version Control

With Siteglide CLI we can keep track of the Code pushed to the Site from Admin and from local machines and make sure the Site always contains the most up to date pushes. It gives us scope to improve this functionality in the future.

Developer Tools

Other CLI commands like siteglide-cli graphql and siteglide-cli logs provide developers with advanced tools that would not be available with an FTP.

Ready to Start Using CLI?

Not Sure if You've Set Up Siteglide CLI Already?

In a Command Line, in any directory, type in:

siteglide-cli -v

If you already have siteglide-cli installed globally, this will tell you which version you have installed.

You can find out which is the latest version here: https://www.npmjs.com/package/@siteglide/siteglide-cli

Have You Installed the Dependencies?

The CLI is distributed via Node Package Manager (NPM) and so you will need NodeJS installed on your machine. The easiest way to get this is to visit https://nodejs.org/ and download the LTS version as this has better support.

Open the download and follow the wizard with the default options to finish install.

Have you Installed the CLI Globally on your Machine?

You can use the following to install Siteglide CLI in any directory. The -g flag instructs your machine to make this command available in any directory (globally)- so you only need to do this on your machine once.

npm i -g @siteglide/siteglide-cli

When an update is released for the CLI, you can use the same command as above to install the updated version. Please note that the flags for commands below are not available on all versions of the CLI, updating to the latest version will allow you to use all of them.

Issues Installing on Windows?

The following video will give you a complete walkthrough guide for setting up Siteglide CLI on a Windows machine. Feel free to skip ahead to the parts you find the most useful.

Issues Installing on a Mac?

The following video will give you a complete walkthrough guide for setting up Siteglide CLI on a Mac. Feel free to skip ahead to the parts you find the most useful.

The steps followed in the video can be found here. If you are using zsh as your shell then the commands here will have to be run against the ~/.zshrc file, not ~/.profile. ZSH is the default for Macs since macOS Catalina, to find out which shell you are using you can run echo ${SHELL} in terminal. If the ~/.profile or ~/.zshrc files do not already exist then you may need to create them first before running the export PATH command

Struggling to Connect to a Site?

Read our in-depth guide:

Debug Mode

Sometimes Siteglide support may ask you to run the CLI in "debug mode". This provides more output into your terminal so that we can use it to aid in supporting you. To do this, you need to prefix the command you are running with some extra information. This prefix differs slightly on macOS, Linux and Windows, for example if you were to want to sync to a site with debug mode on:

DEBUG=true siteglide-cli sync production

DEBUG=true siteglide-cli sync production

set DEBUG=true && siteglide-cli sync production

$env:DEBUG='true'; siteglide-cli sync production

Note, for macOS and Linux, debugging will be turned on for that one command that you prefix. For Windows, debugging will be turned on for as long as Command Prompt or Powershell is open. Closing Command Prompt or Powershell and re-opening it will turn debug mode off.

Step 1: Install the Siteglide CLI

The Siteglide CLI can be installed from NPM using:

npm i -g @siteglide/siteglide-cli

Step 2: Connect to a Site

Setup a local folder and use the site specific command to connect directly to your site (you can find this on the site details page in Portal - more info):

siteglide-cli add --email me@mydomain.com --url https://my_great_site.com

Step 3: Start Building!

You should now be ready to start work, you'll likely want to pull down the files from the server:

siteglide-cli pull <env>

Check out our Reference article for a full list of useful Commands:

Usage-based Billing

The Subscriptions tab shows you exactly what each site uses broken down into high-level types of infrastructure usage and then down to specific Siteglide features to help show more value to clients.

For example, you can see the total number of Units but the real value is seeing that this is made up of CRM Contacts, Form Cases, WebApp items, Module Items, Products and much more.

Note: External API calls are unlikely to be used for many sites if you're not working on platformOS directly via CLI.

When comparing the cost of the various different tools required to achieve the same result and then trying to somehow connect them all together you can show huge savings to clients both in terms of cost and time.

Plans and Extras

You can see the individual Site Plan pricing on the Plans page:

Extras are charged pro-rata based on the plan price. Simply divide the Plan Price by the Units included you get the Unit Rate that you will be charged if you exceed the limit.

We replaced the old, more costly Overages with Extras. If your site subscription tab shows a 'Legacy' plan please refer to old old Overages pricing or speak to the team about switching to one of our new plans!

How our usage-based billing works:

1. Storage, Records, Domains and Client Admin Users do not reduce unless deleted.

2. Emails, API Calls and Bandwidth renew each month.

3. You are billed based on the peak usage each calendar month.

4. Deleted items count towards peak usage for that month but do not count in subsequent months.

5. Once you hit 70% usage of any metric it will be marked as orange as a warning.

6. Once you hit 100% usage of any metric you will start incurring Extras.

7. If you have Automatic Upgrades turned on and the cost of Extras exceeds the difference in cost to upgrade to the appropriate plan the site will automatically be upgraded on the 1st of the following month.

8. You can manually upgrade or downgrade to any plan once per month but if the new plan doesn't cover the usage you will be charged overages.

9. We do not downgrade automatically as we do not know what usage will be required in a given month and assume most sites increase in usage as the business grows and the site becomes more successful/popular.

Subscription Changes

To give you full use of the Siteglide platform we simply charge you based on your usage which can change over time and likely increase as you help your clients grow.

Please ensure you're aware of how subscription changes work before going live:

1. We monitor usage and provide the Subscriptions tab for each site to show if you are close to exceeding or exceeding the usage available on the current plan. Find out more about the Subscriptions Area in Portal.

2. We calculate usage at midnight on the 1st of each month for the whole of the previous month. If you have Automatic Upgrades turned on and exceed any usage limits we will apply the cheapest option at the time which will either be to charge Extras or Upgrade the plan. If you have Automatic Upgrades turned off we will only charge the Extras.

3. Extras are charged in blocks as a one-off charge for excess usage in that billing period. Typically you could use double the allowance of one usage metric before it’s cheaper to upgrade to the next plan.

4. For Monthly Upgrades the new plan will be applied immediately both for the new month and retrospectively for the previous month (to avoid paying more costly overages). We will charge for the new month and the increase between the new and previous plan. This will only be done to save higher overage costs, we will always apply the cheapest option.

5. Annual Upgrades will start a new 12 month subscription crediting the balance of the previous subscription prior to payment (e.g. $250 - $63 (6 months remaining of Starter plan).

6. For Sites on Connect Billing (deprecated) we will continue to pick the cheapest option based on our fees not what you charge your customer as this can vary (you could manually upgrade them to a higher plan if preferred).

7. If your site usage decreases and you believe it will not increase again then you might wish to Downgrade to a lower plan. Simply press Downgrade on the Subscriptions page, pick your chosen plan and request the Downgrade. The Downgrade will not take effect until the end of the current billing period. Note: You may prefer not to do this on Connect Billing to avoid lots of changes.

8. If you wish to cancel a site we recommend first discussing any issues with our Success team but alternatively you can delete the site via the portal. Please note deleting a site takes effect immediately and all data will be irretrievably lost. All payments are non-refundable so we recommend making full use of the current billing cycle before deleting the site (any remaining time will be forfeited).

9. Please see our full Payment Terms and Payment Failure Process in our End User Licence Agreement (sections 7 and 8).

Siteglide is built for Digital Agencies by Agency owners that hit too many limitations with the platforms available. While anyone can use Siteglide it's designed with agencies in mind.

Approved Siteglide Agencies get various benefits and extra features to help them deliver the best results to end customers.

Explore the Agency Account features:

Whitelabel your Account:

Manage Client Accounts:

Make copies of Sites:

If you are an approved Siteglide Agency you will have additional features accessible from the tabs across the top:

Community Expert Details

The Community Expert Details tab is where you can brand Siteglide to your Agency and create a page on the Experts area so users in need of your services can find you:

Read more about Whitelabelling Siteglide to your Agency:

Marketplace Payment Details

The Marketplace Payment Details tab allows you to take payments for any Modules you sell in the Marketplace. You would need to use Stripe to take payments and insert your secret key:

Partner Programme

The Partner Programme tab provides more information on how you can partner with us:

Affiliate Programme

The Affiliate Programme tab lets you setup and control the affiliate commission for referring new users to Siteglide:

Once you've installed the CLI you should be ready to learn how to set up a new project folder and connect it to a specific Siteglide Site. You'll need to follow these steps every time you want to use the CLI to work on a new site, so over time these will become very familiar.

Step 1) Create a Project Folder on Your Machine

Your project folder will contain all of your Site's files.

Use Finder on Mac, or Windows Explorer to create this new empty folder, and give it a similar name to your site so you can find it again. We recommend creating this folder inside a sensible organisation structure, for example you may have a single folder which contains all of your project folders, or you might organise by customer.

Step 2) Open Your Project Folder in a Text Editor

In order for a CLI tool's ability to deploy and pull code from a Site to be useful, we need to have a good place to look at and change that code.

While you are free to use any kind of terminal or any kind of Text Editor, we'll use VSCode for these steps- one major benefit is that its integrated terminal allows you to easily manage your project in one place. It also comes with lots of useful extensions.

If you do not already have a text editor installed, you can browse for one or install VSCode here: https://code.visualstudio.com/download

You can then open your project folder in the Text Editor:

Step 3) Open the Integrated Terminal

The terminal will appear in its own panel, by default below the code. In VSCode this will automatically change directory to your project folder (if not, do this manually)!

Step 4) Make Sure Your Email Address is Listed in the Site Users

Open up the Siteglide Portal and find your Site in the Sites option in the left-hand-side menu.

In the Users tab, make sure your user's email address is listed. If not, invite yourself (as an existing user) to the Site.

Step 5) Copy the Env Command with Pre-Filled Variables

In the Details tab, near the bottom of the Site information, find the CLI Command and copy it.

Step 6) Run the Env Command to Set Up a Connection Between your Project Folder and a Site

Paste the command into your integrated terminal.

When prompted, enter the Siteglide Password associated with the email address in the command.

This command creates what we call an envrionment. Think of it as a connection between a project and a Site. Sometimes you may maintain a staging Site and a live Site for the same project and you might create both a staging and a production environment.

You will need to remember the name of your environment in order to use any other Siteglide-CLI commands, but if you forget, there will be a .siteglide-config file in the root of your project folder which will list them:

Step 7) Run an Initial Pull of the Site to Pull Down the Existing Code Base

You're now set up with Siteglide-CLI for this Site! The obvious first move would be to pull the existing Site's files down to the Site, using the following command in the terminal:

siteglide-cli pull staging

This will create your directory structure and populate it with your site's files and assets (images will not be pulled due to their size - see export command).

Next

You now know how to set up Siteglide CLI on a Site! You can follow these steps every time you want to work on a new Site.

Next, check the Reference for how to:

• Deploy all your code to the site

• Sync individual files to the site as you save them

• And remember how to pull all the code down to your project folder

Comfortable with code?

We recommend using our CLI (Command Line Interface).

New to Command Line Interfaces?

You can go further, faster with CLI but it's not for everyone, we recommend reading the following article before deciding:

Already installed CLI?

Useful links once CLI is installed:

New to Liquid markup?

Liquid is a templating language (created by Shopify) that helps you build out Siteglide functionality.

Looking for a specific tag/function?

Check out our Reference guide:

Tutorials

CLI Commands

These commands should be run from within the project folder. Commands follow the format of siteglide-cli <command> <env> <flags> , so for example if you would like to view the logs of your production environment in "quiet mode", you would run:

siteglide-cli logs production -q

Please note that some commands may fail if you run them in your users home directory. We recommend a folder structure such as siteglide/ and then give each project/site it's own folder.

Add

The first time you use the CLI with a project on your device, you will need to create an environment. This is essentially a config file that authorises your connection.

siteglide-cli add <env> --email me@mydomain.com --url https://my_great_site.com

You must use the email of your Siteglide partner account to replace me@mydomain.com and the development domain of the website you are connecting with to replace https://my_great_site.com

After your site goes live, you will only be able to add the development domain to an environment, not your main user-facing domain.

Sync

siteglide-cli sync <env>

This command will setup a watcher that will automatically sync file saves and deletions when that action happens on your machine. To stop the sync running, enter use the shortcut control + c in your terminal.

Flags:

-l: Turns on the live reload server. This enables automatic browser reloading of a page when a file is saved in your IDE.

Logs

siteglide-cli logs <env>

This command will output the last 20 logs and then a live list of logs from your site. Logs are written by using the log liquid code, for example: `

. To stop the logs running, enter use the shortcutcontrol + c` in your terminal

Flags: -f : Filter log types -q : Quiet mode

Version

siteglide-cli -v

Check the current version of Siteglide CLI you are running. See the Siteglide CLI changelog to find the latest version number. If you need to update, see the "Installing & Updating" command section above.

Help

siteglide-cli help

Generates a list of valid Siteglide CLI commands available to you.

GraphQL

Deprecated - Please see the GUI command below

GUI

siteglide-cli gui <env>

This command will open up the GraphiQL and Liquid Evaluator editors locally. This will let you run Graph queries and mutations to test them out before creating them within your site. Also good for quickly getting data out of the database to check.

The Liquid evaluator tool lets you quickly test Liquid from the CLI, without having to create and save a page in Siteglide Admin.

To stop the GUI command running, enter use the shortcut control + c in your terminal

Flags: -o: Automatically open GraphiQL in default browser

Pull

siteglide-cli pull <env>

This will pull down all files from the site in to a folder named marketplace_builder within your current directory. During this process it will also overwrite any local versions of files if they already exist. If you have made any changes locally that you have not synced they WILL be overwritten.

Flags:

-i: Ignore assets such as CSS and JS as part of the pull.

-m: Provide the name of a module to download. Note that this will only download that module and not the site as well. This will only download the public folder within the module, if the module only contains a private folder then nothing will be downloaded.

Note: Assets such as images and videos are not downloaded as part of CLI Pull

Init

siteglide-cli init

This will create a blank folder structure within the folder you run the command, which includes all folders that are automatically created for you when making a new website on Siteglide. If these folders already exist, you will receive an error and so it will not overwrite existing files.

Deploy

siteglide-cli deploy <env>

If you have made a lot of changes in your codebase, then you can use deploy to re-send all files to your site at once. Deploy is a single command that will create a .zip file of your site and then upload that to your website.

Flags:

-w : With assets, also deploys your sites assets folder, supports total assets of up to 5GB.

Export

siteglide-cli export <env>

Export is very similar to Pull, but it will also grab all data. This command will first grab all data from the site and export it into a data.json file, then it will run a pull to grab your code base.

Flags: -w : With assets, also download asset files from your instance such as images and PDFs.

--csv: Export the data files as CSV instead of JSON. Please note that these CSV's are currently not compatible with the ones that are exported/imported from Siteglide Admin

-a: Only export assets and not the sites codebase. This by default will only export code related assets (CSS/JS etc) within the /assets folder. It can be mixed with -w above to export all assets

Migrate

siteglide-cli migrate <env> --url <existing url>

Download and migrate an existing site to Siteglide using our site import tool. This tool will scrape the existing site, download all of the publicly accessible pages and assets, compress CSS/JS/images. The migrate command will also convert any existing forms (using the <form> tag) to a "form to email" in Siteglide. When filled in, this will email the user who triggered the CLI migration with an autoresponder. These forms can then optionally be updated at a later date within Siteglide Admin.

Note: If you are using a Mac, running migrate in your “home” folder may fail. Please move into a different folder in terminal and then try again.

Flags:

--url: Existing sites URL, usually the homepage. This flag is mandatory

-n: No Optimization, skips the CSS/JS and Image optimization

-m: A number to set the level of recursion that the scraper will search through the site. For example setting -m 1 will only follow 1 link deep from the entry page

-i: A string to send to the scraper that if found in the URL it will ignore downloading that page. For example if your blog posts are links such as site.com/post/post-name and you wanted to ignore them, you could use the flag -i /post/ This flag can be used multiple time such as -i /blog -i /posts/

List

siteglide-cli list

Output a list of environments you have previously added and their relative URLs for the current folder.

Modules

siteglide-cli modules <env>

Provides a list of modules installed onto the instance. These names can then be used in the pull command to download the contents of that module.

How to use Liquid For Loops and Indexing to handle arrays. Also, how to use a key to access key maps, using categories as an example.

Prerequisites:

This Article is the second in a series on using Dot Notation in Siteglide. We strongly recommend reading the Article below first:

Introduction

If you're using dot notation, you'll probably come across arrays and maps. The syntax for dealing with them is slightly different, but this actually makes them more powerful when you're building complex Layouts.

The examples below focus mainly on Categories because they are a good example of arrays and maps.

Arrays

An array is a group or list of data. A key might have a single value, or an array of values.

In Siteglide for example, each WebApp item for example has a field called category_array which stores a list of the IDs of every Category assigned to that item. The more categories an item belongs to, the longer the array. E.g. { "category_array":["98479", "111111"] }

If you try to use standard dot notation as we practised in the previous Article, you will be able to output the array as it is using the key category_array and the liquid {{this.category_array}}:

["98479", "111111"]

However, there aren't many places where this would actually be helpful. It would probably be more useful to do one of the following:

• Access one of the Array items by its Index

• Loop over the array Items

• Find the length of the array (how many items are there?)

Accessing an Array by its Index

Arrays have an index, which means they are numbered. In Siteglide (and in JavaScript) Arrays are zero-indexed, meaning the first item has the index of 0 while the second item has the index of 1.

We can access the first value in the category_array by its index using the following Liquid: {{this.category_array[0]}}outputs 98479

Note that straight after the key, we give the index number of the value we want in square brackets. If the array contained objects, you could go a step further and access one of their properties with a dot after the square brackets.

Looping the Array to Access all Values in it

We can access all values in the Array using a Liquid For Loop:

This outputs:

Finding the Length of an Array

You can find the length of an array using a Liquid filter: {{this.category_array | size}} outputs: 2

Maps

As well as arrays, you might come across a map of data. Here is an example which can be tried on any Siteglide Starter Site using the Liquid: {{context.exports.categories}}

It outputs something like this (but I've shortened it here!):

A map is used to store data when you know the ID of an item and want to fetch it using it's ID as a key. In Siteglide we use them for performance reasons. You can tell this is a map, because the key items contains several comma-separated objects instead of a single value. Each of these has a key representing an ID, instead of the name of a property.

Let's say you have the ID of a category, but you want to display the Category's name: {{context.exports.categories.items["98490"].name}}

This outputs: Women

This sounds odd, but it's the name of the eCommerce Category we wanted! You can achieve the same if you have the ID stored as a variable:

Looping over a Map

You can loop over all keys in a key map using a Liquid FOR loop. Inside the loop, each key-value pair is treated as an array with the key being the first item in the array and the value being the second and last value in the array.

In this example, we'll loop over all Categories in context.exports.categories.data and see what data is available to output:

Using what you've learned so far

Here's a challenge you can try.

Can you create a WebApp with Categories and in your Layout output a list of the Category names that belong to the item?

Step 1) Create a WebApp and assign more than one Category to each of the Items. Step 2) In the Layout, access the this object. Step 3) Use your Understanding of arrays to loop through every category belonging to the item. Step 4) Use your understanding of maps to find the name of each category in the Loop and output it.

Next Article

Next, we'll look at how you can use dot-notation to work with WebApp collections: Using WebApp Collections

This Liquid is useful when you are accessing a WebApp 'collection', creating a Categories layout, using a custom GraphQL query and more.

Prerequisites

• Choose your favourite third party tool for parsing and formatting JSON. Everyone has a different favourite tool, but you can see a third party comparison here to help you get started and find one: We'll look at this again below in "Using a Third Party Tool to Visualise Objects"

Introduction

Understanding dot notation is a really useful skill for Developers who are trying to get the most out of Siteglide and the platformOS technology it runs on. This Getting Started Article will cover:

• What is dot notation?

• How to find a property of an Object

• How to chain dot-notation

• The Data Tree

• Visualising the Data Tree

You will come across the following terms which might be new:

• Object

• Array

• Key-value Pairs

• properties

• Curly Bracket

This Article is intended to be the starting point for a Series of Articles involving dot notation.

What is dot notation?

Normally when you're accessing data on Siteglide, you simply want to access a single value. For example, on a Starter Site (using the WebApp installed by default, Gallery), you might need to output a Title on your Layout: {{this.Title}}

In this example, this outputs a String: The Latest Music

You could use this syntax from memory, or by referring to the Docs, but you're actually already using dot notation. The syntax above takes a variable this which returns an object. .Title is dot notation which specifies that the Developer wants to access the Title which is a property of this.

Note: Sometimes you may see something like this: {{this['Title']}} This is the exactly same thing, except this alternative syntax also allows you to add spaces in field names. We'll cover this in more detail in the next Article.

Key Value Pairs

Another important piece of terminology is the concept of a Key-Value Pair.

A key is a place where data is stored; a value is the data itself.

In the previous example, this and Title are both keys. The key Titlehas the value The Latest Music.

Chaining

You can chain dot notation. The following example will output the first name of the User currently signed in to a Secure Zone: {{context.current_user.first_name}}

This accesses the context object, then accesses its current_user property and finally accesses the id property of current_user. current_user can be considered an Object, because it has properties of its own, however, id has no properties and is stored as a String.

The Data "Tree"

You can think of objects in pOS and Siteglide as a Tree. The Object you start on like context or this is like the trunk of the tree. Each time you use a dot to access a property, you are going one level down the tree, until you reach the branch of data you needed.

Just outputting this on its own would show you the real JSON Object behind the first example in this Article and all of its properties: {{this}}

This outputs an object of data, which to start with is a little hard to read. That's because whitespace is removed for efficiency reasons. Adding the whitespace back in with a third party tool will allow us to read it more easily (see the next section).

Visualising the Object "Tree"

To make sense of the JSON that the Liquid outputs, you'll need a tool for automatically formatting the JSON data and adding whitespace. Some tools even help you visualise the data in other more advanced ways.

Visualising the Data

Here is an example of a tree-view. It's the JSON data with extra whitespace and newlines added for readability (colours too).

From this view you can make the same observations we made when using the <pre> tag, but it is easier because each level of the tree is indented and all keys are coloured light blue:

• The first and last character is a curly bracket- this represents the this object we are accessing.

• The key id has no properties, it has a value of 98656 which is stored as a String. this.id will be enough to access it.

• The key properties has properties which are accessible by dot notation. You can tell because the properties key is followed by more curly brackets indicating that it is an object. All the properties inside this set of curly brackets are properties of properties. `{{this.properties.name}}` will access the name property of properties.

Here is a chart view from the same tool. It shows more clearly how some objects are nested within others. You can use this to help you chain dot-notation to get the values you need.

A Special Case - Arrays

You may notice that category_array looks slightly different in the examples above. This is because its value is an array. You can notice an array in your data when square brackets are used around a list of values separated by commas e.g "category_array":["98479", "111111"]

We will cover arrays in the next Article: Advanced Dot Notation: Arrays and Key Maps

This Article will show how to use custom fields to fetch dynamic content in a WebApp Layout.

Introduction

Partners often ask us about outputting Liquid from a Rich Text Editor in their WebApps. Unfortunately it's not currently possible to do this- but here we'll explain a little about why- and a technique you can use to achieve the same effects.

If you want to include content from another WebApp or Module Item, we'd recommend checking out Datasources instead: . Datasource fields allow the Client to search and select the WebApp / Module Items they want to include from a dropdown.

Answer

Currently platformOS doesn't allow Liquid code to be executed within Liquid Fields (such as a Blog's description field). This policy improves security, by making sure it's impossible for user-submitted content to inject malicious Liquid code into your Site- giving you peace of mind that any Liquid code you write is for your eyes only.

We're working on a secure method to allow something like this in the future, but in the meantime, this Article will show you how to use custom fields to fetch dynamic content in the Layout- either above or below your Rich Text field output.

In this example, we'll be adding a Form below the WebApp rich text field.

Step 1) Add custom fields

You'll need to add the following fields to your WebApp structure:

• Show Form - Checkbox containing values True & False.

• Form ID - String field containing the ID of the Form you'd like to output.

• Form Layout - String field containing the name of the Forms Layout.

Step 2) Add data to a WebApp Item

Now the fields we'll be using have been defined, add the relevant information to the fields.

Step 3) Add Liquid to the WebApp Layout where the content will be displayed

Next, locate the WebApp Layout Folder where the Form will be outputted.

Here we can output the Form using the fields that have just been set- wrap the whole include within an IF statement checking whether "Show Form" is "true" if so the Form will be outputted (with the parameters being pulled in from our WebApp). In our example, the Form will be added underneath a Rich Text field.

Now the fields within the WebApp control whether a Form is outputted for each item.

Alternative options for moderating which content the Client can add

*Hardcoding parameters *If you only wish the Client to be able to display a single type of Form, you could hardcode the ID and Layout name of this Form straight to the WebApp Layout.

The Client would have control over whether or not to show a Form, but the Form type would always be the one you approved.

*Using Content Sections *Content Sections and Code Snippets can also be outputted depending on ID and could provide a range of ready-built content which you could allow the Client to add into their WebApp items.

*Expanding the Logic *You could use Liquid Logic in the Layout to only allow certain Form / Content Section IDs to be displayed and forbid others. In this example, Form 2 will never be displayed, even if it is selected:

What is GraphQL?

Ready for some Tutorials?

Take control over your WebApp Layouts by exposing the Data and making your own For Loop with Liquid

Prerequisites

In this Tutorial, we'll be using dot notation, so if you're not familiar with it, you may want to brush up here:

You'll also need to be familiar with WebApps:

Introduction

By default in Siteglide, when you include a WebApp, we query the database and loop over the items for you. We take the data inside the loop and assign it to a variable called this which holds dynamic data about the current item. In certain situations, you may want to do something different, so we have provided the optional parameter collection.

Setting collection to 'true' makes the data from the behind-the-scenes query available to you directly, without a layout.

Using Collection

In the following example, we show the difference between a WebApp list which does use Collection and one which doesn't:

This outputs:

To break it down further, setting collection to true exports the data to {{context.exports}} Under that, you can access it by the id of the WebApp in the original include tag. In this example, it's 1 so we can access {{context.exports.webapp_1.data | json}}.

You can then use dot notation to access the data as you wish.

A Possible Use Case

When would you use collection?

Well some people will prefer to always use collection, others will prefer to use layouts. One possible use-case where Collection works better though is if you want to display the same WebApp twice on the Page but differently each time.

For example, what if you wanted to display the first item largely at the top, then display other items in smaller cards below?

You could use the `

` tag twice to achieve this, with different Layouts each time, but this would have a negative effect on performance. This would slow the Page down, because we would be querying the database behind the scenes twice (once for every time you include the tag).

Alternatively, you could include the webapp just once as a collection, then use Liquid to display the items you want in the way you want:

This outputs:

Great! Only one query needed behind the scenes and we've nearly met the objective, but there's one problem. The item "A Special Guest Appearance" has been included twice!

Advanced Looping

We can use the offset parameter on our loop tag to start the loop at a different index. Let's skip the first index when we loop, as this item has already been displayed.

Using Layouts with Collections

Hang on, wasn't the point of Collections to avoid Layouts? Not quite! The idea was to give you control over the loop- layouts are still possible. I can still include my portfolio_2 layout, but I need to work out its path from SITE MANAGER / Code Editor in Admin.

I can now include the Layout at this Path: `

`

The Layout is expecting an object called this containing the data, but as in the example above we already assigned variables called this containing the right data, the Layout works without further modification:

Want to use Liquid Dot Notation to find dynamic data on your Site? The context variable is most likely the place to look.

Prerequisites

In this Article, we'll be using dot notation, so if you're not familiar with it, you may want to brush up here:

• - You might not need to fully understand this topic- but a first read of it will be very useful in helping you to recognise the more difficult to handle types of data structure- even if you're not ready to tackle them yet.

Introduction

Once you've got a good understanding of Liquid Dot Notation, the next step is branch out and discover what is possible.

Here are some of the most useful places to look for data:

• {{context}} The platformOS object context contains a huge tree of information about your Site- often including variables you didn't know you wanted until you discovered them.

• {{context.exports}} The object exports sits on the root level of context and its role is to allow a global storage location for any custom variables not already included in context. You'll mostly use it as a place to access Siteglide specific data, for example, it is the home of data relating to Siteglide categories and will contain WebApp or module data when you use the collection parameter in the include tag. exports will also contain any keys that you have entered within the area in Siteglide Admin. You can also add your own data to a namespace in exports - see the to see how. This is especially useful if you want to include some data in a Content Section, Code Snippet or Layout- but access it in on a higher level e.g. the Page Template.

• {{this}} - This is a Siteglide variable containing data specific to a Layout- you'll only be able to use if within a Layout file. The data will completely change depending on the type of content, so it's a good place to use Dot Notation to explore each time you try a new feature.

In this article, we'll explore the context object in more detail.

The this object is used differently in different features, so the best place to learn about it is by reading the documentation on the specific feature you're using it with.

Context

The context object's role is to provide your Site with contextual information which might help it render HTML in a more flexible and personalised way.

Context should be available in any Liquid file, and this includes auto-responder and workflow notifications. However, bear in mind that context may work subtly differently in an email- for example- it's not possible to see information about the person reading an email- current_user would refer to the person submitting the Form which triggers the email to be queued.

We'll go through the top level of context's keys and explain each namespace's role. Beyond that, you will have to explore for yourself!

If a property is marked advanced only, it is because we haven't found a use-case for it yet on a Siteglide site, or they are not supported, or there is a newer version of this property which is easier to use. We may mark a feature as advanced only because it is possible for it to conflict with a Siteglide feature and it needs to be used with caution. You may be able to discover your own Use Cases for these- if so we'd be very interested to hear about them! To be clear, we can't offer support if these are used in your Site, but we're noting them here in order to be comprehensive.

authenticity_token (value)

Advanced only - You won't need to use this directly- it is a frequently changing token used as part of the security on form submissions.

session (object)

***Adding Session Fields ***You can add fields to session and exports objects only.

Compatibility: To avoid conflicting with future Siteglide features, we recommend that if you use this feature, you prefix any new fields with the initials or name of your Agency.

e.g. Let's say a User has decided to opt-in to a particular non-essential feature or cookie. You could remember this: <div data-gb-custom-block data-tag="session" data-agency_optional_features='true'></div>

You can then use logic to only show these features to Users who have opted-in.

***Removing Session Fields ***To continue our previous example, if the User chooses to change their preferences and opt out, you can forget the setting by setting it to an empty String: `

`

current_user (object)

Unlike session, this only holds information relating to a User if they are currently logged in to a Secure Zone. It is more sensitive than `session` and will include a name and email address. If there is no current_user, it will hold the value null.

headers (object)

Headers are information sent and received when a browser sends a request to a server for an HTML Page. This is a technical area which can be nevertheless useful on some every-day use cases.

Another helpful property is HTTP_REFERER. This tells you the URL of the Page that the User was visited before the current one- assuming this was not deliberately hidden. This can be really useful for redirecting a User back to a particular Page after carrying out an Action.

params (object)

This object helpfully takes the URL of the current Page and dissects it into chunks which you can use.

• slugs refer to parts of a URL separated by forward slashes / - slug, slug2 and slug3 will be available to you only if they exist. This can be helpful if you're implementing breadcrumbs.

• query parameters will become available to you if they exist and will be available under the same key they use in the URL. E.g. a parameter in the URL https://siteglide.com?password=test will become available here: {{context.params.password}}

Advanced only- When using CLI- params can also be used in a form_configuration to interrogate the form data being sent to the server, including virtual fields.

language (value)

Advanced only- You can ignore this, as Siteglide does not support this pOS feature.

environment (value)

Advanced only- This will currently only read the value of "Production" as currently all Siteglide Sites are Production ready- but watch this space!

is_xhr (value)

Advanced only - Returns true if the Page is being rendered by an XHR (sometimes referred to as Ajax) Request.

location (object)

This is analogous to "location" in JavaScript and can provide you with useful URL information.

• {{context.location.url}} will get you the full absolute URL for the current Page

• {{context.location.href}} will get you the relative URL for the current Page without query parameters- useful if you want to set new query parameters!

• {{context.location.pathname}} will get you the relative URL for the current Page including query parameters.

This Object is often useful when you use it alongside params.

page (object)

This contains metadata for the Page.

layout (object)

This actually gives you metadata relating to the chosen Page Template, not about Layouts on the Page.

modules (object)

This contains objects for each module you have installed on your Site. It includes Siteglide Modules and any Modules you've installed via platformOS. It only contains metadata- if you want data relating to items in that Module, you'll have to access it in a Layout with {{this}} or through making a collection and then looking in {{context.exports}}.

visitor (object)

Advanced only- Contains the IP Address of the visitor.

constants

Advanced only-

useragent

Advanced only- Use device instead!

device

Device should give you information about your visitor's device, operating system and browser. However, use it with caution - you'll still need to make websites responsive! You could use this to suggest to certain Users that they will have a better experience if they update their browser to a modern one.

cookies

This lists the cookies currently used by the Site.

Any payment gateways you are using as part of Siteglide eCommerce e.g. Stripe may also have a cookie listed here.

You may also see cookies relating to browser extensions. Ignore these- as your Users will have different extensions to your Developers!

version

Advanced only

post_params

Advanced only

flash

Advanced only

exports

This is where all context data is kept which is custom- either to Siteglide or that you have added to your Site.

Turning the Page! In tutorial 2, we'll control how many items Graph returns on each Page of results and retrieve specific Pages.

Prerequisites

• You have completed the first Learning GraphQL tutorial.

• About GraphQL- optional- Read more about GraphQL and when it might be best used.

Introduction

When GraphQL returns results, it will organise them into pages.

This allows it to be more efficient, as it only returns the data that is needed straight away. At the same time, the rest of the pages are organised ready for the next request.

You'll always need to think about Pagination when using GraphQL, even you only want to retrieve the first Page of results.

Per Page

per page is an argument used to define the number of results that will be returned on each page.

It's now a mandatory argument on some types of query so we've already got the argument in our query from the last tutorial:

query get_all_records {
  records(
    per_page: 20
  ) {
    total_entries
    results {
      model_schema_name
      properties
    }
  }
}

Experiment by changing the integer in the argument from 20 to another value, e.g. 1. Observe the difference. It's recommended to keep the per_page number as low as possible- for efficiency and performance.

Let's consider a few situations:

• You want to display 3 items - Set per_page to 3- only the three items you need will be retrieved.

• You want to display 20 items at a time, but allow the user to view the next 20 when they've finished reading - Set per_page to 20

• If you want the user to be able to change per_page dynamically, we'll cover this when we look at variables in a future tutorial.

• If you think you need to display more than 2000 items at a time (perhaps to provide data to a JavaScript plugin), consider using GET requests to a custom Liquid endpoint page to fetch each page of results asynchronously. You can learn more in Tutorial 8 - Building a Liquid API GET Endpoint Page powered by GraphQL queries but we recommend working through the other tutorials first.

Returning Pagination Metadata

You can return pagination metadata alongside your query results:

• current_page - Returns the number of the current page.

• per_page - Returns the number of items on every page.

• has_previous_page - A boolean which is true if there is a page before the current page.

• has_next_page - A boolean which is true if there is a page after the current page.

• total_pages - Returns an integer representing the total number of pages in these results.

These optional properties can be requested alongside total_entries and your results object, like in the example below. Try them out. Code:

query get_all_records {
  records(
    per_page: 20
  ) {
    current_page
    total_pages
    has_previous_page
    has_next_page
    per_page
    total_entries
    results {
      model_schema_name
      properties
    }
  }
}

Notes:

• Properties like has_next_page and has_previous_page are most useful for adding pagination buttons of your own.

• You can see that by default, we get the first page of results- so page returns 1.

Explorer:

Changing the Page

You can view other pages by setting the page argument to the page of results you'd like to see.

Code:

query get_all_records {
  records(
    page: 2
    per_page: 20
  ) {
    current_page
    total_pages
    results {
      model_schema_name
      properties
    }
  }
}

Explorer:

Next time

In the next Article, we'll look at how to filter results.

For example, we'll learn how to return items from only a specific WebApp.

Let's go!

We look at a possible answer to Tutorial 3's challenge. This shows how to write a query which fetches all WebApp items, not Module items.

Prerequisites

• This Article shows the Answers to a Challenge. If you've not had a go at the challenge yet, we'd recommend you head there first.

• About GraphQL- optional- Read more about GraphQL and when it might be best used.

Challenge Answers

The trick here was to examine the tablesand spot the common patterns in their values.

The two types of recordswe wanted had these tables beginning with "webapp_":

• webapp_1

• webapp_2

The types of records we don't want have table values without "webapp_", for example:

• module_3 - (Blog Module)

• module_14 - (eCommerce Module)

• form_1 - Newsletter Sign Up Form Submissions

So, in order to filter for the recordswe do want and not the recordswe don't want, we need recordswhich start with the string webapp_.

Code:

query get_all_webapps {
  records(
    page: 1
    per_page: 20
    filter: {
      table: {
        starts_with: "webapp_"
      }
    }
  ) {
    total_pages
    results {
      table
      properties
    }
  }
}