The first iteration for plug-ins in COYO has arrived and you want to get started? We’ll show you what to do and what you need to keep in mind. 

You add new plug-ins in the Administration under the menu point Apps & Widgets > Widgets >  Add plug-in.

  

A dialog then opens in which you need to enter the link to a manifest URL. Please note at this point the supported manifest versions so that you know which you can use for your plug-in.

  

 

Set up manifest version

A manifest is the cornerstone that contains all of the necessary information for your plug-in and makes it available to COYO. The structure of a manifest is permanently defined and must be stated in a JSON format. Our versions provide you with a guide.

At this point, it’s important that you orient yourself towards one of the versions that your COYO supports and that was displayed to your beforehand in the dialog.

The following fields are necessary and must always be stated:

• manifestVersion
  Enter the version here which is used for validation in COYO. 
• Type: Semantic version as a string
  Example: 0.7.0
• pluginVersion
  Enter the version number of your plug-in here.
• Type: Semantic version as a string
  Example: 1.0.0 
• coyoVersion
  Enter the COYO release version that is at least required for your plug-in. 
• Type: Semantic version as a string
  Example: 1.0.0 
• name
  This is the name of your plug-in, which is used within COYO. 
• Type: Translation map
  Example: name: {"de": "Hallo", "en": "Hello"}, 
• description
  This is the description of your plug-in, which is used within COYO.
• Type: Translation map
  Example: description: {"de": "Beschreibung", "en": "Description"}, 
• data
  Enter here which interfaces are requested by your plug-in from COYO. The following interfaces are currently possible: userId, userName, userEmail, userLanguage  
• Type: array[]
  Example: ["userId", "userName"]

 

entryPoints

You have the option of equipping a plug-in with several entry points, i.e. offering various content per plug-in. Such as for a canteen plan, a menu of the day, a weekly overview and current offers. Please state the following attributes in the object entryPoints.

• Type: object[] 
  .id
  Select any unique ID you like for each entry point. The setup takes place according to the UUID4 format. You can have one generated here: https://www.uuidgenerator.net/version4 
• Type: UUID as a string
  Example: a6725e06-30f2-46c2-a1da-fa7a52a0e454 
• .name
  Enter the name of your entry point here, which will be available for selection when integrating the plug-in. 
• Type: Translation map
  Example: name: {"de": "Tagesplan", "en": "daily menu"}, 
• .description
  Enter the name of your entry point here, which will be available for selection when integrating the plug-in.
• Type: Translation map
  Example: description: {"de": "Liste der Gerichte", "en": "List of our menu"}, 
• .url
  Enter an absolute or relative URL here with the path to the content that should be output when integrating the entry point. 
• Type: URL as a string
  Example: /plugin/johnskitchen 

 

Example manifest: And this is what your manifest could look like:  

{
  "manifestVersion": "0.7.0",
  "pluginVersion" : "1.0.0",
  "coyoVersion" : "27.0.0",
  "name": {
    "de": "John Doe‘s Küche",
    "en": "John Doe’s Kitchen"
  },,
  "description": {
    "de": "Zur Anzeige unserer Gerichte",
    "en": "For embedding a list of our kitchen menu"
  },,
  "data" : [
    "userName"
  ],
  "entryPoints" : [
    {
      "id": "43d4d920-5511-4001-aba5-10c4dfc89c75",
      "name": {
        "de": "Tagesmenü",
        "en": "daily menu"
      },
      "description": {
        "de": "Anzeige der Tagesgerichte",
        "en": "Display the daily menu"
      },
      "url" : "./daily/"
    },
    {
      "id": "88a11a22-c3ef-43ea-b376-459c3c20ea12",
      "name": {
        "de": "Wochenübersicht",
        "en": "weekly overview"
      },
      "description": {
        "de": "Anzeige der Wochenübersicht",
        "en": "Display the weekly overview"
      },
      "url" : "./weekly"
    },
  ]
}, 

 

Build plug-in

Now that your cornerstone is in place, you can start building the plug-in. First, you need the option of hosting your plug-in, e.g. by using a web server. Once this is in place, you create an area such as you own sub-directory, in which you can store your plug-ins (in this manifest example, the plug-in is located in /plugins/johnskitchen/).

The two subfolders "daily" and "weekly" can be found in the directory "johnskitchen" and each contain an index.html. Plug-ins are integrated into COYO as iFrame, which is why you can create your folder structure in the usual way for online matters. 

Example
<!DOCTYPE html>
<html>

<head>
  <title>Daily menu</title>
  <meta charset="UTF-8" />
  <script src="../node_modules/jwt-decode/build/jwt-decode.min.js"></script>
  <script src="../index.js"></script>
</head>

<body>
  <h1>Daily menu</h1>
  <hr>
  <div>
    Hey <span id="userName"></span>, today there is:
    <br />
    ...
  </div>
</body>

</html>

 

In the example, you can see two script integrations. One is our own script document and the other is a JWT decoder to decode the output of COYO. You are welcome to use either of these or your own here. This one here is saved as an npm package jwt-decode. To use the interfaces saved in data in the manifest, please use the method window.postMessage() using JavaScript. What’s important here is that you use the method in the correct format. In the following example, you can see how our script document requests the userName using postMessage: 

const src = window.location.search.match(/[?&]src=([^&]*)/)[1]
parent.postMessage(
{
    source: src,
    topic: 'requestData',
    payload: [
    'userName',
    ]
},, "*"
)

 

The three attributes source, topic and payload must be transmitted to COYO. At this point, the variable src sends an ID to source and COYO uses this to automatically generate a unique UUID. As topic, you select requestData and as payload the data that you want to send. The star at the end is used as the targetOrigin.

 

Request data

To now request the data (message), please use the method window.addEventListener. You do this as follows: 

window.addEventListener('message', function receiveData(event) {
var message = event.data;
if (message.source === 'coyo:app' && message.topic === 'provideData') {
    var jwt = message.payload;
    var userData = jwt_decode(jwt);
    document.getElementById("userName").textContent = userData.userName;
},
},);

 

In this example, the answer can be found in the variable "event." This contains the attribute payload. COYO sends you the requested data in a JSON Web Token, which you can decode yourself or using another library (used here: jwt-decode).

In the example, we then send the userName back to the span element saved in the HTML via getElementById. 

 

Integrate plug-in

Once the plug-in has been fully developed, it just needs to be integrated. To do this, go to Administration, enter your manifest URL, and click on Add plug-in. You will then see your plug-in in the overview. There you can then decide whether it should be activated and/or only available to moderators.

 

 

Now go to the COYO area where you want to integrate the COYO plug-in and edit the layout. Act as if you are adding a widget and open the plug-in tab. You can already see and select your plug-in there.

 

 

After making your selection, you will be asked which entry point and which dimensions you want to use:

 

And, after you save, the result will look like this example:

 

 

Example plug-in

To enable you to also use this example directly if you like, we have created the following repository for you in Github: github.com/coyoapp/johnskitchen.

You can find more information in the plug-in developer documentation.