Creating widget and operator descriptions

Application Mashup (WireCloud) course @ http://edu.fiware.org

Use ← and → to move around. Press h for getting more info

Presenter Notes

Creating widget and operator descriptions

Introduction

Presenter Notes

Introduction

In WireCloud, every application mashup component have to provide a config.xml file providing metadata info. Moreover, every component must provide the following info:

  • vendor: The id of the vendor/distributor of the mashable application component. It cannot contain the character "/"
  • name: Name of the mashable application component. It cannot contain the character "/"
  • version: Current version of the mashable application component. It must define starting sequences of numbers separated by dots. Moreover, zeros can only be used alone (e.g. 0.1 is valid but 03.2 is not). Following a release number, you can have a pre-release tag. A pre-release tag is a serie of letters: a (alpha), b (beta) or rc (release candidate); followed by digits. Pre-release tags make a version be considered older than the version they are appended to. So, revision 2.4 is newer than revision 2.4rc1, which in turn is newer than 2.4b1 or 2.4a1

Presenter Notes

Introduction

These tree attributes (vendor, name and version) uniquely identify the resource, therefore there can not be a repetition of such identifier in any collection of WireCloud resources (including widgets, mashups, operators, ...). In addition to these attributes, every resource can, optionally, provide the following attributes:

  • title: Name used in the user interface for the mashup application component. Used for example when listing mashable application components. This field can be translated, therefore this field is not used to uniquely identify the mashable application component. This field is also uses as the default title for widgets added to workspaces

  • authors: Comma separated list of developers. e.g.:

    Álvaro Arranz, Aitor Magan

    You can also provide an email and/or an url:

    Barney Rubble <b@rubble.com> (http://barnyrubble.tumblr.com/)

  • contributors: Comma separated list of contributors. Same format than the authors field

Presenter Notes

Introduction

  • email: E-mail address for getting support
  • license: Name of the license associated to the mashable application component
  • description: A brief textual description of the mashable application component
  • longdescription: Relative path to a markdown file describing the mashable application component
  • changelog: Relative path to a markdown file detailing the changes made to the mashable application component in each version
  • image: Absolute or template-relative URL of the mashable application component image for the catalogue. (170x80px)
  • smartphone: Image to be used in smartphones. (59x60px)
  • doc: Absolute or template-relative URL of the mashable application component documentation.

Presenter Notes

Creating widget and operator descriptions

XML

Presenter Notes

XML

Mashable application components described using XML should use the http://wirecloud.conwet.fi.upm.es/ns/macdescription/1 namespace for the root element that must be called widget or operator depending on the component that you want to develop. This root element must have the three attributes (vendor, name and version) that identify the resource. In addition, it should contain another element details that will carry on all the basic information about the resource, as explained before.

Presenter Notes

XML

The following code shows you the description of a widget using XML:

<?xml version='1.0' encoding='UTF-8'?>
<widget xmlns="http://wirecloud.conwet.fi.upm.es/ns/macdescription/1" vendor="CoNWeT" name="map-viewer" version="2.5.4">
    <details>
        <title>Map Viewer</title>
        <authors>Example &lt;user@example.com&gt;</authors>
        <email>user@example.com</email>
        <image>images/catalogue.png</image>
        <description>Place things on map! Explore the world, trace routes...</description>
        <longdescription>DESCRIPTION.md</longdescription>
        <license>AGPLv3+ w/linking exception</license>
        <licenseurl>http://www.gnu.org/licenses/agpl-3.0.html</licenseurl>
        <doc>doc/userguide.md</doc>
        <changelog>doc/changelog.md</changelog>
    </details>
    ...
</widget>

Presenter Notes

XML

And here you have a description of an operator in XML:

<?xml version='1.0' encoding='UTF-8'?>
<operator xmlns="http://wirecloud.conwet.fi.upm.es/ns/macdescription/1" vendor="CoNWeT" name="ngsi-source" version="3.0a2">
    <details>
        <title>Map Viewer</title>
        <homepage>https://github.com/wirecloud-fiware/ngsi-source</homepage>
        <authors>Example &lt;user@example.com&gt;</authors>
        <email>user@example.com</email>
        <image>images/catalogue.png</image>
        <description>Retrieve Orion Context Broker entities and their updates in real time.</description>
        <longdescription>DESCRIPTION.md</longdescription>
        <license>AGPLv3+ w/linking exception</license>
        <licenseurl>http://www.gnu.org/licenses/agpl-3.0.html</licenseurl>
        <doc>doc/userguide.md</doc>
        <changelog>doc/changelog.md</changelog>
    </details>
    ...
</operator>

Presenter Notes

Creating widget and operator descriptions

RDF

Presenter Notes

RDF

In addition to the XML format, widget and operator descriptions (config.xml files) can also be written using one of the following RDF notations: n3, turtle or rdf/xml. These RDF notations usually are more complex than the XML notation provided by WireCloud, making them more suitable when you want to add extra metadata to the config.xml. WireCloud uses this syntax for exporting the component metadata to other systems that uses RDF (but this is transparent to the user).

We recommend you to stick using the XML notation when possible.

Presenter Notes

RDF

The first thing that you have to include in your config.xml file is the header in order to have all the namespaces available in the rest of the document. At least you need to import the WireCloud namespace ("http://wirecloud.conwet.fi.upm.es/ns/widget"), but you can import other namespaces in order to ease the task of writing the code. In the following lines you can find an example. As can be seen, the WireCloud namespace has been tagged as "wire". In addition, some other namespaces has been imported (usdl-core, foaf, rdfs,...):

<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:usdl-core="http://www.linked-usdl.org/ns/usdl-core#"
xmlns:foaf="http://xmlns.com/foaf/0.1/"
xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
xmlns:dcterms="http://purl.org/dc/terms/"
xmlns:wire="http://wirecloud.conwet.fi.upm.es/ns/widget#"
xmlns:vCard = "http://www.w3.org/2006/vcard/ns#"
xmlns:gr="http://purl.org/goodrelations/v1#">

Presenter Notes

RDF

And using turtle:

@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix usdl-core: <http://www.linked-usdl.org/ns/usdl-core#> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix wire: <http://wirecloud.conwet.fi.upm.es/ns/widget#> .
@prefix vCard: <http://www.w3.org/2006/vcard/ns#> .
@prefix gr: <http://purl.org/goodrelations/v1#> .

Presenter Notes

RDF

Once added the RDF header, the next step is adding the required node: wire:Operator or wire:Widget depending on the component that you want to create. This will be the root node, so all the metadata associated to the widget or operator should be a descendant of this node.

The basic info about the resource should be added using the following nodes:

  • vendor: udsl-core:hasProvider
  • name: dcterms:title
  • version: usdl-core:versionInfo
  • description: dcterms:description
  • title: wire:displayName
  • author: dcterms:creator
  • email: vcard:addr
  • image: wire:hasImageUri
  • smartphoneimage: wire:hasiPhoneImageUri
  • doc: foaf:page

Presenter Notes

RDF

The following code show an example of the description of an Operator:

<wire:Operator rdf:about="http://wirecloud.conwet.fi.upm.es/ns/widget#CoNWeT/entity-service/2.3.2">
    <usdl:hasProvider>
        <gr:BusinessEntity rdf:nodeID="Ne2a8644226d049239a5a9856bafcd7c6">
            <foaf:name>CoNWeT</foaf:name>
        </gr:BusinessEntity>
    </usdl:hasProvider>
    <wire:hasImageUri rdf:resource="images/catalogue.png"/>
    <wire:hasiPhoneImageUr rdf:resource="images/catalogue_mob.png"/>
    <wire:displayName>Entity Service</wire:displayName>
    <dcterms:title>entity-service</dcterms:title>
    <usdl:versionInfo>2.3.2</usdl:versionInfo>
    <dcterms:description>This operator permits us gather information about several entities (Lamp posts, AMMSs and Regulators) from any NGSI service.</dcterms:description>
    <foaf:page rdf:resource="docs/index.html"/>
    <dcterms:creator>
        <foaf:Person rdf:nodeID="Ne3468f9471d349908dd8e81167153ac8">
            <foaf:name>sblanco</foaf:name>
        </foaf:Person>
    </dcterms:creator>
    <vcard:addr>
        <vcard:Work rdf:nodeID="N6d57fc77a0e643138195f0db44b95fb2">
            <vcard:email>example@example.com</vcard:email>
        </vcard:Work>
    </vcard:addr>
</wire:Operator>

Presenter Notes

RDF

Evidently, other RDF formats can also be used (e.g. n3):

<http://wirecloud.conwet.fi.upm.es/ns/widget#CoNWeT/entity-service/2.3.2> a wire:Operator ;
dcterms:creator [ a foaf:Person ;
    foaf:name "example" ] ;
dcterms:description "This operator permits us gather information about several entities (Lamp posts, AMMSs and Regulators) from any NGSI service." ;
dcterms:title "entity-service" ;
wire:displayName "Entity Service" ;
wire:hasImageUri <images/catalogue.png> ;
usdl:hasProvider [ a gr:BusinessEntity ;
    foaf:name "CoNWeT" ] ;
usdl:versionInfo "2.3.2" ;
vcard:addr [ a vcard:Work ;
    vcard:email "example@example.com" ] ;
foaf:page <docs/display/wirecloud> .

Presenter Notes

Creating widget and operator descriptions

Entry Points

Presenter Notes

Entry Points

Widgets and operators are very similar but not equals. There are some difference between them since the operators don't have a view. This means that operators descriptors don't use an initial HTML document as entry point. Instead, operators define the list of javascript files in their descriptor file.

Presenter Notes

Entry Points

Widgets

If you use XML to define your widget, you must define the contents element to set the HTML entry point. This element is contained by the root element (widget) (as we explained before):

<contents src="index.html"/>

Just in case you use RDF to describe your widget, you must set the element usdl:utilizedResource to set the HTML entry point. The following code is an example using N3:

usdl:utilizedResource <index.html> ;

Presenter Notes

Entry Points

Operators

If you have developed your operator using XML, you must use the scripts element to define the JS files that will be executed. This element must be contained by the root one (operator) as can be sen in the following snippet: 

<scripts>
    <script src="js/main.js"/>
    <script src="..."/>
</scripts>

Presenter Notes

Entry Points

Operators

To set the JS files of your operator in RDF, you must set the element usdl:utilizedResource and set the index of each file. To do so, you can stick to the following example:

<http://wirecloud.conwet.fi.upm.es/ns/widget#CoNWeT/entity-service/2.3.2> a wire:Operator ;
    usdl:utilizedResource <js/main.js> ;
    ...

<js/main.js> a usdl:Resource ;
    wire:index "0" .

You can also use other RDF formats such as XML:

<usdl:utilizedResource>
    <usdl:Resource rdf:about="js/main.js">
        <wire:index>0</wire:index>
    </usdl:Resource>
</usdl:utilizedResource>

Presenter Notes

Creating widget and operator descriptions

Switching between supported description formats

Presenter Notes

Switching between supported description formats

WireCloud provides tools for automatically convert the format of your mashable application component descriptions. If you want to do it, you can make use of the convert command (WireCloud must be installed in order to use this tool, see the Installation and Administration Guide for more info):

$ wirecloud-admin convert [options] <source_widget_descriptor> [dest_file]

The most important options supported by this command are the -d flag, that allows you to specify the output format (currently you can use the following formats: xml, rdf and old_xml); and the --rdf-format option that allows you to specify the flavour or RDF to use. For example, if you want to obtain the RDF (n3) versión of a description you can run the following command:

$ wirecloud-admin convert -d rdf --rdf-format n3 config.n3

Presenter Notes

Switching between supported description formats

This will print the new description to the standard output. For saving the result into a file, you should use the [dest_file] argument. The next example will convert the config.ttl description file from RDF/turtle to xml creating a config.xml file:

$ wirecloud-admin convert -d xml config.ttl config.xml

Remember that you can always obtain more info about the convert command using the help command:

$ wirecloud-admin help convert

Presenter Notes

Creating widget and operator descriptions

Examples

Presenter Notes

Examples

The following tutorials will guide you to create a widget or an operator. These tutorials include some other configurations that can be added to your config.xml file. But the best way to understand the structure of these documents is to see some examples.

You can find some widgets and operators on github:

Presenter Notes

Thanks!

Presenter Notes