Developers - Oversite
Data-pf attributes
After having installed Oversite script into your application, you need to add the necessary data attributes to your HTML elements for Oversite to interpret.
There are three types of attributes that Oversite needs for different functionalities:
Using data-pf attributes
The data-pf attribute stores a configuration for a given page, section or component. The value inside is a JSON string and it contains various properties described in the table below. Here is a generic example for a component.
Make sure the value of data-pf is a valid JSON object with double quotes.
<div data-pf='{"providerId": "my-content-provider", "componentKey": "card", "groupId": "001", "instanceId": "xFrt5f6", entryId": "abc1234"}'></div>
Available Properties
| Property | Usage | Description |
|---|---|---|
pageId | Unique identifier of a page | Required if you want to use Global/Local options, make a page unique by its id. |
title | Friendly Name in the Editor | A user friendly title to differentiate components. Visible in outline tabs and the editor title |
providerId | Enable Deep links | Enable deep links with a configured provider Id (Page, sections, components) |
sectionId | Enable Section Designer | Enable Section Designer on a given section |
componentKey | Enable Component Designer | Enable Component Designer and make link with configured component Id synced with CLI |
groupId | Enable Component Grouping | Make relationship between similar component, needed for individual styling vs group styling |
instanceId | Enable Component Grouping | Required if you want to use Group/Component options, make a component unique by its id |
| Others | Deep links tokens | Other values to be used in URL pattern for deep links activation (e.g EntryId, locale, contentType…) |
Attribute types
1. Page
The page attribute is a single data-pf attribute on the <body> tag. The value for this attribute should be at least a unique identifier of the page you are rendering. It is a free text value allowing you to insert any kind of identifier, like the page slug, ID, or any other identifier that is best suited for your solution. This attribute is used to differentiate pages and content/styling stored in our platform.
<body data-pf='{"pageId": "unique-id", "providerId": "my-content-provider", "entryId": "abc1234"}'></body>
You can also have Deep Links enabled at page level by adding providerId and other properties requested by a provider.
2. Sections
Controlling the Layout of your page works based of Sections. Sections are parts of your page that contain one or more Components such as grids and carousels.
When using Sections, the immediate child elements of the element you tag should be one or more Components.
You configure a section by adding a JSON object containing a sectionId and a title in a data-pf attribute to the HTML element you want to assign as a Section.
<div data-pf='{"sectionId":"1", "title": "Hero Section"}'>
<!-- Insert Component(s) -->
</div>
You can also have Deep Links enabled at section level by adding providerId and other properties requested by a provider.
3. Components
Assigning the data-pf attribute to your components will allow you to deeplink into the CMS, highlighting of each individual component, and enabling component related Oversite features like commenting.
You configure a component by adding a JSON object to the data-pf attribute on the top element of your component's HTML. This JSON object should contain the following properties:
providerId- Refers to the ID of the Provider in Oversite which stores the content displayed.componentKey- Refers to the ID of the Component set in theme.json.title- A user friendly title to differentiate components with for the editor.groupId- A field used to group stylings of components. Components that should always show in the same way, should have the same value. Components that have unique styling on your page, should have a unique value.- Others.. - You can add other properties to the object based on what you need. For example, if the Provider requires an
entryIdfor deeplinking purposes, this is where you should specify the value for that property.
Take the following HTML snippet as an example:
<div data-pf='{"providerId": "my-content-provider", "componentKey": "hero", "title": "Campaign Hero", "groupId": "abc1234", "instanceId": "123456, "entryId": "abc1234"}'>
<h1>Hero Title</h1>
<p>Hero Description</p>
</div>