Integrate custom frontends into the CMS

The CMS provides a way to dynamically integrate external custom frontends into a dedicated side menu' voice.

To integrate this functionality there are steps to follow, all through the API Console.

Integration requirements

Following the requirements to integrate this functionality:

Note that this guideline is base on the Console version 5 and CMS version 7.x.x

Integration steps

Following the steps to integrate this functionality into the desired CMS.

All the steps to do are on the Console

1. CRUD - cmsmenu creation

First of all you need a collection named cmsmenu where to insert the menu voices you want to create:

  1. Click on CRUD
  2. Click on Create new CRUD
  3. Create the CRUD with the following data:
    • name: cmsmenu
    • description: insert a custom description
    • rows:
      • name: String (Required)
      • _oder: Number
      • icon: String (Required)
      • link: String (Required)
      • iframe: Boolean (Required)

2. Service - create the custom service for your frontends

You also need to add the custom service of the frontends that you want to integrate into the CMS; note that the service must be already Dockerized.

  1. Click on Services
  2. Click on Create new service
  3. Select Create from an existing Docker image
  4. Create the service with the following data:
    • name: the name of your service
    • Docker image: the url of your docker image
    • description: insert a custom description
    • the result will be something like this

3. Endpoints - create the endpoints

The CRUD and the service are not reachable until you create the corresponding endpoints through the following steps:

  • cmsmenu endpoint:

    1. Click on endpoints
    2. Click on Create new endpoint
    3. Create the endpoint with the following data:
      • base path: cmsmenu
      • type: CRUD
      • description: insert a custom description
      • the result will be something like this
  • custom service endpoint:

    1. Click on endpoints
    2. Click on Create new endpoint
    3. Create the endpoint with the following data:
      • base path: /custom-service-path
      • type: Custom Microservices
      • description: insert a custom description
      • Remember to unflag the two fields Support JSON format on request and Support JSON format on response
      • the result will be something like this

4. CMS configurations (optional)

If you want to manage the custom menu configuration through the CMS you can create a page linked to the CRUD cmsmenu collection. This step is optional and not needed for the integration but useful to manage the configuration.

  1. Click on CMS and Analytics
  2. In the submenu, click on CMS
  3. Click on Create new page
  4. Create the page with the following data:
    • name: the label that you want to visualize
    • endpoint: /cmsmenu
    • category: the category in which you want the page
    • icon: insert the name of a Fontawesom Icon, without the fa prefix (e.g. bell for the notification bell)
  5. Click on the Next button
  6. Select the table Layout and eventually the group expression for the accesses
  7. Finish, the result will be like this

5. Collection cmsmenu - insert data

It's time to insert the menu data in the cmsmenu collection to make the voice of the menu visible.

name: the name you want to visualize in the menu

_order: the order of the page inside the category

icon: the name of the icon visible in the menu

link: the endpoint created for the service (and the path you want to reach in your frontend)

iframe: true if you want to open the frontend in the iFrame, false if you want to open in another tab

To do this you have two ways:

  • insert the data in the CMS in the cmsmenu collection: insert a new object specifying the fields.

    Example of the Push Manager service:

    • name: Push Manager
    • _order: 1
    • icon: bell
    • link: /v2/push-manager-fe/
    • iframe: true

    In this case the frontend is called in the path /. If we wanted to reach the path home you need to put this path in the link: /v2/push-manager-fe/home.

    Publish your content with the publish button.

  • make a POST to the cmsmenu endpoint with the following body:

    Example of the Push Manager service):

    {
        "name": "Push Manager",
        "_order": 1,
        "icon": "bell",
        "link": "/v2/push-manager-fe/",
        "iframe": true,
        "__STATE__": "PUBLIC"               
    }
    

6. Backoffice proxy - Advanced configuration

The last step is to configure the route to go in the correct service. To do this you need to go in the advanced section of the console and manage the Api Gateway backoffice files. The extensions to customize are:

  • maps-proxyBackofficeName.before.map to map an endpoint to a service name.

    Example for the Push Manager service:

    "~^secreted-1-GET-/v2/push-manager-fe/" "push-manager-fe";
    "~^(secreted|unsecreted)-(0|1)-\w+-/v2/push-manager-fe/" "unauthorized";
    
  • maps-proxyBackofficeUrl.before.map to proxy an endpoint to another url.

    Example for the Push Manager service:

    "~^GET-/v2/push-manager-fe/(?<path>.*|$)$" "$path";
    

According to your use case you can put the customization in both before or after file.

To customize these files:

  1. Click on Advanced
  2. Click on api-gateway
  3. Search maps-proxyBackoffice
  4. Customize the configurations
  5. Save and commit

It's time to deploy the configuration.

Result

Once the configuration is deployed you will see the result in the CMS as follows