Content rendering

This guide provides practical examples of how to use the JavaScript SDK to fetch and render a Slot in your application.

Basic usage

To fetch content, you can use the fetch method. This method receives the ID of the slot you want to fetch and returns a promise that resolves to the content.

I can generate code for you!

Go to the Integration page, select the slot you want to implement, and get a fully functional integration code to copy and paste.

Let's say you have a slot called home-hero which represents the content for the hero section of your homepage.

You can fetch the content of this slot as follows:

import croct from '@croct/plug';

async function renderHero() {
  const {content} = await croct.fetch('home-hero');
}

Once the promise is resolved, you can use the result to render the content in your application. The actual structure of the content depends on the schema of the slot, but here is an example:

{
  "title": "The best personalization platform for developers",
  "subtitle": "Best-in-class developer experience and enterprise-grade reliability.",
  "image": {
    "url": "https://cdn.croct.io/devs.png",
    "alt": "A screenshot of an editor showing a code snippet."
  },
  "button": {
    "label": "See docs",
    "url": "https://docs.croct.com"
  }
}

You can then use this content to render the hero section of your homepage:

import croct from '@croct/plug';

async function renderHero() {
  const {content} = await croct.fetch('home-hero');

  const hero = document.querySelector('.hero');
  const heading = hero.querySelector('h1');
  const subtitle = hero.querySelector('.subtitle');
  const image = hero.querySelector('.image');
  const button = hero.querySelector('.button');

  heading.textContent = content.title;
  subtitle.textContent = content.subtitle;
  image.setAttribute('src', content.image.url);
  image.setAttribute('alt', content.image.alt);
  button.textContent = content.button.label;
  button.setAttribute('href', content.button.url);
}

renderHero();

This is just a simple example, but you can use any templating engine or framework to render the content in your application.

Fault tolerance

You should always provide a fallback content to make your application resilient to unexpected errors, downtime, and network failures.

You can achieve this by catching potential errors and providing a fallback content in case of error:

import croct from '@croct/plug';

async function renderHero() {
  const {content} = await croct.fetch('home-hero')
    .catch(() => ({
      content: {
        title: 'Welcome to Croct!',
        subtitle: 'The easiest way to personalize your application.',
        image: {
          url: 'https://cdn.croct.io/hero.png',
          alt: 'A screenshot of the Croct dashboard.',
        },
        button: {
          label: 'Get started',
          url: 'https://croct.com',
        },
      }
    }));

  const hero = document.querySelector('.hero');
  const heading = hero.querySelector('h1');
  const subtitle = hero.querySelector('.subtitle');
  const image = hero.querySelector('.image');
  const button = hero.querySelector('.button');

  heading.textContent = content.title;
  subtitle.textContent = content.subtitle;
  image.setAttribute('src', content.image.url);
  image.setAttribute('alt', content.image.alt);
  button.textContent = content.button.label;
  button.setAttribute('href', content.button.url);
}

renderHero();

Version control

You can lock a specific slot version to keep the content structure aligned with your application's expectations. This gives your team the freedom to evolve the structure over time without the risk of breaking things.

You can specify the version of the slot by passing a versioned ID in the form <id>@<version>. For example, passing home-hero@2 will fetch the content for the home-hero slot in version 2. Not specifying a version number is the same as passing home-hero@latest, which will load the latest content.

const {content} = await croct.fetch('home-hero@2');

For more information, see Slot versioning.

Localization

To support multiple locales, you can use the preferredLocale option to specify the locale of the content you want to retrieve. This is usually the locale of the user's browser or account.

By default, if you do not specify a locale, or if the content is not available in the preferred locale, the content is returned in the default locale of your workspace.

Here is an example of how to fetch content in a specific locale:

const {content} = await croct.fetch('home-hero', {
  preferredLocale: 'en-ca',
});

For more information, refer to the preferredLocale documentation.

Context variables

Sometimes you need to provide additional information to personalize or segment your users.

For example, if you are working on a SaaS application, you may want to personalize the content based on the subscription plan, quota usage, features, or any other application-specific information. You can achieve this by passing any relevant information to the attributes option:

const {content} = await croct.fetch('upgrade-banner', {
  attributes: {plan: 'premium'},
});

These values are then accessible as custom attributes in the context variable:

context's plan is "premium"

Keep in mind that the context has some constraints on the number of attributes and levels of nesting. For more information, please refer to the attributes documentation.