npm package: @mediaplatform/communications-library
Description: 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.
Author: smp@sportal.bg
Latest version: 1.0.4

# 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](https://vitejs.dev). To make a build run `yarn build` in project root to generate the production build in the dist folder. An example output will be:

```bash
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()
```