Creating a custom block

This tutorial is a step-by-step guide to creating and using a custom block inside of the CMS.

What is the custom block?

As the CMS is used by many different companies, each with its specific business model, it is normal for the client/user to want functionality with their current solution, but not inside the CMS. It is impossible to keep the current Sportal365 service as a general go-to solution with all of the requests, so enter Custom Block.

This feature (custom block) allows users to create their custom functionality and integrate it into the CMS. This is the first step that will pave the way to one of our main goals, making the CMS plugin based. This will allow users to have their custom functionality inside the content body and anywhere they may want in our content management system.

Going back to the custom block. With the current version of this feature, the users will be able to integrate their custom functionality inside of the article body. What do we mean by the article body? The current article body consists of the following blocks, which are available out of the box:

Textual

Paragraph, Heading, Quote, List, Table

Widgets

Odds, Team profile, Squad/Team players, Player profile, Match, Top Scorers, Standings, Player H2H, Team Comparison, Match list by stage/round, Team form, Most decorated players, Player career, Squad statistics

Content

Article, Gallery, Image, Video, Embed, Highlight, Link

All of these blocks make up the article body. Our new feature will create an additional block category: Custom

Every new custom block that is created in our system will be listed in the Custom category, as seen below:

Blocks menu

Custom blocks

Creating a custom block inside of the CMS

To achieve the above-displayed examples, you need to do the following, the feature needs to be activated for you. You can do that by simply writing an email to support@sportal365.com, stating the name of your project and for which environments you want this activated: sandbox or production, or both. After the feature has been activated, follow these instructions

1. Getting to the custom block creation screen

To create and configure a new custom block go to https://cms.sandbox.sportal365.com/#/smp/custom-blocks for the sandbox environment or https://cms.sportal365.com/#/smp/custom-blocks for production. You will be presented with the custom block listing screen. A little bit of information about this screen.

1.1 Searching for blocks

The custom block listing screen will display all of the previously created custom blocks, there you can filter them using the search. The search is performed using the block title

The search is automatically performed when you input text, so you will be able to see your result at the moment of writing.

1.2 Deleting blocks

Each listed block can be deleted, by pressing the delete button as seen in the image below:

NB! When you delete a custom block it will immediately disappear in the CMS and won’t be available for use.

1.3 Creating a custom block

And now the functionality that you are interested in. You can create a custom block, by clicking New Custom block

After clicking on this button you will be redirected to the following page https://cms.sandbox.sportal365.com/#/smp/custom-blocks/create for sandbox or https://cms.sportal365.com/#/smp/custom-blocks/create for production.

2. Configuring a custom block

The custom block has a pretty simple configuration. Overall four fields need to be configured

2.1 Block name

This is the name of the block, it will be displayed by this name in the custom blocks listing screen and the blocks menu inside of the block menu for the article body.

2.2 Application URL

This is the URL where you have hosted your solution which will be used inside of the custom block.

2.3 Custom block icon

The block icon is also important as it is a visual identifier that will help the editors locate your custom block fast.

This configuration uses font-awesome icons, the only thing that we require is for you to input the proper font-awesome icon name, following this syntax:

fa fa-trash

If the proper icon name is used we will display the icon on the right side of the input field, this way you will know that we support the icon that you want to use and it will be displayed.

2.4 Custom block status

The custom block visibility inside of the CMS can be controlled using the status dropdown. When you set the block status as inactive and save the configuration it will be removed from the list of blocks that can be used and vice-versa.

Conclusion

After finishing all of the above-mentioned steps, you have successfully created a block inside of the CMS and it is ready for use by anyone interested.

Communication between CMS and client solution

As already mentioned, to create a custom block inside of the CMS, you need to have a javascript application hosted somewhere. The reason why we need the application to be written in javascript is that the communication between the CMS and your solution happens through the messaging system provided by the window object, you can find a bit more on the topic here https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage .

This diagram will give you a bit more insight into the entire lifecycle of the overall solution, CB - Custom Block

Messaging

As you can see in the diagram above, the communication between the CMS and your solution is two-way.

The structure used for the communication is the following

{
  "data": {
    "msg": <event_sent>,
    "payload": <config that will be stored in the article body>
  }
}

There are three types of messages sent:

sportal365_custom_event - This message is sent from the custom block to the CMS
Example:
{ "data": { "msg": "sportal365_custom_event", "payload": "{\"apples\":3, \"oranges\":2}" } }
When this message is sent, the CMS will respond with the next type of message
sportal365_custom_event_callback - This message is always sent back to the client application so that the client can confirm that the data has been stored in the CMS successfully.
Example:
sportal365_custom_event_onload - This message is sent when an article containing the custom block is opened (edited) in the CMS. The stored data is sent back to the client javascript app so that the proper configuration can be displayed to the editor.
Example:

Sample code

Now that you have a general idea of the types of messages sent back and forth we can continue with some sample code.

Passing information to the CMS

This can easily be done by using the window.parent.postMessage(…) function as seen below

Receiving information from the CMS
List of CMS origins:
1. Sandbox - https://cms.sandbox.sportal365.com
2. Production - https://cms.sportal365.com

Conclusion

As you can see the overall communication between the CMS and your application is pretty simple. As always if any questions arise, do not hesitate to contact us via our support: support@sportal365.com.

Happy programming!