Introduction

One of the benefits of Cortex is that the most common content requirements you may have for a sports app or website are provisioned by pre-defined content models: sponsors, text, image, video, live blog, poll, and more are available out of the box. However, if you have a requirement that sits outside of these presets, the option of creating a custom content block is also available.

From the developer perspective, creating a custom content block essentially allows you to define the structure of your own JSON response.

Who should use custom content?

Custom content blocks source from the fields and settings entered into Cortex. For that reason, this document presents the tools and methods available in creating a custom content block in Cortex. However, although the block is built within Cortex, it generally requires the expertise of a developer to ensure correct outcomes.

Please do note that custom content blocks will need to be integrated across all your platforms. A custom content block created for the web, for example, will not necessarily display on your app without integration work. Similarly, it may need to be ported to both Android and iOS. Please do plan custom blocks carefully to ensure all eventualities are accounted for.

Creating custom content blocks in Cortex

1. Log in to Cortex. On the left-hand side, click Content and then select the Settings icon (⚙️)
2. You are presented with the Settings screen. Select the Custom Content Blocks tab.

Here you can select from the custom content blocks already created or click New custom content block to create a new one. You are then presented with the Custom content block edit screen. This example is entitled the Player Profile Custom Content Block.

3. Give your content block a name and a description, and assign it a Status, noting carefully the meaning of each:

• Draft is the creation mode in which all changes are accepted, but the block is not available to view or trial within an article while in Draft status.
• Testing is a mode in which the block can be used and displayed within an article, but further changes can be made as necessary and the block can be returned to Draft mode.
• Published. Once the block is published elements of its structure are set in stone and - note carefully - no further changes can be made to those elements. This is because, once the block is finalised, there is a degree of integration and porting work that must take place to use the block, so any further changes to key elements will require an integration/porting exercise to be carried out again. It is therefore important to manage releases and versions of the block to ensure its integrity for the user.
  • What cannot be changed: Once the block is published, you cannot change the block name, field types or field names, and you cannot remove a field. Once published, it is also not possible to return the block to a status of Test or Draft.
  • What can be changed: Once the block is published you can still change the block description, the subheading of a field, the field validation (whether or not it is a required field, the list of options that can be selected in a dropdown, the minimum and maximum number of characters), the sort order of the fields, and you can add new fields.
• Deprecated. This ‘retires’ the block; however, all existing articles that use it will continue to function. It will no longer be offered as a content option within Cortex.

4. There is also a toggle switch entitled Nested only. All custom content blocks can be nested within other custom blocks. However, toggling Nested only to On means this content block can ONLY be used as a nested block. It can not be used as a standalone block.
5. You can now begin to customise your content block by adding fields. To do this, click Insert field at the bottom of the Custom content block edit screen.
6. You are invited to select your field type from a list:

The available fields are as follows:

• The Input field allows the user to insert free text or a numeric value into a field.
• The Select field creates a list of options from which the user can choose.
• The Default block allows you to select from all the existing standard blocks available in the orthodox content creation process; image, text, video, poll, live blog and so on.
• A Nested block is the option to introduce an existing custom content block from those already created.
• The Content ID field allows the selection of an item of content, identified by it’s ID.
• The Linked ID field pulls in data from third party providers, such as Opta.

In terms of the JSON, a nested block, content ID and linked ID are all arrays, i.e. there could be multiple values

Blank values are handled in different ways:

• A blank input field provides a ""
• A blank select field provides a null
• A blank default block provides a {}
• A blank nested provides a []
• If the Content ID field is left blank then it is omitted.
• If the Linked ID field is left blank then it is omitted.

7. Click Save. Now, when building an article or page in Cortex, whenever you choose Custom as your content option, as shown in the screenshot below, the custom content blocks you have created will be available for use.

Custom block creation - best practices

Custom content blocks can be powerful additions to your fan-facing web and app presence, however they should also be created with care and developer discipline if they are to function correctly. Below are some recommended best practices in building custom content blocks.

1. Check carefully that what you are looking to achieve is not already covered in the standard features of Cortex.
2. Complete the block and field descriptions with a comprehensive explanation of the intention behind it in order to ensure the user understands the block and uses it appropriately.
3. Field names, descriptions, and values should use sentence case to be consistent with the rest of Cortex. For example “First name” is preferred to “First Name”.
4. Do not hesitate to contact your Cortex administrator or account manager for help with creating custom content blocks. Working with us can help ensure the development is smooth and the outcome is successful.

A custom content block and JSON response example

This section provides a complete example of a custom content block creation for a Player of the match block. It details all the fields and shows the JSON that is generated.

Block title: Player of the match

Block description: Add this to an article to showcase the player of the match

Created block - JSON output

{
  "id": "f9c472e9-3e68-48f8-9b44-e3fb50729ce4",
  "contentType": "CUSTOM",
  "customContentType": "651fcac63851bfbbbc03ff6f",
  "customContent": {
    "fixtureLinkedId": {
      "linkedIds": [
        {
          "sourceSystem": "OPTA_FOOTBALL_MATCH",
          "sourceSystemId": "2258214",
          "text": "England Women v Germany Women (2022-07-31)"
        }
      ]
    },
    "matchReport": {
      "articleIds": [
        "736c226d-4f85-4c51-8108-17c2d17414a0"
      ]
    },
    "name": "C Ortex",
    "position": "Forward",
    "profileImage": {
      "image": "https://media-cdn.incrowdsports.com/4db92cef-018c-4b92-8435-26f21a571d05.jpg?crop=1890%3A2835%3Anowe%3A602%3A809"
    },
    "shirtNumber": "10",
    "stat": [
      {
        "statNumber": "2",
        "statName": "Goals"
      },
      {
        "statNumber": "1",
        "statName": "Assists"
      }
    ]
  },
  "sourceSystemId": "651fcac63851bfbbbc03ff6f"
}