Embedding Styla on Your Website

TLDR: For a Styla Page or Magazine to be rendered on a page, you need to reference a script that renders it and a place a container with a specific ID in which it will be rendered.

Current implementation

This specification describes the best way to render Styla Pages and Magazines content with JavaScript. There is a legacy specification described below that is still working but a bit slower hence should not be used for new Styla clients.

What is needed

Rendering your Styla Content in a <div> using the JS file from Styla:

1. Reference this script in the <head> of the page:

<script src="https://engine.styla.com/init.js" async></script>
  • this file (the same one used for Modular Content) will take care of rendering Pages content for any Styla client
  • the script will also take care of styling of the Styla content, so no need to reference an additional CSS. Styla does not use your website's CSS.
  • make sure not to iload the script multiple times on one page 

2. Place this container where you want your Styla content rendered:

It's usually between the header and the footer:

<div data-styla-client="${clientName}">${staticHtml}</div>
  • you get the ${clientName} from Styla during your onboarding, it's the same account you create content for in editor.styla.com
  • if you use Styla for several languages/locales, you will need to use a different ${clientName} for each of them
  • the ${staticHtml} is delivered by the integration with Styla's SEO API and can skipped for quick testing purposes but then Styla content won't render with JavaScript switched off

3. In case your CMS does not enable you to reference the script in the head, just put it in the <body> like this: 

<div data-styla-client="${clientName}">${staticHtml}</div>
<script src="https://engine.styla.com/init.js" async></script>

Why this needs to be done

Once embedded, the script will render a piece of content matching the relative path of the page on which it is embedded. If no page matching this path has been published for this clientName with editor.styla.com then the script will render a Styla 404 message.

Please pay attention to trailing slashes. If a page you have published in editor.styla.com does not have a slash at the end while the URL on which you ran the script ends with a slash, the script will display a 404 message. A rule can be set by Styla CSM to have all your Styla paths end in a slash automatically.

Styla content will be rendered where the <div> is placed in your website's template (usally between its header and footer) in users' browser window. 

We don't guarantee that embedding Styla JS with any external tag manager will work. If it's essential, please take your time to test it and contact Styla's support if you need our help or have questions.

Styla content will only be displayed in mobile size/style if the <meta name="viewport"> tag is present on the parent page. Most CMS generate it automatically but if yours does not, please include it.

HTML Hydration

On clients' request we can allow browser to display static HTML rendered server-side based on tags from the SEO API until Styla JavaScript renders content. If you are interested in this option, please contact your Customer Success Manager at Styla.

Example live implementations

You can find these code snippets in page sources on the pages linked to below.

OBI page

1. Client's snippet:

<script src="https://engine.styla.com/init.js"></script>

2. Client's div:

<body>
<div data-styla-client="obi"></div>
</body>

Hardeck Homepage

1. Client's JS snippet:

<script src="https://engine.styla.com/init.js" async></script>

2. Client's div:

<body>
<div data-rootpath="/" data-styla-client="hardeck" data-styla-content=""></div>
</body>


Legacy implementation

This specification describes the older way to render Styla Pages and Magazines content with JavaScript. It's a little bit slower than the one described above but is still used by many Styla clients.

What is needed

Rendering your Styla Content in a <div> using the JS file from Styla:

1. Reference this script in the <head> of the page:

<script src="//client-scripts.styla.com/scripts/clients/{styla-account}.js" async></script>
  • the {styla-account} placeholder should be substituted with the real ID that you should have received from Styla,
  • it makes sense to use a variable for it in case you need to embed several Styla accounts on different pages for different countries/languages/currencies/target groups,
  • the JS will also take care of styling of the Styla content, so no need to reference an additional CSS. Styla does not use your website's CSS.  

2. Place this container where you want your Styla content rendered:

It's usually between the header and the footer:

<div id="stylaMagazine"></div>

3. In case your CMS does not enable you to reference the script in the head, just put it in the <body> like this: 

<div id="stylaMagazine"></div>
<script src="//client-scripts.styla.com/scripts/clients/{styla-account}.js" async></script>

4. Include DNS prefetch statements for the following Styla subdomains you will request data from:

