1 of 9

File Manager

Siteglide has a built-in Document Management System (DMS) where you can create folders and upload various types of files (assets) including Images (JPG, PNG, SVG, WEBP etc), PDFs and Videos:

The first button on the right of each image allows you to Edit the image:

The second button is to Download the image. The final 2 buttons are to copy the URL for the image:

Direct URL: The full CDN URL you can use in background images or external links.
Asset URL: The dynamic version that should be used on Siteglide pages for optimum performance.

Linking to Assets Explained

Find out how to use the asset_url filter to generate a path to your assets and understand the benefits of hosting assets on our CDN.

Introduction

Assets are stored directly on an Amazon Web Services (AWS) server, separate to the website you are building on. They can be accessed using a Content Delivery Network (CDN) from your website.

Benefits

The use of this method offers automatic Caching control, which decreases the likelihood that someone views your website with anything other than the most up-to-date versions of your files. The CDN also reduces page load times, as the assets are not stored on your site, but instead are distributed to over 100 edge locations around the world.

CDN Asset URLs for the Best Performance

If you have uploaded an image to the images folder using File Manager, it will have a file path like this in the database: images/SG-Logo-White.svg

You would add the following liquid to your page, so that the server automatically appends the CDN URL: {{ 'images/SG-Logo-White.svg' | asset_url }}

You will see that the asset will render on the page with a similar path to this: https://uploads.prod01.oregon.platform-os.com/instances/283/assets/images/SG-Logo-White.svg?updated=1549914206

Each site has a unique CDN path, you can find out what yours is by rendering an image on the page and inspecting on it. ?updated= is a parameter automatically included that time stamps your files, helping with cache control.

Relative Asset URLs - Good Performance and convenient but may have caching issues for regularly updated assets

Using ../ automatically appends the URL to your asset within CSS files:

background-image: url('../images/SG-Logo-White.svg');

../ is relative to the location of your stylesheet which will already be inside the CDN. This is especially useful for background images. You can look up CSS relative paths online for more information.

Note that this can have drawbacks with assets which are regularly updated, as you may pull in a cached version of the image. Using asset_url instead prevents this as it always appends the URL with a timestamp, busting the cache and getting the most recent version.

Vanity Asset URLs - Slower Performance, but sometimes a Client Requirement

