SMP Communications library

The @mediaplatform/communications-library is intended as a communication middleman between the Sportal365 CMS and custom client applications. The library handles the transfer of messages and data between the two parties.

How to run the project

1. Clone the project.
2. Install dependencies with yarn install.
3. Run yarn dev in project root to build the library in dist folder and start the library in the index.html file.

How to install library in client app

1. Run yarn add @mediaplatform/communications-library

Bundling for production

The project is bundled with ⚡ Vite. To make a build run yarn build in project root to generate the production build in the dist folder. An example output will be:

communications-library
└── dist
    └── constants         <-- All messages 
    └── library           <-- The communications library main class
    └── utils             <-- The communications library utility functions

How to use

1. Import the communications library in your file and the corresponding message constants and EventModel model:

  import {CommunicationsLibrary, EVENT_MESSAGE, EventModel, PARENT_DATA} from "@mediaplatform/communications-library" for the third party app;
  
  import {CommunicationsLibrary, EVENT_MESSAGE, EventModel} from "@mediaplatform/communications-library" for the Sportal365 CMS;

Note 1: EVENT_MESSAGE - indicates a message from the communications library has been sent

Note 2: CHILD_LOAD_FINISHED - indicates the child has loaded and ready to receive data from the parent

Note 3: PARENT_DATA - indicates the parent data has been sent to the child

Note 4: EventModel - the format of the callback function sent by the event listener: {type: messageType, data: data}

2. Instantiate the communications library in the client application:

  const communicationsLibray = new CommunicationsLibrary(${targetOrigin});

Note 1: targetOrigin - the url, which points to the parent receiver (Sportal365 CMS)

3. Instantiate the communications library in the Sportal365 CMS:

  const communicationsLibray = new CommunicationsLibrary(${targetOrigin}, ${contentWindow}); 
  

Note 1: targetOrigin - the url, which points to the child receiver (client application)

Note 2: contentWindow - the window of the parent (Sportal365 CMS), which represents the iframe in which the client application is loaded

4. How to initiate the communication between Sportal365 CMS and client application:

    communicationsLibray.initiateHandshake();

Note 1: initiateHandshake() determines whether the communications library is called from the Sportal365 CMS or the client application and listens for communication events between the two parties.

Note 2: If the communications library is an instance of the parent (Sportal365 CMS), it listens for CHILD_LOAD_FINISHED event type and sends data of the parent (Sportal365 CMS) to the child (client application) BEFORE initiating the communication, you must set the data of the parent (custom block) in the communications library instance, so it can be sent to the child.

commsLib.setParentData(${blockData});

Note 3: If the communications library is an instance of the child (client application), it sends message of type CHILD_LOAD_FINISHED to the parent

5. How to send and receive data as a child to and from the parent (Sportal365 CMS):

Note 1: Receiving and handling data from the parent

      communicationsLibray.listenForEvents((evt: EventModel) => {
        if (evt.type === PARENT_DATA) {
	    // Logic in client app that handles the data from the CMS
        }
    })

Note 2: Sending data to the parent

communicationsLibray.sendDataToParent({type: EVENT_MESSAGE, data: ${clientAppData}})

5. How to send and receive data as a parent to and from the child (Client application):

Note 1: Receiving and handling data from the child

      communicationsLibray.listenForEvents((evt: EventModel) => {
		if (evt.type === EVENT_MESSAGE) {
	            // Logic in cms that handles the data from the custom app
		}
	});

6. Closing the connection listeners:

   communicationsLibray.closeConnection()