Contentful

Overview

Contentful is a headless CMS platform that you can use out-of-the-box with the Storefront Application. For more information on the features of Contentful itself, refer to the Contentful documentation.

Storefront Integration

The Contentful integration with the SCAYLE Storefront Application can be separated by concerns of local development (using contentful-cli) and shop runtime (using Contentful Delivery API).

Initial Development Setup

The initial setup of Contentful within the SCAYLE Storefront Application requires the creation of a dedicated local .env.contentful file. This file will contain all Contentful-relevant environment variables necessary to work with the Contentful Management API.

Copy

• Create a CONTENTFUL_MANAGEMENT_TOKEN: This token can be created as part of your Contentful account settings.
• Source the CONTENTFUL_SPACE_ID: The CONTENTFUL_SPACE_ID can be found in General Settings once you are logged into Contentful. For more information on finding your Contentful space ID, see in the Contentful Guide.

Scripts

As part of the Storefront Application's package.json, some additional scripts are included to interact with Contentful:

• contentful:download: Uses contentful-export to download all data from the respective Contentful space. You can modify it as needed. Data will be stored in contentful.{SPACE_ID}.json inside the root directory of your application.
• contentful:generate: Running this command will generate all type definitions from your contentful.{SPACE_ID}.json as well as some type guard functions, using cf-content-types-generator. The generated types will be located inside ./modules/cms/providers/contentful/types/gen.

Type Definitions

• Manual type definition: ./modules/cms/providers/contentful/types/contentful-defs.d
• Generated type definition: ./modules/cms/providers/contentful/types/gen/*

Shop Runtime Integration

The runtime integration between Contentful and the Storefront Application uses the Contentful Content Delivery API.

1. Set CMS Provider: To use Contentful with the Storefront Application, set the CMS provider to contentful in your nuxt.config.ts:

typescript

Copy

2. Provide API Credentials: To access the Contentful Content Delivery API, you need to provide an accessToken and spaceID as environment variables:

Copy

After adding environment variables to your .env, your integration is complete.

3. Runtime Configuration (Optional): You can also modify your accessToken and space in runtimeConfig to override environment variables:

typescript

Copy

The integration additionally relies on the @nuxt/image module (see the Nuxt Image module documentation) to handle images used with Contentful components.

Live Preview

The Preview Delivery API is used during the initial load to display unpublished changes in the Contentful editor. To accomplish this, an additional preview access token is required. Without it, unpublished changes will only be visible after they are published in the editor.

To enable the preview token in your runtime configuration:

typescript

Copy

When setting up the preview URLs within Contentful, also add the query param ?_editorMode={entry.sys.updatedAt} to the URL. This action informs the site to bypass the cache and load Contentful's live preview SDK seamlessly.

Deployment Requirements

Our implementation provides integration with the Nuxt RuntimeConfig functionality. This means that NUXT_PUBLIC_CMS_ACCESS_TOKEN and NUXT_PUBLIC_CMS_SPACE can be set during the application's runtime as environment variables instead of during build time, enhancing deployment flexibility.

Auto-Imported Components

Contentful components are auto-imported from the ~/modules/cms/providers/contentful/components directory. To prevent component name collisions, we added the prefix CMS to every component. For example, a component named Image would be used as <CMSImage>.

Ready Components

The following components are implemented as part of the Storefront Application, meaning they are available out-of-the-box for all shops that are built upon this foundation:

• Accordion
• AccordionEntry
• Banner
• BannerLink
• ClickableImage
• Image
• Link
• Text
• Video
• DetailImage
• Grid
• GridTile
• ImageSlider
• ImageSliderSlide
• ImageText
• Page
• Product
• ProductSlider
• ScrollableLinkList
• SlideShow
• Story
• ContentfulLink

The current implementation will add 'CMS'prefix to every component so when you are using components inside of a template you should use:

html

Copy

Fetching Content

The Storefront Application provides simple ways to fetch content from Contentful.

• useCMS() Composables: As content from Contentful allows references to data provided by SCAYLE (e.g., product data), the Storefront Application features the useCMS composable. This composable internally relies on the contentful package to fetch content.
  An example usage for getting relevant content might look as follows:

Copy

const { data, status, } = useCMSBySlug<TypeContentPageSkeleton>( `content-page-${props.slug}`, { content_type: 'contentPage', 'fields.slug[match]': `content/${props.slug}`, }, )

• The useCMS composable exposes the following data and functions as dedicated composables:
  • useCMSBySlug: Wraps around Nuxt's useAsyncData function using the contentful package to fetch Contentful content by slug (a user-friendly and URL-friendly string used to identify content).
    • The Contentful entry you are fetching must have a slug field and value that matches what you are trying to fetch.
  • useCMSByFolder: Wraps around Nuxt's useAsyncData function using the contentful package to fetch Contentful content by slug (a user-friendly and URL-friendly string used to identify content) for a folder.
    • The Contentful entry you are fetching must have a slug field and value that starts with the slug you want to fetch.
  • defaultCMSOptions: Returns default options for fetching, such as locale, env, etc.

Basic Composables and Helpers

The Storefront Application includes a few simple reusable composables and helpers to simplify the usage of certain functionalities with Contentful components:

• useCMSAligment(): Provides Tailwind-compatible alignment classes for Contentful components.
• useContentfulImage(): Provides utilities to process and return a sanitized teaser image object for Contentful components.
• useContentfulMargins(): Provides Tailwind-compatible margin classes for Contentful components.
• useCMSListingContent(): Returns a formatted object for usage with listings containing the CMS content, preListingContent, postListingContent, and hasTeaserImage.

Components

This section offers a detailed overview of various shop areas utilizing Contentful content, alongside their options. It's essential to review the type definitions (./modules/cms/providers/contentful/types/gen/*) for actual values and expected data types.

Homepage

Component: SlideShow

Component: Slide

Component: ImageSlider

Component: ImageSliderSlide

Component: Grid

Component: GridTile

Component: ImageText

Component: ProductSlider

Component: Banner

Component: Entry

Footer

Component: Footer

Component: LinkGroup

Component: Link

Listing Pages

Component: ListingPage

Service Pages

Component: Accordion

Component: AccordionEntry

Content Pages

Component: Content Page

Parameter	Details
uid?	string
teaserImage?	Asset
teaserImageMobile?	Asset
headline?	string
subline?	string
content?	Copy Array<TypeAccordionSkeleton

Copy

| | seo? | TypeSeoSkeleton |

All Pages

Component: Video

Component: ClickableImage

Component: Image

Component: Text

Component: DoubleColumn

Component: Paragraph

Component: settings - tracking

Component: settings - margin

Component: settings - seo