Plug-ins

Watch out!
We have moved all plug-in related documentation to our new COYO developer hub at https://dev.coyoapp.com/. Please refer to the guides there and don’t use this documentation any more. It will be removed in the near future. If you have any questions, feel free to raise them at https://dev.coyoapp.com/discuss. We are happy to help.

Plug-ins are a way of integrating third-party content into COYO, allowing a seamless display of information and extending the features COYO offers. It is an important concept and yet another powerful way to customize the functionality of a COYO installation. Plug-ins can be as simple or as complicated as you need them to be, depending on what you want to do. The simplest possible plug-in is a static web site.

Please note that plug-ins are a relatively new addition to the COYO ecosystem and both this documentation as well as the implementation might not cover every use case that we would like to cover in the future.

Plug-in architecture

Plug-ins are independent small web applications that are hosted separately from COYO. A plug-in is not limited to the integration in a specific COYO instance but can be used in many different installations. It is completely up to the plug-in developer how complex the plug-in is and how and with which technology it is implemented. Each plug-in is embedded into COYO via iFrames and the exact details on how that works is described in the sections below.

The plug-in manifest

The plug-in manifest is a JSON file that contains all relevant information to install a plug-in in a COYO environment. Each plug-in must therefore necessarily have at least one plug-in manifest. Although COYO stores a local copy of the manifest in the database when a plug-in is installed, it makes sense to host and publish the manifest under the same domain as the plug-in.

The structure of the manifest is defined in an accompanying JSON schema. You can find all schemas at https://download.coyoapp.com/release/plugins and might want to test your own plug-in manifest using a tool like the JSON Schema Tool. While the final definitions should always be looked up in the latest JSON schema file, here is a list of the most important fields of a plug-in manifest:

Attribute

Type

Description

Attribute

Type

Description

manifestVersion*

Semantic version
e.g. 1.3.0

The version that the plug-in manifest is validated against.

pluginVersion*

Semantic version
e.g. 0.7.2

The version of the plug-in itself.

coyoVersion

Semantic version
e.g. 27.2.0

The minimum required COYO version for this plug-in.

name*

Translation map
see Internationalization

The name of the plug-in.

description

Translation map
see Internationalization

A brief description of the plug-in.

data

string[]
e.g. [“userName”]

A set of properties that the plug-in is allowed to request from COYO.

lifecycle

object
e.g. { "url": "/lifecycle/", "events": ["install"] }

A description of web hook endpoints implemented in the plug-in backend to receive events from the COYO backend. See https://coyoapp.atlassian.net/wiki/spaces/CD/pages/237535249/Back+end+communication

config

Configuration fields
see Configuration

A set of global configuration fields for this plug-in.

entryPoints*

object[]
see Entry points

A list of entry points that this plug-in offers.

id*

UUID
e.g. a6725e06-30f2-46c2-a1da-fa7a52a0e454

A random version 4 UUID to uniquely identify the entry point.

name*

Translation map
see Internationalization

The name of the entry point.

description

Translation map
see Internationalization

A brief description of the entry point.

url*

URL
e.g. /plugin/ep1

An absolute or relative (to this manifest) invocation URL.

height

Height or ratio
see Dimensions and scrolling

The default height or ratio of this entry point.

config

Configuration fields
see Configuration

A set of local configuration fields for this entry point.

origin

URL[]
see Secure communication

A set of alternative targetOrigins for communication via window.postMessage().

Entry points

To cater for different views of a single plug-in, COYO offers the concept of entry points. Each entry point belongs to the overarching plug-in and shares the same data but defines its own URL endpoint. While the plug-in itself is configured in COYO’s administration area, the specific entry point to render can be configured on each individual plug-in instance in COYO. If your plug-in defines only one entry point COYO will automatically select and render it.

To get a better idea of entry points, let's take the following example. You develop a plug-in to display the current menu of your company canteen. While this is a single plug-in you might want to define three different entry points for it (each of them with an own URL and interface):

  • the daily menu,

  • a weekly overview

  • and the current special offers

Internationalization

Since COYO can be used in different languages, plug-ins should also react to the language settings of the user. This concerns both the information in the plug-in manifest and the presentation of the plug-in itself.

The description texts of the plug-in manifest are used in the administration area and in the plug-in configuration dialog. Thus, every text in the manifest is not defined as a simple string but as a JSON object mapping language identifiers to their respective translations. COYO automatically takes care of selecting the correct language for every user based on the users' settings.

Do use translation maps.

1 2 3 4 5 6 7 8 9 10 11 12 { "pluginVersion": "1.0.0", "name": { "en": "Hello world", "de": "Hallo Welt" }, "description": { "en": "My first plug-in.", "de": "Mein erstes Plug-In." }, … }

Don’t use translated strings.

1 2 3 4 5 6 { "pluginVersion": "1.0.0", "name": "Hello world", "description": "My first plug-in.", … }

The translation of the plug-in itself is not automatically handled by COYO. Each plug-in can handle translations in its own way. The required language data can be retrieved via a requestData call to the COYO front end with the corresponding data key userLanguage.