In some cases you may wish to hide the AWS CDN (https://uploads.prod01.oregon.platform-os.com) and only refer to the vanity domain of the site (https://www.mydomain.com). To dynamically achieve this, you can use the liquid parameter asset_path rather than asset_url when calling an asset to a page. Any of the above examples are also applicable with this method.

{{ 'images/SG-Logo-White.svg' | asset_path }}

You will see that the asset will render on the page with your vanity domain in it's path, similar to this: https://www.mydomain.com/assets/images/SG-Logo-White.svg?updated=1549914206

Assets Troubleshooting

Diagnosing issues

If you cannot see the asset on your page then you can check the following common issues:

Check the string you used for a path does not start with a forward slash or "assets".

e.g. these will fail because the "/" or "assets/" beginning of the path will end up being added twice.

Check the file manager or code editor shows the correct path for your asset, including any folders.
You should include the file extension for your asset in the path e.g. ".jpg"

e.g. this will fail because an asset's full name has not been included:

{{'images/SG-Logo-White' | asset_url }}

Make sure you wrap your path in quotes as it is a string:

e.g. here a string was forgotten and validation on Admin or Siteglide CLI should not accept it:

{{images/SG-Logo-White | asset_url }}

Special Characters and Spaces

Ideally, try not to upload files which contain special characters or spaces. However, if this is unavoidable, there are ways to fix the "access denied" errors you may see when you follow a link to an image like this.

Dashes '-' and forward slashes '/' are not counted as special characters for this purpose. When uploaded to AWS, any special characters or spaces will be URL encoded automatically. But to access the file, you will need to encode the path and then replace the % signs in the encoded string with the encoded version of the % sign "%25".

If you're experiencing this issue and need further guidance, contact support.

Siteglide Scripts Explained

Teleporting Scripts to the Head and Footer with siteglide_head_scripts and siteglide_footer_scripts or using context.exports to avoid duplicates

Introduction

Typically when building a website, we have one or two core stylesheets and JavaScript files that contain the styling for your entire website.

When building large sites, however, these files can contain many thousands of lines of code. This can mean that loading the head files for the entire website on each and every page, can become unwieldy and slow.

siteglide_head_scripts and siteglide_footer_scripts can be used anywhere on a page and automatically move their contents to either the <head> or to before the closing </body> tag respectively.

This allows you to include a JS file only when it becomes relevant to a particular snippet of Liquid code, yet still output that <script> or <link> tag file a maximum of one time per page and in the most optimum position in the DOM.

Head Scripts

siteglide_head_scripts moves the contained assets into the <head> of your page when it renders. You must include ,, on the end of each line within this liquid tag.

<div data-gb-custom-block data-tag="content_for" data-0='siteglide_head_scripts'> <link rel="stylesheet" href="{{'css/modules/module_3/design_system/1/sidebar.min.css' | asset_url}}" />,,</div>

Footer Scripts

siteglide_footer_scripts moves the contained assets to the bottom of the body tag on your page when it renders. You must include ,, on the end of each line within this liquid tag.

<div data-gb-custom-block data-tag="-" data-0='siteglide_footer_scripts'></div> <link rel="stylesheet" href="{{ 'css/modules/module_9/custom.css' | asset_url}}" />,,<div data-gb-custom-block data-tag="-"></div>

Troubleshooting

Problem

My JavaScript console has the error: Uncaught SyntaxError: Unexpected end of input?

Solution

This error can occur if you use single-line comments in your inline JavaScript and then wrap that script inside the head or footer scripts. It's because the newlines are removed from the JavaScript- meaning the single-line comments do not end when they should.

You can fix it by moving your JavaScript to an external file or replacing single-line comments // with opening /* and closing */ JavaScript comments.

Performance and Avoiding Duplicates

When you use content_for you can add resources from many different files and they'll all output together in the <head> or before the closing tag. While this is convenient, you should be especially wary of accidentally including the exact same resource twice and slowing down your page.

To help avoid this, Siteglide will attempt to check the tags you've added for any duplicates before outputting. This happens on the server-side. Adding two commas ,, at the end of each line, allows this functionality to work.

We'd still recommend you check your Page Source for any duplicate resources. It's still possible for this to happen if you add the same resource to siteglide_head_scripts from two different Layouts with different CDN links each time. Also it can happen if you send one tag to the siteglide_head_scripts and another to the siteglide_footer_scripts.

Duplicate checking checks for duplicate tags, it doesn't follow the links and check for duplicate content. If you always load from our CDN using | asset_url the risk of this is reduced.

Using content_for with your own namespace

The platformOS docs explain how you can add any namespace to the content_for tag and use it in conjunction with the yield tag to send any variable from the Page to the Page Template.

Content For: https://documentation.platformos.com/api-reference/liquid/platformos-tags#content_for

Yield: https://documentation.platformos.com/api-reference/liquid/platformos-tags#yield

If using this, we'd recommend again that you check for any duplicate resources, as at the time of writing there is a known issue with this technique. For now, there are two ways to make this work:

Use our namespaces listed above
Use the flush: 'true' parameter to prevent duplicates occurring. This empties the namespace clean each time you add something- meaning you can only add content to the namespace once.

Alternatives - Using context.exports

Another way of avoiding duplicate entries of assets in your code, only pulling them in when the page needs them is to use the context.exports variable to keep track of them. This is the method most often used by SiteBuilder.

{% if context.exports.sitebuilder.live_update_JS_loaded == blank %}
  <script async src="{{'modules/module_86/js/v1-5/sitegurus_live_update_javascript_api.min.js' | asset_url }}"></script>
  {% assign live_update_JS_loaded = true %}
  {% export live_update_JS_loaded, namespace: sitebuilder %}
{% endif %}

The if statement checks if the <script> has already been outputted; the next line outputs the <script>, if not.

The next two lines store a new variable in exports to make sure the same code will know not to output the same again.

This method does not have the benefit of "teleporting" your code to the <head> or closing </body> tag, but it works well with <script> tags with the async or defer attributes.

Assets with CLI

Deploying Assets

This will deploy assets all at once along with the entire code base. The -w flag is necessary to include assets.

siteglide-cli deploy env -w

Syncing Assets

siteglide-cli sync env

Watches for changes in the assets folder and syncs changed files one by one. This is not always recommended for large files.

Migrating Assets

Introduction

When migrating a site from one platform to another, we recommend that the first thing you do is import your assets.

This means that when you import your WebApps and WebApp Layouts later on, the paths to the images can easily be mapped.

There are two main ways to upload assets:

via the Siteglide CLI
via the Admin CMS/ File Manager

Using File Manager to Upload Assets

File Manager currently allows you to bulk upload files within your browser. This is a great alternative to CLI for day-to-day use. You can create folders and upload assets within each as you go.

However, there could be browser limitations over how much can be uploaded at once (e.g. large file sizes), so we still recommend you use Siteglide CLI for bulk upload and for migrations.

Uploading Your Assets Using Siteglide CLI

If you have a very large number of assets to upload (especially large images or videos), the best way to upload is via the Siteglide CLI.

In order to do this: you'll need to follow these steps. Where a step has a placeholder like , add in your own environment, for example production:

First follow this tutorial to set up siteglide-cli, including adding an environment.
Create a new folder for your project if you've not already got one.
Change directory to that folder with the terminal command cd path/to/folder
Run the terminal command siteglide-cli pull . When prompted to, type a capital "Y" to confirm.

You will now have the Site stored in your new Project folder. On the root, level, you'll see a root folder called marketplace_builder.

In your new Project folder, make sure the counterpart versions of these folders exist inside marketplace_builder/assets/ - by default after a pull, only a css and js folder will be shown. If needed, create any other folders here

Run the terminal command siteglide-cli deploy -w . This deploys your marketplace_builder folder, including the assets, to your website.
Check your assets have arrived successfully on Admin by navigating to CMS/File Manager and checking each of the four tabs.

Outputting your Assets

Assets are stored and accessed a bit differently on our platform. We do this to receive various benefits, check out our doc on Assets to find out more.

Steps to Optimise Images on the Fly with Cloudinary

Introduction

https://cloudinary.com/ is a 3rd party service which we recommend as a convenient way to transform assets on the fly to change their size or format.

When building sites for fast performance, there is often a compromise with convenience. Tools like Google Page Speed Insights remind you to store multiple sized versions of the same image in order to optimise them to different sized device screens and resolutions. You also want to serve images in next-gen formats like webp, but your client will usually upload jpg or png images.

Cloudinary allows you to get the best of both worlds, by using the Siteglide File Manager's AWS CDN to store single original copies of each image for a clutter-free, easy experience for clients, while in the code you can dynamically transform images to optimise them perfectly to the site vistors. Cloudinary also caches their transformations, so after the first time they are delivered as fast as if you had already uploaded different versions to the CDN.

Step 1 - Create a Cloudinary Account

Go to https://cloudinary.com/ and follow the steps to create an account.

Step 2 - Make a Note of your Cloud Name

This will be an essential part of the URLs.

https://cloudinary.com/documentation/cloudinary_credentials_tutorial

Step 3 - Generate your first URL inside your code

To build a URL, you will need to start with the beginning of the Cloudinary URL, which will direct the browser to their API endpoint, replacing 'demo' with your cloud name from step 2:

https://res.cloudinary.com/demo/image/fetch/\

Next add your optional transformations to resize the image by a number of pixels width or height:

https://res.cloudinary.com/demo/image/fetch/h_200,w_200

Next optionally add transformations to automatically transform to next-gen image formats on supported browsers only:

https://res.cloudinary.com/demo/image/fetch/h_200,w_200/f_auto/

then use Liquid to get the path to the original image on Siteglide's CDN. See

For example:

{{'images/example.jpg' | asset_url}}

Putting it all together:

https://res.cloudinary.com/demo/image/fetch/h_200,w_200/f_auto/{{'images/example.jpg' | asset_url}}

Step 4 - Add HTML to deliver the Appropriate URL to several Screen Resolutions - Optional

Source: MDN

<img
  srcset="https://res.cloudinary.com/demo/image/fetch/w_480/f_auto/{{'images/example.jpg' | asset_url}} 480w, https://res.cloudinary.com/demo/image/fetch/w_800/f_auto/{{'images/example.jpg' | asset_url}} 800w"
  sizes="(max-width: 600px) 480px,
         800px"
  src="https://res.cloudinary.com/demo/image/fetch/w_800/f_auto/{{'images/example.jpg' | asset_url}}"
  alt="Example of serving different sized images on different screen widths" />

Learn more about the

Step 5 - Read the Cloudinary Docs and Experiment with more Image Transformations - Optional

There are many more options available. Read more here:

https://cloudinary.com/documentation/image_transformations In these examples, you may need to replace 'upload' with 'fetch' in the URL to support remote images from the Siteglide file manager.

Also check out using client hints on some browsers to further fine-tune image requests:

https://cloudinary.com/documentation/responsive_server_side_client_hints

Assets File Structure

marketplace_builder/
└── assets/
    ├── css/
    ├── images/
    └── js/

Any folders inside the assets folder are optional. We've included a few common default folders as an example.

Tags for Assets

Linking to Assets

HTML - Stylesheets:

<link rel="stylesheet" type="text/css" href="{{ 'css/styles.css' | asset_url }}" />

HTML - JavaScript files:

<script src="{{ 'js/myfile.js' | asset_url }}"></script>

HTML - Images:

{{ 'images/SG-Logo-White.svg' | asset_url }}

WebApp Asset Field:

{{ this['my_field'] | asset_url }}

CSS - Relative Paths:

background-image: url('../images/SG-Logo-White.svg');

Vanity URL to Asset - Slower Performance:

{{ 'images/SG-Logo-White.svg' | asset_path }}

Or

/assets/images/SG-Logo-White.svg

Siteglide Scripts Explained

Teleporting Scripts to the Head and Footer with siteglide_head_scripts and siteglide_footer_scripts or using context.exports to avoid duplicates

Introduction

Typically when building a website, we have one or two core stylesheets and JavaScript files that contain the styling for your entire website.

Head Scripts

siteglide_head_scripts moves the contained assets into the <head> of your page when it renders. You must include ,, on the end of each line within this liquid tag.

<div data-gb-custom-block data-tag="content_for" data-0='siteglide_head_scripts'> <link rel="stylesheet" href="{{'css/modules/module_3/design_system/1/sidebar.min.css' | asset_url}}" />,,</div>

Footer Scripts

siteglide_footer_scripts moves the contained assets to the bottom of the body tag on your page when it renders. You must include ,, on the end of each line within this liquid tag.

Troubleshooting

Problem

My JavaScript console has the error: Uncaught SyntaxError: Unexpected end of input?

Solution

You can fix it by moving your JavaScript to an external file or replacing single-line comments // with opening /* and closing */ JavaScript comments.

Performance and Avoiding Duplicates

Duplicate checking checks for duplicate tags, it doesn't follow the links and check for duplicate content. If you always load from our CDN using | asset_url the risk of this is reduced.

Using content_for with your own namespace

The platformOS docs explain how you can add any namespace to the content_for tag and use it in conjunction with the yield tag to send any variable from the Page to the Page Template.

Content For: https://documentation.platformos.com/api-reference/liquid/platformos-tags#content_for

Yield: https://documentation.platformos.com/api-reference/liquid/platformos-tags#yield

If using this, we'd recommend again that you check for any duplicate resources, as at the time of writing there is a known issue with this technique. For now, there are two ways to make this work:

Use our namespaces listed above
Use the flush: 'true' parameter to prevent duplicates occurring. This empties the namespace clean each time you add something- meaning you can only add content to the namespace once.

Alternatives - Using context.exports

{% if context.exports.sitebuilder.live_update_JS_loaded == blank %}
  <script async src="{{'modules/module_86/js/v1-5/sitegurus_live_update_javascript_api.min.js' | asset_url }}"></script>
  {% assign live_update_JS_loaded = true %}
  {% export live_update_JS_loaded, namespace: sitebuilder %}
{% endif %}

The if statement checks if the <script> has already been outputted; the next line outputs the <script>, if not.

The next two lines store a new variable in exports to make sure the same code will know not to output the same again.

This method does not have the benefit of "teleporting" your code to the <head> or closing </body> tag, but it works well with <script> tags with the async or defer attributes.