The first iteration for plug-ins in Haiilo 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 Haiilo. 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 Haiilo 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 Haiilo. - 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 Haiilo 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 Haiilo. - Type: Translation map
Example: name: {"de": "Hallo", "en": "Hello"}, - description
This is the description of your plug-in, which is used within Haiilo. - Type: Translation map
Example: description: {"de": "Beschreibung", "en": "Description"}, - data
Enter here which interfaces are requested by your plug-in from Haiilo. 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 Haiilo 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 Haiilo. 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 Haiilo. At this point, the variable src sends an ID to source and Haiilo 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. Haiilo 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 Haiilo area where you want to integrate the Haiilo 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.