Skip to content

Use Cases

Fetch Navigation

api
  .fetchNavigation({ locale: 'de_DE' })
  .then((result) => console.log('Fetched Navigation: ', result))
  .catch((error) => console.error('Failed to fetch navigation', error));

Create Page

These examples show how to create the various types of pages in FirstSpirit.

Product

api
  .createPage({
    fsPageTemplate: 'product', // (1)
    id: `Product Page`,        // (2)
    type: 'product',           // (3)
    displayNames: {
      EN: `Product Page EN`,   // (4)
      DE: `Product Page DE`,
    },
  })
  .then((isSuccess) => console.log('Create Product Page: ', isSuccess ? 'SUCCESSFUL' : 'FAILED'))
  .catch((error) => console.error('Failed to create product page', error));
  1. FirstSpirit page template uid
  2. ID from shop system
  3. Page type to create (product, category or content)
  4. Display names for various languages

Category

api
  .createPage({
    fsPageTemplate: 'category', // (1)
    id: `Category Page`,        // (2)
    type: 'category',           // (3)
    displayNames: {
      EN: `Category Page EN`,   // (4)
      DE: `Category Page DE`,
    },
  })
  .then((isSuccess) => console.log('Create Category Page: ', isSuccess ? 'SUCCESSFUL' : 'FAILED'))
  .catch((error) => console.error('Failed to create category page', error));
  1. FirstSpirit page template uid
  2. ID from shop system
  3. Page type to create (product, category or content)
  4. Display names for various languages

Content

api
  .createPage({
    fsPageTemplate: 'contentpage', // (1)
    id: `Content Page`,            // (2)
    type: 'content',               // (3)
    displayNames: {
      EN: `Content Page EN`,       // (4)
      DE: `Content Page DE`,
    },
  })
  .then((isSuccess) => console.log('Created Content Page: ', isSuccess ? 'SUCCESSFUL' : 'FAILED'))
  .catch((error) => console.error('Failed to create content page', error));
  1. FirstSpirit page template uid
  2. ID from shop system
  3. Page type to create (product, category or content)
  4. Display names for various languages

Find Page

api
  .findPage({
    locale: 'de_DE',
    id: `Content Page`, // (1)
    type: 'content',    // (2)
  })
  .then((pageResult) => console.log('Found Page: ', pageResult))
  .catch((error) => console.error('Failed to find page', error));
  1. ID from shop system
  2. Page type to fetch (product, category or content)

Note

To improve the performance of CaaS requests, the Connect for Commerce module creates an index in CaaS. This consists of the keys page.formData.type.value, page.formData.id.value, locale.language and locale.country, which are necessary to identify a Shop Driven Page. The index is created for both the preview and release collection.

Create Section

This example shows how to create a section by looking for the page first in order to receive its preview ID.

api
  .findPage({           // (1)
    locale: 'de_DE',
    id: `Content Page`, // (2)
    type: 'content',    // (3)
  })
  .then((pageResult) => {
    console.log('Found Page: ', pageResult);

    api
      .createSection({
        pageId: pageResult.items[0].previewId, // (4)
        slotName: 'content',                   // (5)
      })
      .then((isSuccess) => console.log('Create Section: ', isSuccess ? 'SUCCESSFUL' : 'FAILED'))
      .catch((error) => console.error('Failed to create section', error));

  })
  .catch((error) => console.error('Failed to find page', error));
  1. Find the page first to retrieve the preview ID
  2. ID from shop system
  3. Page type to create (product, category or content)
  4. Preview ID from FirstSpirit
  5. Name of the slot to create a section in

Create Add content button

This will create a custom "Add content" button.

const targetElement = document.querySelector('my-selector');
const button = addContentButton({
  handleClick: () => {
    // Handle the event
  }
});
targetElement.appendChild(button);

Parse DOM of current page for slots

This will look for HTML-elements with the attribute data-fcecom-slot-name and will extend the DOM based on whether or not content exists in the CaaS for the current element.

When there is no content at all for the given element yet (i.e. no page exists in FirstSpirit for the given element ID), the slots will be filled with "Add content" buttons allowing the user to add content to the slots. Clicking the buttons will create a corresponding page in FirstSpirit and create a section within the selected slot afterwards.

When there is an entry within the CaaS already, the data-preview-id attributes required by TPP will be set. This will cause the Content Creator to render its outline and edit buttons.

const pageResult = api.setPage({
  fsPageTemplate: 'product', // (1)
  id: 'Product Page',        // (2)
  type: 'product',           // (3)
  displayNames: {            // (4)
    EN: 'Product name EN',
    DE: 'Product name DE',
  },
  locale: 'en_GB',           // (5)
  ensureExistence: true      // (6)
});
  1. FirstSpirit page template uid - will be used when the page has to be created when adding content
  2. ID from shop system
  3. Page type (product, category or content)
  4. Display names for various languages - will be used when the page has to be created when adding content
  5. The current locale
  6. If the page does not exist, it can be created. For this to work, the pageTarget has to be a representation of a shop-driven page.

Rendering content

While the actual rendering of the content is not within the scope of this API, it can be used to extract the data used to render the contents.

const pageResult = await api
  .findPage({
    locale: 'de_DE',
    id: `Content Page`,
    type: 'content',
  });

const sections = EcomApi.extractSlotSections(
  pageResult, // (1)
  'content'   // (2)
);
  1. Result of findPage or setPage
  2. Name of the slot within the page template in FirstSpirit

The sections variable will be an array containing all sections within the given slot. They can then be rendered based on their type.

Last update: June 21, 2023