Managing content with 'scopes' and 'requiredScopes'
Use 'scopes' and 'requiredScopes' to define which store sections can be added to specific pages, ensuring proper content structure for your store.
scopes and requiredScopes are Headless CMS schema definitions that determine which store sections can be added to specific pages (defined within Content Types).These features help manage the content structure and ensure store sections are used in appropriate contexts. For example, the Hero component is only available for the home page or pages like the Product Details Page (PDP).
Before you begin
Update the @faststore/core package version
Make sure you have
@faststore/core version 3.0.18 or greater to benefit from this feature. If you don't have the updated package, follow the instructions in Updating the @fastore/core package version.Set Headless CMS
Make sure to have set the Headless CMS files
content-types.json and sections.json in your store project by following the Setting up the Headless CMS guide. These files contain the store’s custom Content Types and sections.scopes
scopes are labels that define the context provided by a Content Type. They help categorize Content Types based on their capabilities.The
scopes are string arrays within the definition of your Content Type in the content-types.json file. For example:
_10{_10 "id": "home",_10 "name": "Home",_10 "scopes": ["home"],_10 "isSingleton": true,_10 "configurationSchemaSets": [...]_10}
In this example, the
Home Content Type stores content for your home page and has a scopes named home. This scopes definition means that only sections designed for the home page context can be used with this Content Type.Default FastStore scopes
When creating custom sections, you can restrict their usage to specific Content Types using these default scopes:
scopes name | Content Type |
|---|---|
custom | Landing Page |
global | Global Sections |
landing | Landing Page |
pdp | Product Details Page |
plp | Product Listing Page |
search | Search Page |
requiredScopes
requiredScopes defines the Content Types a section can be used in. Similar to scopes, they are specified as string arrays within the section definition in the sections.json file.A section is only available for a Content Type in Headless CMS if the Content Type
scopes include at least one matching scopes from the section's requiredScopes. Sections without any requiredScopes can be used in any Content Type.In the following example, the
ProductShelf section is only available for PDPs:
_10{_10 "name": "ProductShelf",_10 "requiredScopes": ["pdp"],_10 "schema": {...},_10}
Empty requiredScopes
When a section has an empty
requiredScopes ([]), the section is available for all Content Types. In the following example, the Navbar section is available to use in any Content Type because it has no required scopes:
_10{_10 "name": "Navbar",_10 "requiredScopes": [ ],_10 "schema": {...}_10}
Default FastStore requiredScopes
When creating custom sections for Headless CMS, you can use these default
requiredScopes for specific Content Types:requiredScopes name | Section name |
|---|---|
custom | CrossSelingShelf |
pdp | CrossSelingShelf, Breadcrumb, and ProductDetails |
plp | Breadcrumb and ProductGallery |
search | ProductGallery |
Using scopes and requiredScopes
In the following example, let’s set a new Content Type
Custom Page to display a new Call To Action section.
To better understand this tutorial, make sure you create the newCall To Actioncomponent by following the instructions in the Creating a new section guide.
Setting up the Headless CMS files
Make sure to have set up the Headless CMS filescontent-types.jsonandsections.jsonin your store project by following the Setting up the Headless CMS guide. These files contain the store custom Content Types and sections.
-
In the
content-types.jsonfile, create a newCustom PageContent Type by adding the following:We defined the"scopes": ["custom"]for the newcustomPageContent Type. Thecustomscope is also thelandingPagedefault scope defined in FastStore. -
In the
sections.jsonfile, add the following:
We defined that the
Call To Action section will only be available for customPage and landingPage Content Types.Remember that theCall To Actionsection is also available for thelandingPageContent Type because thecustomscope is default for it in FastStore.
When editing the
Custom Page Content Type, the Headless CMS checks its scopes (custom) and matches them against the sections' requiredScopes (custom). Since the Call to Action section matches the Custom Page and Landing Page scope, the section is available to use in these two Content Types.Syncing the Headless CMS changes
-
Open the terminal and run
yarn cms-syncto sync the new files created in the previous step. -
In the VTEX Admin, go to Storefront > Headless CMS, and open the FastStore project.
-
Click on the
Create Documentdropdown. -
Click on
Custom Page:
-
In the
Sectionstab, click onAdd Section(+). -
Select the Call To Action section.
-
Set the section fields as you wish.
-
Click
Save. -
Click
Previewto preview the saved content. You will see a section similar to the image below with a title Shop deals in Fashion and a Call To Action buttonSee all deals.