What's next?

Custom entities
  • Updated

In this article, we cover FORGE's capabilities for defining new and bespoke custom entities to build content faster.

Topics covered here:

Out-of-the-box entities

FORGE provides the editorial teams with the following entities:

  • Story: Together with photos, stories are the main building blocks to assembling content. A story is a collection of story parts, which can be either text or any other type of editorial entity.
  • Photo: The other main building block that, with stories, makes up the content.
    FORGE relies on Cloudinary for photos storage: all formats Cloudinary supports, FORGE supports. Size limits depend on the Cloudinary paid plan, which is a choice of the digital project based on FORGE.
  • Album: A collection of photos.
  • Document: Any file. Administrators configure the allowed file formats and sizes.
  • Editorial selection: A collection of entities grouped‌ into an entity, which is called editorial selection.
    Editorial selections contain different editorial entity types. E.g., they collect stories, photos, and documents together.

Custom entities

Administrators and producers can create custom entities and use them in stories and as items in editorial selections. These custom entities are not available out-of-the-box.

The following screenshot shows a list of possible custom entities:

Permission-based visibility and management

For each custom entity C, a permission Wcm.View.CustomEntity.C exists that editors must have to see and use that specific custom entity in:

  • Menus
  • Lists

Editors need the additional permission CanOperateOn.Wcm.C to create, edit, and delete the custom entity C.

Editorial workflow

Custom entities are published or unpublished in all languages, but editors can select ‌visibility per language. E.g., a published document can be visible in the front-end in English but not in French.

Find more details in Translations with language-independent workflow.

User interface

Each custom entity has a dedicated overview page that editors can access by selecting its menu item in the left menu. See Searching entities for more information about searching through custom entities, which work like ‌built-in entities. 

E.g., in the screenshot below, there's the player's overview page:

By selecting New or a custom entity from the overview page, editors enter the custom entity edit page. E.g., in the screenshot below, there's the player's edit page:

Custom entities are made up of

Custom properties

In the center, editors can fill in the entity-specific fields.

Main properties

Custom entity's built-in main properties are:

  • Thumbnail: By default, it's the document file type icon. Editors can replace it with any photo.
  • Entity code: Read-only unique entity identifier.
  • Slug: Human-readable entity identifier. If the document isn't published, editors can edit it.
  • Content date: By default, it's the publishing date. Editors can edit it.

History

Like for any entity, this section lists for each change who, what, and when.

General settings

Editors can select:

  • Authorization group: Select the authorization group that editors must have to edit the document.
  • List availability: Select whether the document must be included into lists that the front-end queries. See List Availability for more information.

Context and tags

Editors can select:

  • Context: Text that appears above an article on the front-end. It's a small, but important piece of text which highlights the key features of the content.
  • Tags: Document's taxonomy.

Promotion

Editors can promote the document's visibility by leveraging:

  • Feature the content: Flag that makes a document featured. This flag informs the front-end that the document's visibility has a higher priority than not-featured ones.
  • Add to selections: Add the document to one or many editorial selections.

Relations

Editors can relate the document to other entities regardless of their type.

User interface configuration

In Administration->Configuration->Custom Entities, administrators can configure the custom entity user interface within the JSON definition by

  • Grouping together fields into sections
  • Positioning fields

Grouping together fields into sections

In the custom entity JSON schema, define the list of groups to display within the groups array at root level. The following parameters define a group:

  • key: It identifies the group. It's used to assign a field to this group.
  • label (optional): It's the group label the user interface displays.
  • icon (optional): It's the group's icon code. Refer to Google Fonts to search for icons and their codes. 

For example, the JSON below defines two groups. The first group (key = player-basics) uses the icon with person_outline code. The second group doesn't have an icon.

{
 ...,
 "groups": [
  {
   "key": "player-basics",
   "label": "Player",
   "icon": "person_outline"
  },
  {
   "key": "player-photos",
   "label": "Photos"
  }
 ]
}

Then, assign custom entity fields to groups by setting their groupby parameter with the group key.

For example, the JSON below assigns the firstname field to the player-basics group:

{
 ...,
  "firstname": {
   ...,
   "groupBy": "player-basics",
   ...
 },
 ...,
 "groups": [
  {
   "key": "player-basics",
   "label": "Player",
   "icon": "person_outline"
  },
  {
   "key": "player-photos",
   "label": "Photos"
  }
 ]
}

Positioning fields

Administrators can span custom entity fields into 12 columns per row. For each field, the columns parameter defines how many columns the field spans. When the sum of the columns exceeds 12, the field displays in the next row.

For example, in the JSON below, fields firstname, lastname, and dateOfBirth are displayed in the same row (4+4+4 = 12) of the player-basics group: 

{
 "firstname": {
  ...,
  "groupBy": "player-basics",
  "columns": 4
 },
 "lastname": {
  ...,
  "groupBy": "player-basics",
  "columns": 4
 },
 "dateOfBirth": {
  ...,
  "groupBy": "player-basics",
  "columns": 4
 },
}

Instead, in the JSON below, fields firstname and lastname lays in the same row (6+6=12) of the player-basics group. In contrast, within the same player-basics group, dateOfBirth displays in the next row and spans the first 4 columns:

{
 "firstname": {
  ...,
  "groupBy": "player-basics",
  "columns": 6
 },
 "lastname": {
  ...,
  "groupBy": "player-basics",
  "columns": 6
 },
 "dateOfBirth": {
  ...,
  "groupBy": "player-basics",
  "columns": 4
 },
}

Related articles