The options plugin provides a way of adding configurable lists of options.
From version 2.0.0 options end up as link elements in the item meta data section per default. This is different from before. In version 1.x.x options ended up as link elements in the content meta data section. If you need to keep the old behaviour when upgrading the configuration setting deprecatedMode must be set to true.
When adding or remove links document:changed events is fired. These event structures change between 1.0.1 and 2.0.0. This can have an impact on other plugins. If you have plugins listening to these events, code need to be amended before upgrading. See below for more details on events fired.
Options are specified, in the writer client configuration file, as a specific type. Each type has a configurable number
of options to choose from.
| Property | Type | Required | Description |
|---|---|---|---|
| options | Object | true |
Full configuration of a options values, see below for examples |
| deprecatedMode | Boolean | false |
Optional. If set to true the plugin will create and manage option links in the content meta section (which is deprecated) |
{
"id": "io.infomaker.options",
"name": "im-options",
"url": "https://plugins.writer.infomaker.io/v1/infomaker/im-options/{PLUGIN_VERSION}/index.js",
"enabled": true,
"mandatory": false,
"data": {
"options": {
"type": "toggle",
"label": "Article options",
"link": {
"rel": "articleoptions",
"type": "x-im/articleoptions"
},
"multivalue": true,
"values": [
{
"uri": "im://articleoptions/premium",
"title": "Premium"
},
{
"uri": "im://articleoptions/facebok",
"title": "Facebook"
},
{
"uri": "im://articleoptions/instagram",
"title": "Instagram"
},
{
"title": "Article placement",
"uri": "im://articleoptions/tone",
"list": {
"type": "dropdown",
"label": "Article placement options",
"link": {
"rel": "articleoptions/placement",
"type": "x-im/articleoptions/placement"
},
"multivalue": false,
"values": [
{
"title": "- Please select placement -"
},
{
"uri": "im://articleoptions/placement/top",
"title": "Positive tone"
},
{
"uri": "im://articleoptions/tone/middle",
"title": "Neutral tone"
},
{
"uri": "im://articleoptions/tone/bottom",
"title": "Negative tone"
}
]
}
}
]
}
}
}The example above states a list of 4 toggable options. The multivalue setting is set to true, which means that any of them may be selected.
The fourth option 'Article placement' has a sub-list defined with three options.
It's a dropdown style with setting multivalue set to false, so only one of the items may be selected.
The first item does not have a uri key, which means that it's a header and does not result in a link in the document.
The option plugin supports being defined multiple times in the configuration file so that
completely different options may be handled by this plugin. The id must be set to different values in order for this to function.
The name must be set to im-options in order for the plugin to register*.
{
"id": "io.infomaker.socialoptions",
"name": "im-options",
"url": "https://plugins.writer.infomaker.io/v1/infomaker/im-options/{PLUGIN_VERSION}/index.js",
"enabled": true,
"mandatory": true,
...
},
{
"id": "io.infomaker.articleoptions",
"name": "im-options",
"url": "https://plugins.writer.infomaker.io/v1/infomaker/im-options/{PLUGIN_VERSION}/index.js",
"enabled": true,
"mandatory": true,
...
},The plugin supports three types of components for selecting values: dropdown-, toggle- and button components.
The dropdown component, configured with dropdown supports selecting a single value:
------------------------
| Choose something | V |
------------------------...
"options": {
"type": "dropdown",
"label": "Article options",
"link": {
"rel": "articleoptions",
"type": "x-im/articleoptions"
},
"multivalue": false,
"values": [
{
"uri": "im://articleoptions/premium",
"title": "Premium"
},
...The button component, configured with button stacks horizontally and supports selecting multiple values:
[Value 1] [Value 2] [Value 3]
[Value 4]Buttons also have support for icons prepending the name. It is configured in the 'values' section, using the field 'icon'. The value
is any of the Font Awesome icons from http://fontawesome.io/icons/.
It is also possible to have an image icon, which is specified using the 'image' field in the value section.
...
"options": {
"type": "button",
"label": "Article options",
"link": {
"rel": "articleoptions",
"type": "x-im/articleoptions"
},
"multivalue": true,
"values": [
{
"uri": "im://articleoptions/premium",
"title": "Premium",
"icon" : "fa-star-o"
},
{
"uri": "im://articleoptions/priority",
"title": "Priority",
"image" : "data:image/svg+xml;base64,..."
},
...The toggle component, configured with toggle stacks vertically and supports selecting multiple values:
[ O] Value 1
[O ] Value 2
[O ] Value 3Toggle buttons also have support for icons prepending the title. It is configured in the 'values' section, using the field 'icon'. The value
is any of the Font Awesome icons from http://fontawesome.io/icons/.
It is also possible to have an image icon, which is specified using the 'image' field in the value section.
...
"options": {
"type": "toggle",
"label": "Article options",
"link": {
"rel": "articleoptions",
"type": "x-im/articleoptions"
},
"multivalue": true,
"values": [
{
"uri": "im://articleoptions/premium",
"title": "Premium",
"icon" : "fa-star-o"
},
{
"uri": "im://articleoptions/priority",
"title": "Priority",
"image" : "data:image/svg+xml;base64,..."
},
...The plugin will add link under newsItem > itemMeta > links. Here's an example where a user marked the article as being 'premium' according to the example configuration above.
<newsItem>
<itemMeta>
<links xmlns="http://www.infomaker.se/newsml/1.0">
<link rel="articleoptions" title="Premium" type="x-im/articleoptions" uri="im://articleoptions/premium"/>
</links>
</itemMeta>
</newsItem>Remember, if you really must keep backwards compatibility with older content and store option links under newsItem > contentMeta > links you need to set the deprecatedMode to true.
When toggling options on or off, link elements are removed or added to the document. These changes will trigger document:changed events. These events can be listened to by other plugins. From version 2.0.0 these events will look as below.
The event will include the properties rel, type, title and uri which will match the option configuration. Se below examples.
{
"eventType": "document:changed",
"data": {
"rel": "articleoptions",
"title": "Premium",
"type": "x-im/articleoptions",
"uri": "im://articleoptions/premium",
"action": "add"
}
}{
"eventType": "document:changed",
"data": {
"rel": "articleoptions",
"uri": "im://articleoptions/premium",
"action": "remove"
}
}