<link rel="dns-prefetch" href="//styla-prod.us.imgix.net"><link rel="dns-prefetch" href="//client-scripts.styla.com"><link rel="dns-prefetch" href="//redpanda.styla.com">

Example live implementations

You can find these code snippets in page sources on the pages linked to below.

NorthSails page

1. Prefetch statements:

<head>
<link rel="dns-prefetch" href="//client-scripts.styla.com"><link rel="dns-prefetch" href="//redpanda.styla.com"><link rel="dns-prefetch" href="//styla-prod.us.imgix.net">
</head>

2. Client's snippet (an example past version number):

<head>
<script src="//client-scripts.styla.com/scripts/clients/northsails-en.js?v=169C45B21FC-39"></script>
</head>

3. Client's div:

<body>
<div id="stylaMagazine" data-rootpath="/gb/en/s/"></div>
</body>

Yourhome magazine

1. Prefetch statements:

<head>
<link rel="dns-prefetch" href="//client-scripts.styla.com"><link rel="dns-prefetch" href="//redpanda.styla.com"><link rel="dns-prefetch" href="//styla-prod.us.imgix.net">
</head>

2. Client's snippet (an example past version number):

<head>
<script>
 window.mak.afterCreate.push(function () {
  var head = document.getElementsByTagName("head")[0];
  var script = document.createElement('script');
  script.setAttribute('src', 'https://client-scripts.styla.com/scripts/clients/yourhome-de.js?v=169C45B21FC-175');
  head.appendChild(script);
 });
</script>
</head>

3. Client's div:

<body>
<div id="stylaMagazine"></div>
</body>


How to test your implementation

Once you have the above running on your local, stage and production environment, please make sure everything is working fine:

  1. The JS and CSS are appended with the most up-to-date version (compare with the version endpoint) which is requested and cached on your end for 5 minutes.
  2. When you go the page(s) with your Styla content embedded, your browser displays the feed with all stories there accordingly. Compare with what you see at https://{styla-account}.styla.live/{page-path}, which is a preview service for Styla content, not embedded anywhere.
  3. Check visually if all the styling is applied properly and there are no glitches that might be a result of interference of your JS and CSS with the ones Styla provides.
  4. Check visually how your embedded Styla Content behaves on: mobile phone, tablet, desktop. Its layout should not respond to the browser tab size being changed directly, but adjust to it once the page is reloaded.
  5. Content is updated in the feed and on story page once you change them in backoffice.styla.com.
  6. Check if the following actions work fine:
  • Single story content is displayed correctly once you click it in the feed.
  • Only stories from a given category are shown in the feed once you click the name of the category above the feed.
  • More story pages are loaded when you scroll the feed down.
  • Search returns results accordingly.

If there are any problems that you cannot solve, please contact Styla support.

Additional options

You can use data parameters in the div to force some additional behaviour on the Styla JS.

Forcing a specific Styla page

To do that, use data-styla-client and data-styla-content parameters like this:

<script src="//client-scripts.styla.com/scripts/clients/{styla-account}.js" async></script>
<div data-styla-client="{styla-account}" data-styla-content"={styla-page-slug}">

This will make the Styla JS render page with a specific slug that you previously created in Styla CMS at editor.styla.com.

This is very useful when embedding Styla content on your Home or any other page outside of the Styla root path wich streamlines publishing of Styla content. However, there is a caveat: integration with the SEO API won't work out-of-the-box and fetching tags for this page needs to be hardcoded.

Forcing a specific root path

You can also force a specific root path to avoid 404 error from Styla if you embed content that normally is displayed on a different URL. Use data-rootpath parameter to achieve this:

<script src="//client-scripts.styla.com/scripts/clients/{styla-account}.js" async></script>
<div id="stylaMagazine" data-rootpath="/gb/en/inspiration/">

This will make the Styla JS render page on the /gb/en/inspiration/ path correctly, even if this account has a different root path set - and would render a 404 from Styla without this parameter.

Triggering Styla content in a specific moment

If you're having timing issues and, for instance, Styla div is loaded after Styla JS has checked for it, please use the below to load the content in a specific moment:

window.styla.init()

This will be especially useful if you embed Styla content into a single-page application. Please make sure to remove Styla content from the scope once no longer needed. Otherwise it might stack up and clutter your DOM.