Getting editorial selections
An editorial selection represents a list of promoted content on FORGE.
Using the back-office, editors can create a promoted list of content, add items to it, and reorder them in the best way to increase fans' engagement.
Like any other editorial item on the system, editorial selections have a unique public identifier that should be used to get their content via DAPI.
In this example, we’re going to learn how to get the content of an editorial selection using its unique identifier (slug).
Assuming there is a published editorial selection with the slug homepage-promoted-content for the “English” language,
we need to build the request as follows:
GET https://dapi-base-url/v2/content/en-US/sel-homepage-promoted-content
Where dapi-base-url must be substituted with the absolute URL of the specific Distribution API instance.
On the above request, it is important to notice that the slug of the editorial selection must be preceded by the prefix sel-;
this applies to all kinds of editorial selections (single and multi-language).
Considering the above sample, to get the content of the editorial selection, you need to combine the prefix sel-
with the actual slug homepage-promoted-content resulting in the combined string sel-homepage-promoted-content.
When an editorial selection matching the provided identifier is found, an output contract similar to the following is returned:
{
"pagination": {
"maxItems": 100
},
"meta": {
"apiVersion": "2.0",
"generatedAt": "2020-07-22T10:14:23.4782503Z"
},
"items": [
{
"type": "story",
"_translationId": "24904094-67ae-4c04-8ea6-51060a08e6a1",
"_entityId": "1fdd46a6-2e9b-4d9f-8557-88b6bed902f8",
"selfUrl": "https://acme.org/v2/content/en-us/stories/a-handful-of-olympic-and-paralympic-rowing-facts",
"slug": "a-handful-of-olympic-and-paralympic-rowing-facts",
"title": "A handful of Olympic and Paralympic rowing facts",
"tags": [
{
"_translationId": "a6f13b8a-cd67-4e9f-82c8-798d47d1c389",
"_entityId": "7458c096-8d65-40a3-b535-f8ba1a08ccfa",
"selfUrl": "https://acme.org/v2/content/en-us/tags/rowing",
"title": "rowing",
"slug": "rowing",
"neutralSlug": "rowing",
"externalSourceReference": {},
"fields": {}
}
],
"createdBy": "Frank Becker",
"lastUpdatedBy": "Frank Becker",
"lastUpdatedDate": "2020-07-22T09:25:58.606Z",
"contentDate": "2020-07-21T07:34:19.442Z",
"featured": 0,
"headline": "Interesting facts about rowing in the Olympic games",
"summary": "The familiar story goes that rowing was included at the first Olympic Games in 1896, but due to inclement weather, the rowing races were cancelled. There were only a handful of countries set to participate, among them France, Germany, Italy and Greece, in just four boat classes. While rowing today",
"thumbnail": {
"title": "2019-05-29-redgrave-pintest-featured",
"templateUrl": "https://images.acme.org/media/image/private/{formatInstructions}/forge/zaxax7s7k6z2lgoyb59x",
"thumbnailUrl": "https://images.acme.org/media/image/private/w_250,h_250,c_thumb,g_auto,q_auto,f_jpg/forge/zaxax7s7k6z2lgoyb59x",
"format": "jpg",
"overriddenFormats": {},
"slug": "2019-05-29-redgrave-pintest-featured",
"selfUrl": "https://acme.org/v2/content/en-us/photos/2019-05-29-redgrave-pintest-featured"
}
},
{
"type": "customentity",
"_translationId": "df94dabe-91af-4ce9-9e79-643409e26551",
"_entityId": "19da4105-7110-4e9e-b8f0-b1a08ebaec96",
"selfUrl": "https://acme.org/v2/content/en-us/youtubevideos/why-should-i-row",
"title": "Why should I row?",
"slug": "why-should-i-row",
"tags": [
{
"_translationId": "a6f13b8a-cd67-4e9f-82c8-798d47d1c389",
"_entityId": "7458c096-8d65-40a3-b535-f8ba1a08ccfa",
"selfUrl": "https://acme.org/v2/content/en-us/tags/rowing",
"title": "rowing",
"slug": "rowing",
"neutralSlug": "rowing",
"externalSourceReference": {},
"fields": {}
}
],
"fields": {
"videoId": "G1EmAFw_wA0"
},
"createdBy": "Frank Becker",
"lastUpdatedBy": "Frank Becker",
"lastUpdatedDate": "2020-05-19T14:14:54.161Z",
"contentDate": "2020-04-06T09:38:24.786Z",
"context": {
"_translationId": "a6f13b8a-cd67-4e9f-82c8-798d47d1c389",
"_entityId": "7458c096-8d65-40a3-b535-f8ba1a08ccfa",
"selfUrl": "https://acme.org/v2/content/en-us/tags/rowing",
"title": "rowing",
"slug": "rowing",
"neutralSlug": "rowing",
"externalSourceReference": {},
"fields": {}
},
"featured": 0,
"thumbnail": {
"title": "1 - SN086zQ",
"templateUrl": "https://images.acme.org/media/image/private/{formatInstructions}/forge/yyd4ehfswo7p878drhu4",
"thumbnailUrl": "https://images.acme.org/media/image/private/w_250,h_250,c_thumb,g_auto,q_auto,f_jpg/forge/yyd4ehfswo7p878drhu4",
"format": "jpg",
"overriddenFormats": {},
"slug": "1-sn086zq",
"selfUrl": "https://acme.org/v2/content/en-us/photos/1-sn086zq"
},
"entityCode": "youtubevideo"
},
{
"type": "album",
"_translationId": "d30f92af-56f0-4f2d-a1b4-3c521425cf9b",
"_entityId": "b05ce183-6bcc-44f4-bf1c-c057ca28903c",
"selfUrl": "https://acme.org/v2/content/en-us/albums/rowing-album",
"slug": "rowing-album",
"title": "Rowing album",
"tags": [],
"createdBy": "Frank Becker",
"lastUpdatedBy": "Frank Becker",
"lastUpdatedDate": "2020-07-22T08:58:46.277Z",
"contentDate": "2020-05-28T16:47:54.215Z",
"featured": 0,
"thumbnail": {
"title": "1 - SN086zQ",
"templateUrl": "https://images.acme.org/media/image/private/{formatInstructions}/forge/yyd4ehfswo7p878drhu4",
"thumbnailUrl": "https://images.acme.org/media/image/private/w_250,h_250,c_thumb,g_auto,q_auto,f_jpg/forge/yyd4ehfswo7p878drhu4",
"format": "jpg",
"overriddenFormats": {},
"slug": "1-sn086zq",
"selfUrl": "https://acme.org/v2/content/en-us/photos/1-sn086zq"
},
"description": ""
}
]
}
The output contract represents the list of the content that has been promoted on the specified editorial selection.
These editorial items can be manually added to the selection (e.g. an editor selecting the content to be promoted) or automatically selected by the system matching some business rules configured on the back office (auto-fill rules).
Auto-fill rules
FORGE enables editors to configure the editorial selection to automatically select the published content based on some rules.
These rules are called “Auto-fill rules” and can be fine-tuned directly from a dedicated panel on the back-office.Users have the possibility to define the maximum number of items to be part of the promoted list, the desired taxonomy, and the type of content that should be selected.
For example, imagine we set up the auto-fill rules as follow:
- Max number of items: 10
- Tags: rowing, jason-osborne
- Entity types: stories, videos, albums
Each time a story, video, or album having at least one of the specified tags (e.g. rowing or jason-osborne) it will be automatically added to the editorial selection after all manually added items.
If the selection already has at least 10 elements (both manually and automatically added), the publication will be ignored and no additional elements will be added to the list.Keep also in mind that the auto-fill rules are applied only on content that has the “List availability” option set to public.
This property is used by editors to instruct FORGE about the visibility of specific pieces of content into lists.
From a consumer perspective, there is no difference between the two types of content.
Also, in this case, the main metadata of each content is returned by the endpoint, ensuring greater flexibility when building up the presentation.
The following Distribution API endpoints have been used on this workflow;
please refer to the specific endpoint page for an in-depth description of the output contract:
| Endpoint | Path | Description |
|---|---|---|
| Get Selection By Slug | /v2/content/{culture}/sel-{slug} | This endpoint returns the list of published items that are part of the specified editorial selection |