From 9a9b7c19970fde7cb0f5837e7ac31f5d8f66db09 Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Tue, 26 Mar 2019 10:38:05 +0000 Subject: [PATCH 1/4] Amend Codeblocks, add highlight and format markdown --- docs/CONTRIBUTING.md | 187 ++-- docs/administration_guide.md | 374 ++++--- docs/development/eclipse_ide.md | 109 +- docs/development/macdl.md | 8 +- docs/development/macdl_rdf.md | 595 +++++------ docs/development/macdl_xml.md | 461 ++++---- docs/development/ngsi_api.md | 519 ++++----- docs/development/object_storage_api.md | 115 +- docs/development/platform/testing.md | 16 +- docs/development/platform/themes.md | 4 +- docs/development/platform/translation.md | 26 +- docs/development/widget_and_operators.md | 124 +-- docs/index.md | 68 +- docs/installation_guide.md | 1238 ++++++++++++---------- docs/restapi/index.md | 11 +- docs/user_guide.md | 620 +++++------ docs/widgetapi/widgetapi.md | 1016 ++++++++---------- mkdocs.yml | 6 +- 18 files changed, 2473 insertions(+), 3024 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 2cd34fd6f2..abb346f5e8 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -2,68 +2,58 @@ Looking to contribute something to WireCloud? **Here's how you can help.** -Please take a moment to review this document in order to make the contribution -process easy and effective for everyone involved. +Please take a moment to review this document in order to make the contribution process easy and effective for everyone +involved. -Following these guidelines helps to communicate that you respect the time of -the developers managing and developing this open source project. In return, -they should reciprocate that respect in addressing your issue or assessing -patches and features. +Following these guidelines helps to communicate that you respect the time of the developers managing and developing this +open source project. In return, they should reciprocate that respect in addressing your issue or assessing patches and +features. **Contents** -- [Using the issue tracker](#using-the-issue-tracker) -- [Bug reports](#bug-reports) -- [Feature requests](#feature-requests) -- [Contributing code](#contributing-code) - - [Code Guidelines](#code-guidelines) - +- [Using the issue tracker](#using-the-issue-tracker) +- [Bug reports](#bug-reports) +- [Feature requests](#feature-requests) +- [Contributing code](#contributing-code) + - [Code Guidelines](#code-guidelines) ## Using the issue tracker -The [issue tracker](https://github.com/Wirecloud/wirecloud/issues) is -the preferred channel for [bug reports](#bug-reports) and -[features requests](#feature-requests), but please respect the following -restrictions: - -* Please **do not** use the issue tracker for personal support requests. Stack - Overflow ([`fiware-wirecloud`](http://stackoverflow.com/questions/tagged/fiware-wirecloud) - tag) is a better place to get help. +The [issue tracker](https://github.com/Wirecloud/wirecloud/issues) is the preferred channel for +[bug reports](#bug-reports) and [features requests](#feature-requests), but please respect the following restrictions: -* Please **do not** derail or troll issues. Keep the discussion on topic and - respect the opinions of others. +- Please **do not** use the issue tracker for personal support requests. Stack Overflow + ([`fiware-wirecloud`](http://stackoverflow.com/questions/tagged/fiware-wirecloud) tag) is a better place to get + help. +- Please **do not** derail or troll issues. Keep the discussion on topic and respect the opinions of others. ## Bug reports -A bug is a _demonstrable problem_ that is caused by the code in the repository. -Good bug reports are extremely helpful, so thanks! +A bug is a _demonstrable problem_ that is caused by the code in the repository. Good bug reports are extremely helpful, +so thanks! Guidelines for bug reports: -1. **Use the GitHub issue search** — check if the issue has already been - reported. - -2. **Check if the issue has been fixed** — try to reproduce it using the - latest `master` or development branch in the repository. +1. **Use the GitHub issue search** — check if the issue has already been reported. -3. **Isolate the problem** — ideally create a [reduced test - case](http://css-tricks.com/6263-reduced-test-cases/) and a live example. +2. **Check if the issue has been fixed** — try to reproduce it using the latest `master` or development branch in + the repository. +3. **Isolate the problem** — ideally create a [reduced test case](http://css-tricks.com/6263-reduced-test-cases/) + and a live example. -A good bug report shouldn't leave others needing to chase you up for more -information. Please try to be as detailed as possible in your report. What is -your environment? What steps will reproduce the issue? What browser(s) and OS -experience the problem? Do other browsers show the bug differently? What -would you expect to be the outcome? All these details will help people to fix -any potential bugs. +A good bug report shouldn't leave others needing to chase you up for more information. Please try to be as detailed as +possible in your report. What is your environment? What steps will reproduce the issue? What browser(s) and OS +experience the problem? Do other browsers show the bug differently? What would you expect to be the outcome? All these +details will help people to fix any potential bugs. Example: > Short and descriptive example bug report title > -> A summary of the issue and the browser/OS environment in which it occurs. If -> suitable, include the steps required to reproduce the bug. +> A summary of the issue and the browser/OS environment in which it occurs. If suitable, include the steps required to +> reproduce the bug. > > 1. This is the first step > 2. This is the second step @@ -71,57 +61,44 @@ Example: > > `` - a link to the reduced test case > -> Any other information you want to share that is relevant to the issue being -> reported. This might include the lines of code that you have identified as -> causing the bug, and potential solutions (and your opinions on their -> merits). - +> Any other information you want to share that is relevant to the issue being reported. This might include the lines of +> code that you have identified as causing the bug, and potential solutions (and your opinions on their merits). ## Feature requests -Feature requests are welcome. But take a moment to find out whether your idea -fits with the scope and aims of the project. It's up to *you* to make a strong -case to convince the project's developers of the merits of this feature. Please -provide as much detail and context as possible. - +Feature requests are welcome. But take a moment to find out whether your idea fits with the scope and aims of the +project. It's up to _you_ to make a strong case to convince the project's developers of the merits of this feature. +Please provide as much detail and context as possible. ## Contributing code -If you're ready to take the plunge & contribute back some code/docs, the process -should look like: - -- Fork the project on GitHub into your own account. -- Clone your copy of WireCloud. -- Make a new branch in git & commit your changes there. -- Push your new branch up to GitHub. -- Again, ensure there isn't already an issue or pull request out there on it. - If there is & you feel you have a better fix, please take note of the issue - number & mention it in your pull request. -- Create a new pull request (based on your branch), including what the - problem/feature is, versions of your software & referencing any related - issues/pull requests. - -In order to be merged into WireCloud, contributions should follow the following -recommendation as much as possible: - -- A solid patch that: - - is clear. - - works across all supported versions of Python/Django (take a look to the +If you're ready to take the plunge & contribute back some code/docs, the process should look like: + +- Fork the project on GitHub into your own account. +- Clone your copy of WireCloud. +- Make a new branch in git & commit your changes there. +- Push your new branch up to GitHub. +- Again, ensure there isn't already an issue or pull request out there on it. If there is & you feel you have a better + fix, please take note of the issue number & mention it in your pull request. +- Create a new pull request (based on your branch), including what the problem/feature is, versions of your software & + referencing any related issues/pull requests. + +In order to be merged into WireCloud, contributions should follow the following recommendation as much as possible: + +- A solid patch that: + - is clear. + - works across all supported versions of Python/Django (take a look to the [documentation about testing](development/platform/testing.md)) - - follows the [Code guidelines](#code-guidelines). - - comments included as needed. -- A test case that demonstrates the previous flaw that now passes with the - included patch. -- If it adds/changes a public API, it must also include documentation for those - changes. + - follows the [Code guidelines](#code-guidelines). + - comments included as needed. +- A test case that demonstrates the previous flaw that now passes with the included patch. +- If it adds/changes a public API, it must also include documentation for those changes. -You can manually test your changes by running WireCloud directly from the -working copy source code repository. The provided `settings.py` file will use -a shared security key and a basic configuration (e.g. using `sqlite3`) so it is -not ready for a production environments, but can be used for simple manual -tests. Those are the steps to be followed: +You can manually test your changes by running WireCloud directly from the working copy source code repository. The +provided `settings.py` file will use a shared security key and a basic configuration (e.g. using `sqlite3`) so it is not +ready for a production environments, but can be used for simple manual tests. Those are the steps to be followed: -```shell +```bash # # Download your WireCloud repository # @@ -181,38 +158,42 @@ python manage.py runserver # ``` - ### Code guidelines #### Python -- Follow the [PEP 8 style rules](https://www.python.org/dev/peps/pep-0008/) -- Use [`flake8`](http://flake8.pycqa.org/en/latest/) (or alternatively, `pep8` - and `pyflakes` in combination) +- Follow the [PEP 8 style rules](https://www.python.org/dev/peps/pep-0008/) +- Use [`flake8`](http://flake8.pycqa.org/en/latest/) (or alternatively, `pep8` and `pyflakes` in combination) #### JavaScript -- Four spaces for indentation, never tabs. -- strict mode. -- "Attractive". -- Use [`eslint`](http://eslint.org/) (there is a `.eslintrc` file on the source - code of WireCloud ;-). +- Four spaces for indentation, never tabs. +- strict mode. +- "Attractive". +- Use [`eslint`](http://eslint.org/) (there is a `.eslintrc` file on the source code of WireCloud ;-). #### HTML -- Four spaces for indentation, never tabs. -- Double quotes only, never single quotes. -- Always use proper indentation. -- Use tags and elements appropriate for an XHTML5 doctype (e.g., self-closing tags). +- Four spaces for indentation, never tabs. +- Double quotes only, never single quotes. +- Always use proper indentation. +- Use tags and elements appropriate for an XHTML5 doctype (e.g., self-closing tags). #### SCSS -- Multiple-line approach (one property and value per line). -- Always a space after a property's colon (e.g., `display: block;` and not `display:block;`). -- End all lines with a semi-colon. -- Attribute selectors, like `input[type="text"]` should always wrap the attribute's value in double quotes, for consistency and safety (see this [blog post on unquoted attribute values](http://mathiasbynens.be/notes/unquoted-attribute-values) that can lead to XSS attacks). -- Attribute selectors should only be used where absolutely necessary (e.g., form controls) and should be avoided on custom components for performance and explicitness. -- Series of classes for a component should include a base class (e.g., `.component`) and use the base class as a prefix for modifier and sub-components (e.g., `.component-lg`). -- Avoid inheritance and over nesting—use single, explicit classes whenever possible. -- When feasible, default color palettes should comply with [WCAG color contrast guidelines](http://www.w3.org/TR/WCAG20/#visual-audio-contrast). -- Except in rare cases, don't remove default `:focus` styles (via e.g. `outline: none;`) without providing alternative styles. See [this A11Y Project post](http://a11yproject.com/posts/never-remove-css-outlines/) for more details. +- Multiple-line approach (one property and value per line). +- Always a space after a property's colon (e.g., `display: block;` and not `display:block;`). +- End all lines with a semi-colon. +- Attribute selectors, like `input[type="text"]` should always wrap the attribute's value in double quotes, for + consistency and safety (see this + [blog post on unquoted attribute values](http://mathiasbynens.be/notes/unquoted-attribute-values) that can lead to + XSS attacks). +- Attribute selectors should only be used where absolutely necessary (e.g., form controls) and should be avoided on + custom components for performance and explicitness. +- Series of classes for a component should include a base class (e.g., `.component`) and use the base class as a + prefix for modifier and sub-components (e.g., `.component-lg`). +- Avoid inheritance and over nesting—use single, explicit classes whenever possible. +- When feasible, default color palettes should comply with + [WCAG color contrast guidelines](http://www.w3.org/TR/WCAG20/#visual-audio-contrast). +- Except in rare cases, don't remove default `:focus` styles (via e.g. `outline: none;`) without providing alternative + styles. See [this A11Y Project post](http://a11yproject.com/posts/never-remove-css-outlines/) for more details. diff --git a/docs/administration_guide.md b/docs/administration_guide.md index ad2e87ed38..7f8c5750b5 100644 --- a/docs/administration_guide.md +++ b/docs/administration_guide.md @@ -1,234 +1,225 @@ ## Administration commands -WireCloud provides a set of command line tools that can be used from the command -line (manually or by scripts) on the folder of the WireCloud instance. +WireCloud provides a set of command line tools that can be used from the command line (manually or by scripts) on the +folder of the WireCloud instance. ### addtocatalogue -Adds one or more packaged mashable application components into the catalogue. At -least one of the following flags: +Adds one or more packaged mashable application components into the catalogue. At least one of the following flags: -- **redeploy** - Replace mashable application components files with the new ones. -- **users**=USERS - Comma separated list of users that will obtain access to the uploaded mashable - application components -- **groups**=GROUPS - Comma separated list of groups that will obtain access rights to the uploaded - mashable application components -- **public** - Allow any user to access the mashable application components. +- **redeploy** Replace mashable application components files with the new ones. +- **users**=USERS Comma separated list of users that will obtain access to the uploaded mashable application + components +- **groups**=GROUPS Comma separated list of groups that will obtain access rights to the uploaded mashable application + components +- **public** Allow any user to access the mashable application components. Example usage: - $ python manage.py addtocatalogue --users=admin,ringo file1.wgt file2.wgt - +```bash +python manage.py addtocatalogue --users=admin,ringo file1.wgt file2.wgt +``` ### changepassword -Allows changing a user’s password. It prompts you to enter twice the password of the user given as parameter. If they both match, the new password will be changed immediately. If you do not supply a user, the command will attempt to change the password whose username matches the current user. +Allows changing a user’s password. It prompts you to enter twice the password of the user given as parameter. If they +both match, the new password will be changed immediately. If you do not supply a user, the command will attempt to +change the password whose username matches the current user. Example usage: - $ python manage.py changepassword ringo - +```bash +python manage.py changepassword ringo +``` ### createorganization -Creates an empty organization. Once created, you will be able to add users to -the associated group. +Creates an empty organization. Once created, you will be able to add users to the associated group. Example usage: - $ python manage.py createorganization - +```bash +python manage.py createorganization +``` ### createsuperuser -Creates a superuser account (a user who has all permissions). This is useful if you need to create an initial superuser account or if you need to programmatically generate superuser accounts for your site(s). +Creates a superuser account (a user who has all permissions). This is useful if you need to create an initial superuser +account or if you need to programmatically generate superuser accounts for your site(s). -When run interactively, this command will prompt for a password for the new superuser account. When run non-interactively, no password will be set, and the superuser account will not be able to log in until a password has been manually set for it. +When run interactively, this command will prompt for a password for the new superuser account. When run +non-interactively, no password will be set, and the superuser account will not be able to log in until a password has +been manually set for it. -- **--noinput** - Tells Django to NOT prompt the user for input of any kind. You must use **--username** with **--noinput**, along with an option for any other required field. Superusers created with **--noinput** will not be able to sign in until they're given a valid password. -- **--username** - Specifies the login for the superuser. -- **--email** - Specifies the email for the superuser. +- **--noinput** Tells Django to NOT prompt the user for input of any kind. You must use **--username** with + **--noinput**, along with an option for any other required field. Superusers created with **--noinput** will not be + able to sign in until they're given a valid password. +- **--username** Specifies the login for the superuser. +- **--email** Specifies the email for the superuser. -The username and email address for the new account can be supplied by using the **--username** and **--email** arguments on the command line. If either of those is not supplied, `createsuperuser` will prompt for it when running interactively. +The username and email address for the new account can be supplied by using the **--username** and **--email** arguments +on the command line. If either of those is not supplied, `createsuperuser` will prompt for it when running +interactively. Example usage: - $ python manage.py createsuperuser - +```bash +python manage.py createsuperuser +``` ### rebuild_index -Rebuilds Haystack indexes used by the search engine of WireCloud. See Haystack -[documentation][haystack_rebuild_index] for more details. +Rebuilds Haystack indexes used by the search engine of WireCloud. See Haystack [documentation][haystack_rebuild_index] +for more details. -- **--noinput** - If provided, no prompts will be issued to the user and the data will be wiped out. +- **--noinput** If provided, no prompts will be issued to the user and the data will be wiped out. Example usage: - $ python manage.py rebuild_index +```bash +python manage.py rebuild_index +``` [haystack_rebuild_index]: http://django-haystack.readthedocs.io/en/master/management_commands.html#rebuild-index - ### resetsearchindexes (deprecated) Rebuilds Haystack indexes used by the search engine of WireCloud. To be removed in Wirecloud WireCloud v1.3. -- **--noinput** - Tells Django to NOT prompt the user for input of any kind. +- **--noinput** Tells Django to NOT prompt the user for input of any kind. Example usage: - $ python manage.py resetsearchindexes - +```bash +python manage.py resetsearchindexes +``` ## Creating WireCloud backups and restoring them -1. Create a backup of your instance folder. For example: +1. Create a backup of your instance folder. For example: - $ tar -cvjf wirecloud-backup.tar.bz2 -C /path/to/your/instance . +```bash +tar -cvjf wirecloud-backup.tar.bz2 -C /path/to/your/instance . +``` -2. Create a backup of your database. +2. Create a backup of your database. -There are several ways for creating backups of the data stored in the database -used by WireCloud, each of them with its advantages and disadvantages. +There are several ways for creating backups of the data stored in the database used by WireCloud, each of them with its +advantages and disadvantages. -> **NOTE:** Always stop WireCloud before creating a backup for ensuring data -> consistency. +> **NOTE:** Always stop WireCloud before creating a backup for ensuring data consistency. ### Database backups using Django -Django provides the `dumpdata` and `loaddata` commands that can be used for -creating and restoring backups. Those commands can be used independently of the -database engine used. Moreover, you can create those backups using a given -database engine and restore them using a different one. Run the following -command for creating a backup of your database using Django: +Django provides the `dumpdata` and `loaddata` commands that can be used for creating and restoring backups. Those +commands can be used independently of the database engine used. Moreover, you can create those backups using a given +database engine and restore them using a different one. Run the following command for creating a backup of your database +using Django: - $ python manage.py dumpdata > wirecloud.backup +```bash +python manage.py dumpdata > wirecloud.backup +``` -For restoring the backup you only have to run the `loaddata` command, using a -clean database: +For restoring the backup you only have to run the `loaddata` command, using a clean database: - $ python manage.py loaddata wirecloud.backup +```bash +python manage.py loaddata wirecloud.backup +``` -> **NOTE**: Backups created using `dumpdata` can only be restored using the same -> WireCloud version used for creating the backup. If you need to use a different -> version, restore the backup using the original version and then +> **NOTE**: Backups created using `dumpdata` can only be restored using the same WireCloud version used for creating the +> backup. If you need to use a different version, restore the backup using the original version and then > upgrade/downgrade it. - ### SQLite3 database backups -Creating a backup of a SQLite3 database is as easy as creating a copy of the -file where the database is stored. The only thing to take into account is to -stop WireCloud before creating the copy to avoid possible inconsistences. +Creating a backup of a SQLite3 database is as easy as creating a copy of the file where the database is stored. The only +thing to take into account is to stop WireCloud before creating the copy to avoid possible inconsistences. -The restoration procedure is as easy as the creation, you only have to make -WireCloud use the copied database file by editing the `settings.py` file or by -moving the copied database file to the place expected by WireCloud. +The restoration procedure is as easy as the creation, you only have to make WireCloud use the copied database file by +editing the `settings.py` file or by moving the copied database file to the place expected by WireCloud. -> **NOTE**: Take into account that this means that if you are making a full -> backup of your WireCloud instance, you don't need an extra step for -> backing up the database, this backup is already performed by backing up -> the instance directory. +> **NOTE**: Take into account that this means that if you are making a full backup of your WireCloud instance, you don't +> need an extra step for backing up the database, this backup is already performed by backing up the instance directory. ### PostgreSQL database backups You can find more information about how to create PostgreSQL backups in this -[page](http://www.postgresql.org/docs/9.1/static/backup-dump.html). Basically, -you have to run the following command: +[page](http://www.postgresql.org/docs/9.1/static/backup-dump.html). Basically, you have to run the following command: - $ pg_dump > wirecloud.backup +```bash +pg_dump > wirecloud.backup +``` > Make sure WireCloud is not running before making the backup You can restore the backup using the following command: - $ psql < wirecloud.backup - +```bash +psql < wirecloud.backup +``` ## Upgrading from previous versions -1. Install the new version of WireCloud -2. Migrate the database and populate it with any new base component, rebuild the - search indexes and collect the new static files by running the following - commands: +1. Install the new version of WireCloud +2. Migrate the database and populate it with any new base component, rebuild the search indexes and collect the new + static files by running the following commands: - $ python manage.py migrate - $ python manage.py populate - $ python manage.py rebuild_index - $ python manage.py collectstatic --noinput +```bash +python manage.py migrate +python manage.py populate +python manage.py rebuild_index +python manage.py collectstatic --noinput +``` - > **NOTE**: Remember to run those commands using the user serving wirecloud - > (e.g. `su wirecloud`) + > **NOTE**: Remember to run those commands using the user serving wirecloud (e.g. `su wirecloud`) -3. Reload WireCloud (e.g. `$ service apache2 graceful`) +3. Reload WireCloud (e.g. `$ service apache2 graceful`) -You can determine your currently installed version using -`wirecloud-admin --version`: +You can determine your currently installed version using `wirecloud-admin --version`: -``` -$ wirecloud-admin --version +```bash +wirecloud-admin --version 1.0.0 - ``` -> **NOTE:** It is strongly recommended to perform a full database backup before -> starting to migrate WireCloud to a new version. - +> **NOTE:** It is strongly recommended to perform a full database backup before starting to migrate WireCloud to a new +> version. ## From 1.1.x to 1.2.x -WireCloud 1.2 has moved from directly use Whoosh for using search indexes to use -Haystack for managing search indexes. Although Haystack has support for using -Whoosh as search index backend, the schema used for the search indexes are -different. You have to incorporate Haystack configuration into your -`settings.py` file and rebuild them by running the `rebuild_index` command. - +WireCloud 1.2 has moved from directly use Whoosh for using search indexes to use Haystack for managing search indexes. +Although Haystack has support for using Whoosh as search index backend, the schema used for the search indexes are +different. You have to incorporate Haystack configuration into your `settings.py` file and rebuild them by running the +`rebuild_index` command. ## From 1.0.x to 1.1.x -NGSI bindings (ngsijs) have been updated to `v1.0.2`. This allows WireCloud to -directly use CORS requests when connecting to a `ngsi-proxy`. The downside is -that WireCloud is unable to detect the version of ngsi-proxy used, so we had to -drop support for `ngsi-proxy` version `v1.0.0` and below. +NGSI bindings (ngsijs) have been updated to `v1.0.2`. This allows WireCloud to directly use CORS requests when +connecting to a `ngsi-proxy`. The downside is that WireCloud is unable to detect the version of ngsi-proxy used, so we +had to drop support for `ngsi-proxy` version `v1.0.0` and below. -WireCloud 1.1 has changed the schema of the workspace search index, you have to -update this index by running the `resetsearchindexes` command. Also, there are -new predefined dashboards, so you have to the `populate` command. +WireCloud 1.1 has changed the schema of the workspace search index, you have to update this index by running the +`resetsearchindexes` command. Also, there are new predefined dashboards, so you have to the `populate` command. -IdM integration has migrated from `python-social-auth` to -`social-auth-app-django` (see this [link][MIGRATING_TO_SOCIAL] for more info -about this change) - -[MIGRATING_TO_SOCIAL]: https://github.com/omab/python-social-auth/blob/master/MIGRATING_TO_SOCIAL.md +IdM integration has migrated from `python-social-auth` to `social-auth-app-django` (see this [link][migrating_to_social] +for more info about this change) +[migrating_to_social]: https://github.com/omab/python-social-auth/blob/master/MIGRATING_TO_SOCIAL.md ## From 0.9.x to 1.0.x -> **NOTE**: Support for Django 1.6 and Django 1.7 were removed in this version. -> Please, follow the steps described in the [Upgrading to Django -> 1.7+](#upgrading-to-django-17) section before upgrading to WireCloud 1.0. +> **NOTE**: Support for Django 1.6 and Django 1.7 were removed in this version. Please, follow the steps described in +> the [Upgrading to Django 1.7+](#upgrading-to-django-17) section before upgrading to WireCloud 1.0. > -> You can determine your currently installed version of Django by running the -> following command: +> You can determine your currently installed version of Django by running the following command: > > ``` > $ django-admin --version > 1.9.9 > ``` -WireCloud 1.0 has changed some url definitions to remove some django warnings, -so you should update your `urls.py` file. In particular, you have to change the -following lines: +WireCloud 1.0 has changed some url definitions to remove some django warnings, so you should update your `urls.py` file. +In particular, you have to change the following lines: ```python ... @@ -254,124 +245,113 @@ To: url(r'^cdp/', include('wirecloud.proxy.urls')), ... - ``` -> **NOTE**: If you plan to upgrade to Django 1.10, take into account that -> there were some deprecations regarding the syntax of the `url.py` file. We -> have updated the `urls.py` template in WireCloud 1.0 to support Django -> 1.8-1.10 but if you created your WireCloud instance using an older version, -> you will have to update it manually. You can find the current template at +> **NOTE**: If you plan to upgrade to Django 1.10, take into account that there were some deprecations regarding the +> syntax of the `url.py` file. We have updated the `urls.py` template in WireCloud 1.0 to support Django 1.8-1.10 but if +> you created your WireCloud instance using an older version, you will have to update it manually. You can find the +> current template at > [github](https://github.com/Wirecloud/wirecloud/blob/develop/src/wirecloud/commons/conf/platform_project_template/project_name/urls.py) -WireCloud 1.0 has also added a search index for workspaces, you have to -initialize it by running the `resetsearchindexes` command. The db should be -migrated before running this command. +WireCloud 1.0 has also added a search index for workspaces, you have to initialize it by running the +`resetsearchindexes` command. The db should be migrated before running this command. -``` -$ python manage.py migrate -$ python manage.py resetsearchindexes +```bash +python manage.py migrate +python manage.py resetsearchindexes ``` -WireCloud 1.0 added some predefined dashboards, so you have to create them by -running the following command: +WireCloud 1.0 added some predefined dashboards, so you have to create them by running the following command: -``` -$ python manage.py populate +```bash +python manage.py populate ``` -Also, WireCloud 1.0 provides support for real-time synchronization using web -sockets, see the [Enabling the real-time synchronization -support](installation_guide#enabling-the-real-time-synchronization-support) +Also, WireCloud 1.0 provides support for real-time synchronization using web sockets, see the +[Enabling the real-time synchronization support](installation_guide#enabling-the-real-time-synchronization-support) section for instructions on how to enable it. - ## From 0.8.x to 0.9.x ### IdM integration changes -- `FIWARE_PORTALS` has been change to be empty by default. You can add the - following code into your `settings.py` file for obtaining the previous - behaviour: +`FIWARE_PORTALS` has been change to be empty by default. You can add the following code into your `settings.py` file for +obtaining the previous behaviour: - ```python - from wirecloud.fiware import FIWARE_LAB_PORTALS - FIWARE_PORTALS = FIWARE_LAB_PORTALS - ``` +```python +from wirecloud.fiware import FIWARE_LAB_PORTALS +FIWARE_PORTALS = FIWARE_LAB_PORTALS +``` - See the [`FIWARE_PORTALS` documentation](installation_guide#fiware_portals) for more info. +See the [`FIWARE_PORTALS` documentation](installation_guide#fiware_portals) for more info. ### Upgrading to Django 1.7+ -Wirecloud 0.9.0+ adds support for Django 1.7-1.9 and next version of WireCloud -(1.0) will drop support for Django 1.6 and Django 1.7. Moreover, at the time of -releasing WireCloud 0.9.0, Django 1.6 and 1.7 were unsupported by the Django +Wirecloud 0.9.0+ adds support for Django 1.7-1.9 and next version of WireCloud (1.0) will drop support for Django 1.6 +and Django 1.7. Moreover, at the time of releasing WireCloud 0.9.0, Django 1.6 and 1.7 were unsupported by the Django community. -The only thing to take into account when upgrading your WireCloud installation -to use Django 1.7+ is that you need to migrate your db to Wirecloud 0.9.0 using -Django 1.6 and South before upgrading to the new version of Django. +The only thing to take into account when upgrading your WireCloud installation to use Django 1.7+ is that you need to +migrate your db to Wirecloud 0.9.0 using Django 1.6 and South before upgrading to the new version of Django. -Once migrated the database and installed the new version of Django, run -the following command for initializing the Django db migration framework: - - $ python manage.py migrate --fake-initial +Once migrated the database and installed the new version of Django, run the following command for initializing the +Django db migration framework: +```bash +python manage.py migrate --fake-initial +``` ## From 0.7.x to 0.8.x ### Migrate from `django-social-auth` to `python-social-auth` -WireCloud 0.8.x migrated FIWARE IdM code to use `python-social-auth` instead of -using `django-social-auth` due to the later being deprecated. Please, follow -these instructions if you are using the IdM integration: +WireCloud 0.8.x migrated FIWARE IdM code to use `python-social-auth` instead of using `django-social-auth` due to the +later being deprecated. Please, follow these instructions if you are using the IdM integration: -1. Install `python-social-auth` (e.g. `pip install python-social-auth`) -2. Edit your `settings.py` making the following changes: - 1. replace `social_auth` with `social.apps.django_app.default` in the - `INSTALLED_APPS` setting +- Install `python-social-auth` (e.g. `pip install python-social-auth`) +- Edit your `settings.py` making the following changes: + 1. replace `social_auth` with `social.apps.django_app.default` in the `INSTALLED_APPS` setting 2. replace `wirecloud.fiware.social_auth_backend.FiwareBackend` with - `wirecloud.fiware.social_auth_backend.FIWAREOAuth2` in the - `AUTHENTICATION_BACKENDS` setting. - 3. rename `FIWARE_APP_ID` to `SOCIAL_AUTH_FIWARE_KEY` and - `FIWARE_APP_SECRET` to `SOCIAL_AUTH_FIWARE_SECRET` -3. Edit your `urls.py` file and replace: + `wirecloud.fiware.social_auth_backend.FIWAREOAuth2` in the `AUTHENTICATION_BACKENDS` setting. + 3. rename `FIWARE_APP_ID` to `SOCIAL_AUTH_FIWARE_KEY` and `FIWARE_APP_SECRET` to `SOCIAL_AUTH_FIWARE_SECRET` +- Edit your `urls.py` file and replace: - ```python - url(r'', include('social_auth.urls')), - ``` +```python +url(r'', include('social_auth.urls')), +``` - with +    with - ```python - url('', include('social.apps.django_app.urls', namespace='social')) - ``` +```python +url('', include('social.apps.django_app.urls', namespace='social')) +``` -4. Fake `python-social-auth` migrations (it uses the same dabase schema than `django-social-auth`): +- Fake `python-social-auth` migrations (it uses the same dabase schema than `django-social-auth`): - ``` - $ python manage.py migrate default --fake - ``` +```bash +python manage.py migrate default --fake +``` -5. Now you can remove django-social-auth :). E.g.: +- Now you can remove django-social-auth :). E.g.: - ``` - $ pip uninstall django-social-auth - ``` +```bash +pip uninstall django-social-auth +``` ### Migrate the user search index -WireCloud 0.8.2 updated the information stored in the user search index, so you -should run the following command for updating this index: +WireCloud 0.8.2 updated the information stored in the user search index, so you should run the following command for +updating this index: -``` -$ python manage.py resetsearchindexes --indexes=user +```bash +python manage.py resetsearchindexes --indexes=user ``` ## From 0.6.x to 0.7.x -WireCloud 0.7.x adds support for using Whoosh indexes for searching, as -WireCloud 0.6.x didn't use Whoosh, you need to run an extra step when migrating -from 0.6.x to 0.7.x for creating a initial version of those indexes: +WireCloud 0.7.x adds support for using Whoosh indexes for searching, as WireCloud 0.6.x didn't use Whoosh, you need to +run an extra step when migrating from 0.6.x to 0.7.x for creating a initial version of those indexes: - $ python manage.py resetsearchindexes +```bash +python manage.py resetsearchindexes +``` diff --git a/docs/development/eclipse_ide.md b/docs/development/eclipse_ide.md index 50383f486a..ab74a583de 100644 --- a/docs/development/eclipse_ide.md +++ b/docs/development/eclipse_ide.md @@ -1,22 +1,19 @@ ## Installation -- Download the latest version of the "Eclipse IDE for Java EE - Developers" package for your platform from the +- Download the latest version of the "Eclipse IDE for Java EE Developers" package for your platform from the [Eclipse's downloads section][]. -- Download the WireCloud IDE plugin from the - [FIWARE PPP Public Files area]. +- Download the WireCloud IDE plugin from the [FIWARE PPP Public Files area]. - Install the WireCloud IDE plugin: - - *Help -> Install New Software...* + - _Help -> Install New Software..._ ![](../images/user_guide/WireCloudIDE/install_new_software.png) - - Add a new repository using the *Add* button + - Add a new repository using the _Add_ button ![](../images/user_guide/WireCloudIDE/add_repository.png) - - Click *Archive* and select the WireCloud IDE plugin file - downloaded in previous steps + - Click _Archive_ and select the WireCloud IDE plugin file downloaded in previous steps ![](../images/user_guide/WireCloudIDE/add_repository2.png) @@ -24,19 +21,16 @@ ![](../images/user_guide/WireCloudIDE/select_wirecloud_ide.png) - - Click *Next* and complete the wizard. - -[Eclipse's downloads section]: http://eclipse.org/downloads/ -[FIWARE PPP Public Files area]: https://forge.fiware.org/frs/?group_id=7 + - Click _Next_ and complete the wizard. +[eclipse's downloads section]: http://eclipse.org/downloads/ +[fiware ppp public files area]: https://forge.fiware.org/frs/?group_id=7 ## Adding WireCloud servers -WireCloud IDE support deploying Widget/Operator projects into WireCloud -servers. You can manage WireCloud servers from the "Server" view -(usually located in the lower half of Eclipse's development screen). If -you don't have such a view, you can add it via *Window -> Show View --> Servers*: +WireCloud IDE support deploying Widget/Operator projects into WireCloud servers. You can manage WireCloud servers from +the "Server" view (usually located in the lower half of Eclipse's development screen). If you don't have such a view, +you can add it via _Window -> Show View -> Servers_: ![](../images/user_guide/WireCloudIDE/open_server_view.png) @@ -44,25 +38,21 @@ you don't have such a view, you can add it via *Window -> Show View ![](../images/user_guide/WireCloudIDE/create_wirecloud_server1.png) -- In the next step, select WireCloud as the type of server to define - (you will find it under the CoNWeTLab category), update the host - name of the server where WireCloud is located and give it a name. - After filling this info, click *Next*: +- In the next step, select WireCloud as the type of server to define (you will find it under the CoNWeTLab category), + update the host name of the server where WireCloud is located and give it a name. After filling this info, click + _Next_: ![](../images/user_guide/WireCloudIDE/create_wirecloud_server2.png) -- Review the protocol and port configuration. You will also need to - provide a client id and a client secret obtained from the IdM (see - how to create new OAuth2 applications on the - [KeyRock's User and Programmers Guide]). You will need to use - `[WIRECLOUD_SERVER_URL]/oauth2/default_redirect_uri` as the - callback URL field. Once finished click *Next*: +- Review the protocol and port configuration. You will also need to provide a client id and a client secret obtained + from the IdM (see how to create new OAuth2 applications on the [KeyRock's User and Programmers Guide]). You will + need to use `[WIRECLOUD_SERVER_URL]/oauth2/default_redirect_uri` as the callback URL field. Once finished click + _Next_: ![](../images/user_guide/WireCloudIDE/create_wirecloud_server3.png) -- The next step is authorising WireCloud IDE to install and uninstall - resources on the server. This will require you to log in to the - WireCloud server. +- The next step is authorising WireCloud IDE to install and uninstall resources on the server. This will require you + to log in to the WireCloud server. ![](../images/user_guide/WireCloudIDE/create_wirecloud_server_signin.png) @@ -74,16 +64,14 @@ you don't have such a view, you can add it via *Window -> Show View ![](../images/user_guide/WireCloudIDE/create_wirecloud_server_autothized.png) -- At this step you can choose between clicking *Next* and selecting a - list of projects to upload initially to the server, or clicking - *Finish* as all the required info has been provided. In any case, - after finishing the wizard, a new WireCloud server should appear in - the "Server" tab: +- At this step you can choose between clicking _Next_ and selecting a list of projects to upload initially to the + server, or clicking _Finish_ as all the required info has been provided. In any case, after finishing the wizard, a + new WireCloud server should appear in the "Server" tab: ![](../images/user_guide/WireCloudIDE/wirecloud_server_created.png) -[KeyRock's User and Programmers Guide]: https://fi-ware-idm.readthedocs.org/en/latest/user_guide/#registering-an-application - +[keyrock's user and programmers guide]: + https://fi-ware-idm.readthedocs.org/en/latest/user_guide/#registering-an-application ## How to create Widget/Operator projects from scratch @@ -91,50 +79,43 @@ you don't have such a view, you can add it via *Window -> Show View ![](../images/user_guide/WireCloudIDE/create_widget_project1.png) -- And select the Widget/Operator project depending on the type of - resource you want to create (you will find them on the WireCloud - Project category): +- And select the Widget/Operator project depending on the type of resource you want to create (you will find them on + the WireCloud Project category): ![](../images/user_guide/WireCloudIDE/create_widget_project2.png) -- Give a name to the project and click *Finish*: +- Give a name to the project and click _Finish_: ![](../images/user_guide/WireCloudIDE/create_widget_project3.png) -Once created the project, you will obtain the following features in -addition to the ones provided directly by Eclipse: +Once created the project, you will obtain the following features in addition to the ones provided directly by Eclipse: - JavaScript API autocompletion. - Assistance for editing Widget/Operator descriptions. -- Support for installing and uninstalling them from the configure - WireCloud servers. - +- Support for installing and uninstalling them from the configure WireCloud servers. ## Tutorial -- First of all, download this initial code from this - [link](slides/attachments/Example1Skel.zip). This code contains a widget - example skeleton including basic html/style code. -- Import the downloaded file into a Widget project: +- First of all, download this initial code from this [link](slides/attachments/Example1Skel.zip). This code contains a + widget example skeleton including basic html/style code. +- Import the downloaded file into a Widget project: + + ![](../images/user_guide/WireCloudIDE/import_widget1.png) - ![](../images/user_guide/WireCloudIDE/import_widget1.png) - ![](../images/user_guide/WireCloudIDE/import_widget2.png) - ![](../images/user_guide/WireCloudIDE/import_widget3.png) + ![](../images/user_guide/WireCloudIDE/import_widget2.png) ![](../images/user_guide/WireCloudIDE/import_widget3.png) -- Follow the *3.1.3. Making requests and wiring* tutorial available on the - [WireCloud's course @ FIWARE - Academy](http://edu.fiware.org/course/view.php?id=53#section-3). -- Add the widget to the WireCloud server using the Servers view (see the [Adding - WireCloud servers](#adding-wirecloud-servers) sections for more info). The - first step is opening the "Add and remove ..." view: +- Follow the _3.1.3. Making requests and wiring_ tutorial available on the + [WireCloud's course @ FIWARE Academy](http://edu.fiware.org/course/view.php?id=53#section-3). +- Add the widget to the WireCloud server using the Servers view (see the + [Adding WireCloud servers](#adding-wirecloud-servers) sections for more info). The first step is opening the "Add + and remove ..." view: ![](../images/user_guide/WireCloudIDE/upload_widget1.png) -- Once opened the "Add and Remove" view, you will need to move the project from - the available section to the configured one: +- Once opened the "Add and Remove" view, you will need to move the project from the available section to the + configured one: ![](../images/user_guide/WireCloudIDE/upload_widget2.png) -- Click *Finish* and the widget will be uploaded to the selected server where you - will be able to test your widget following the steps documented on the - tutorial. +- Click _Finish_ and the widget will be uploaded to the selected server where you will be able to test your widget + following the steps documented on the tutorial. diff --git a/docs/development/macdl.md b/docs/development/macdl.md index 717d6e36cb..29bc9a9534 100644 --- a/docs/development/macdl.md +++ b/docs/development/macdl.md @@ -1,6 +1,4 @@ -Currently, WireCloud supports two variants or flavours of the Mashable -Application Component Description Langueage: +Currently, WireCloud supports two variants or flavours of the Mashable Application Component Description Langueage: -- The main flavour is based on the [XML](macdl_xml.md) syntax. -- WireCloud also supports [RDF](macdl_rdf.md) to allow adding semantic - annotation into MAC descriptions. +- The main flavour is based on the [XML](macdl_xml.md) syntax. +- WireCloud also supports [RDF](macdl_rdf.md) to allow adding semantic annotation into MAC descriptions. diff --git a/docs/development/macdl_rdf.md b/docs/development/macdl_rdf.md index 04a73c7410..da49d81741 100644 --- a/docs/development/macdl_rdf.md +++ b/docs/development/macdl_rdf.md @@ -1,520 +1,447 @@ -In order for Mashable Application Components to be offered in the [Store -GE], MACs should provide their metadata information using a format -supported by the FIWARE's Marketplace, Store and Repository Generic -Enablers. Those GE are based on the use of USDL documents (RDF), so the -Application Mashup GE supports a RDF flavour of the MACDL, built upon -Linked Data principles and making MAC description files linkable -directly from USDL documents. - -The RDF flavour of the MACDL is based on two new RDF vocabularies. The -first vocabulary, WIRE -(https://github.com/Wirecloud/wirecloud/blob/develop/src/wirecloud/commons/utils/template/schemas/wire.rdf), -deals with the definition of the information that the Application Mashup -GE must use to instantiate widgets and operators, including its user -preferences, persistent variables, wiring information, and so on. The -second vocabulary, WIRE-M -(https://github.com/Wirecloud/wirecloud/blob/develop/src/wirecloud/commons/utils/template/schemas/wire-m.rdf), -defines the mashup-related information needed to create an instance of -the user workspace, including platform-specific information such as -widget instances, wiring and piping between widgets and operators, etc. - -The following sections show both vocabularies, that can be used for -describing MACs using RDF. - -[Store GE]: https://github.com/conwetlab/wstore +In order for Mashable Application Components to be offered in the [Store GE], MACs should provide their metadata +information using a format supported by the FIWARE's Marketplace, Store and Repository Generic Enablers. Those GE are +based on the use of USDL documents (RDF), so the Application Mashup GE supports a RDF flavour of the MACDL, built upon +Linked Data principles and making MAC description files linkable directly from USDL documents. +The RDF flavour of the MACDL is based on two new RDF vocabularies. The first vocabulary, WIRE +(https://github.com/Wirecloud/wirecloud/blob/develop/src/wirecloud/commons/utils/template/schemas/wire.rdf), deals with +the definition of the information that the Application Mashup GE must use to instantiate widgets and operators, +including its user preferences, persistent variables, wiring information, and so on. The second vocabulary, WIRE-M +(https://github.com/Wirecloud/wirecloud/blob/develop/src/wirecloud/commons/utils/template/schemas/wire-m.rdf), defines +the mashup-related information needed to create an instance of the user workspace, including platform-specific +information such as widget instances, wiring and piping between widgets and operators, etc. + +The following sections show both vocabularies, that can be used for describing MACs using RDF. + +[store ge]: https://github.com/conwetlab/wstore ## WIRE vocabulary The diagram below shows the WIRE vocabulary. ![The WIRE vocabulary](../images/mac_description_rdf_wire_diagram.png) +
The `WIRE` vocabulary
-The Application Mashup GE must support this vocabulary to provide a way to represent MAC information as RDF and allow those descriptions to be used from USDL documents. +The Application Mashup GE must support this vocabulary to provide a way to represent MAC information as RDF and allow +those descriptions to be used from USDL documents. ### Classes #### The `wire:Widget` class -This class represents a widget. This is, jointly with `wire:Operator`, one of -the root classes of this vocabulary. +This class represents a widget. This is, jointly with `wire:Operator`, one of the root classes of this vocabulary. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/widget#Widget` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/widget#Widget` -- **Properties include**: `dcterms:title`, `dcterms:description`, - `dcterms:creator`, `usdl:hasProvider`, `usdl:utilizedResource`, `foaf:page`, - `wire:hasPlatformPreference`, `wire:hasPlatformWiring`, - `wire:hasPlatformRendering`, `wire:hasPlatformStateProperty`, - `usdl:versionInfo`, `wire:hasImageUri`, `wire.hasiPhoneImageUri`, - `wire:displayName`, `vcard:addr` - -- **Subclassof**: `usdl-core:Service` +- **Properties include**: `dcterms:title`, `dcterms:description`, `dcterms:creator`, `usdl:hasProvider`, + `usdl:utilizedResource`, `foaf:page`, `wire:hasPlatformPreference`, `wire:hasPlatformWiring`, + `wire:hasPlatformRendering`, `wire:hasPlatformStateProperty`, `usdl:versionInfo`, `wire:hasImageUri`, + `wire.hasiPhoneImageUri`, `wire:displayName`, `vcard:addr` +- **Subclassof**: `usdl-core:Service` #### The `wire:Operator` class -This class represents a operator. This is, jointly with `wire:Widget`, one of -the root classes of this vocabulary. - -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/widget#Operator` +This class represents a operator. This is, jointly with `wire:Widget`, one of the root classes of this vocabulary. -- **Properties include**: `dcterms:title`, `dcterms:description`, - `dcterms:creator`, `usdl:hasProvider`, `usdl:utilizedResource`, `foaf: page`, - `wire:hasPlatformPreference`, `wire:hasPlatformWiring`, - `wire:hasPlatformRendering`, `wire:hasPlatformStateProperty`, - `usdl:versionInfo`, `wire:hasImageUri`, `wire.hasiPhoneImageUri`, - `wire:displayName`, `vcard:addr` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/widget#Operator` -- **Subclassof**: `usdl-core:Service` +- **Properties include**: `dcterms:title`, `dcterms:description`, `dcterms:creator`, `usdl:hasProvider`, + `usdl:utilizedResource`, `foaf: page`, `wire:hasPlatformPreference`, `wire:hasPlatformWiring`, + `wire:hasPlatformRendering`, `wire:hasPlatformStateProperty`, `usdl:versionInfo`, `wire:hasImageUri`, + `wire.hasiPhoneImageUri`, `wire:displayName`, `vcard:addr` +- **Subclassof**: `usdl-core:Service` #### The `wire:PlatformPreference` class -This class represents a user preference in the Application Mashup GE, -that is, data users can see and configure. The Enabler must make this -value persistent and provide users with tools to edit and validate this -data. +This class represents a user preference in the Application Mashup GE, that is, data users can see and configure. The +Enabler must make this value persistent and provide users with tools to edit and validate this data. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/widget#PlatformPreference` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/widget#PlatformPreference` -- **Properties include**: `wire:hasOption`, `dcterms:title`, - `dcterms:description`, `rdfs:label`, `wire:type`, `wire:default`, - `wire:secure` - -- **Used with**: `wire:hasPlatformPreference` +- **Properties include**: `wire:hasOption`, `dcterms:title`, `dcterms:description`, `rdfs:label`, `wire:type`, + `wire:default`, `wire:secure` +- **Used with**: `wire:hasPlatformPreference` #### The `wire:PlatformWiring` class This class represents the wiring status of a widget. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/widget#PlatformWiring` - -- **Properties include**: `wire:hasOutputEndpoint, wire:hasInputEnpoint` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/widget#PlatformWiring` -- **Used with**: `wire:hasPlatformWiring` +- **Properties include**: `wire:hasOutputEndpoint, wire:hasInputEnpoint` +- **Used with**: `wire:hasPlatformWiring` #### The `wire:PlatformRendering` class This class represents the widget size when it is instantiated. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/widget#PlatformRendering` - -- **Properties include**: `wire:renderingWidth`, `wire.renderingHeight` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/widget#PlatformRendering` -- **Used with**: `wire:hasPlatformRendering` +- **Properties include**: `wire:renderingWidth`, `wire.renderingHeight` +- **Used with**: `wire:hasPlatformRendering` #### The `wire:PlatformStateProperty` class -This class represents a widget state variable that the platform needs to -know in order to make it persistent. +This class represents a widget state variable that the platform needs to know in order to make it persistent. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/widget#PlatformStateProperty` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/widget#PlatformStateProperty` -- **Properties include**: `dcterms:title`, `dcterms:description`, `wire:type`, - `rdfs:label`, `wire:default`, `wire:secure`, `wire:multiuser` - -- **Used with**: `wire:hasPlatformStateProperty` +- **Properties include**: `dcterms:title`, `dcterms:description`, `wire:type`, `rdfs:label`, `wire:default`, + `wire:secure`, `wire:multiuser` +- **Used with**: `wire:hasPlatformStateProperty` #### The `wire:Option` class This class represents an option that a user preference could have. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/widget#Option` - -- **Properties include**: `dcterms:title`, `wire:value` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/widget#Option` -- **Used with**: `wire:hasOption` +- **Properties include**: `dcterms:title`, `wire:value` +- **Used with**: `wire:hasOption` #### The `wire:OutputEndpoint` class This class represents an output endpoint. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/widget#OutputEndpoint` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/widget#OutputEndpoint` -- **Properties include**: `dcterms:title`, `dcterms:description`, `rdfs:label`, - `wire:type`, `wire:friendcode` - -- **Used with**: `wire:hasOutputEndpoint` +- **Properties include**: `dcterms:title`, `dcterms:description`, `rdfs:label`, `wire:type`, `wire:friendcode` +- **Used with**: `wire:hasOutputEndpoint` #### The `wire:InputEndpoint` class This class represents an input endpoint. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/widget#InputEndpoint` - -- **Properties include**: `dcterms:title`, `dcterms:description`, `rdfs:label`, - `wire:type`, `wire:friendcode`, `wire:actionLabel` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/widget#InputEndpoint` -- **Used with**: `wire:hasInputEndpoint` +- **Properties include**: `dcterms:title`, `dcterms:description`, `rdfs:label`, `wire:type`, `wire:friendcode`, + `wire:actionLabel` +- **Used with**: `wire:hasInputEndpoint` ### Properties - #### The `wire:hasPlatformPreference` property This property states a user widget preference. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#hasPlatformPreference` -- **Domain**: `wire:Widget` -- **Range**: `wire:PlatformPreference` - +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#hasPlatformPreference` +- **Domain**: `wire:Widget` +- **Range**: `wire:PlatformPreference` #### The `wire:hasPlatformWiring` property This property states the widget wiring status. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#hasPlatformWiring` -- **Domain**: `wire:Widget` -- **Range**: `wire:PlatformWiring` - +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#hasPlatformWiring` +- **Domain**: `wire:Widget` +- **Range**: `wire:PlatformWiring` #### The `wire:hasPlatformRendering` property This property states how the widget must be rendered. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#hasPlatformRendering` -- **Domain**: `wire:Widget` -- **Range**: `wire:PlatformRendering` - +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#hasPlatformRendering` +- **Domain**: `wire:Widget` +- **Range**: `wire:PlatformRendering` #### The `wire:hasPlatformStateProperty` property This property states a widget persistent variable. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#hasPlatformStateProperty` -- **Domain**: `wire:Widget` -- **Range**: `wire:PlatformStateProperty` - +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#hasPlatformStateProperty` +- **Domain**: `wire:Widget` +- **Range**: `wire:PlatformStateProperty` #### The `wire:hasOption` property This property states a user preference option. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#hasOption` -- **Domain**: `wire:PlatformPreference` -- **Range**: `wire:Option` - +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#hasOption` +- **Domain**: `wire:PlatformPreference` +- **Range**: `wire:Option` #### The `wire:hasOutputEndpoint` property This property states a widget wiring output endpoint. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#hasOutputEndpoint` -- **Domain**: `wire:PlatformWiring` -- **Range**: `wire:OutputEndpoint` - +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#hasOutputEndpoint` +- **Domain**: `wire:PlatformWiring` +- **Range**: `wire:OutputEndpoint` #### The `wire:hasInputEndpoint` property This property states a widget wiring input endpoint. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#hasInputEndpoint` -- **Domain**: `wire:PlatformWiring` -- **Range**: `wire:InputEndpoint` - +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#hasInputEndpoint` +- **Domain**: `wire:PlatformWiring` +- **Range**: `wire:InputEndpoint` #### The `wire:friendcode` property -This property states a *friendcode*. - -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#friendcode` -- **Domain**: `wire:InputEndpoint` and `wire:OutputEndpoint` -- **Range**: `rdfs:Literal` +This property states a _friendcode_. +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#friendcode` +- **Domain**: `wire:InputEndpoint` and `wire:OutputEndpoint` +- **Range**: `rdfs:Literal` #### The `wire:actionLabel` property This property states an input's action label. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#actionLabel` -- **Domain**: `wire:InputEndpoint` -- **Range**: `rdfs:Literal` - +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#actionLabel` +- **Domain**: `wire:InputEndpoint` +- **Range**: `rdfs:Literal` #### The `wire:hasImageUri` property This property states the URI of the image associated with the widget. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#hasImageUri` -- **Domain**: `wire:Widget` -- **Range**: `foaf:Image` - +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#hasImageUri` +- **Domain**: `wire:Widget` +- **Range**: `foaf:Image` #### The `wire:hasiPhoneImageUri` property -This property states the URI of the image associated with the Widget if -the platform is running on an iPhone. - -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#hasiPhoneImageUri` -- **Domain**: `wire:Widget` -- **Range**: `foaf:Image` +This property states the URI of the image associated with the Widget if the platform is running on an iPhone. +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#hasiPhoneImageUri` +- **Domain**: `wire:Widget` +- **Range**: `foaf:Image` #### The `wire:displayName` property This property states the widget name to be displayed. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#displayName` -- **Domain**: `wire:Widget` -- **Range**: `rdfs:Literal` - +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#displayName` +- **Domain**: `wire:Widget` +- **Range**: `rdfs:Literal` #### The `wire:value` property This property states the widget configuration element value. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#value` -- **Range**: `rdfs:Literal` - +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#value` +- **Range**: `rdfs:Literal` #### The `wire:type` property This property states the widget configuration element type. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#type` -- **Range**: `rdfs:Literal` - +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#type` +- **Range**: `rdfs:Literal` #### The `wire:default` property This property states the widget configuration element default value. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#default` -- **Range**: `rdfs:Literal` - +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#default` +- **Range**: `rdfs:Literal` #### The `wire:secure` property -This property states whether or not a widget configuration element is -secure. - -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#value` -- **Range**: `rdfs:Literal` +This property states whether or not a widget configuration element is secure. +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#value` +- **Range**: `rdfs:Literal` #### The `wire:multiuser` property -This property states whether or not a component persistent variable is -multiuser. Multiuser persistent variables store a value for each user with access rights to the dashboard. - -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#value` -- **Range**: `rdfs:Literal` +This property states whether or not a component persistent variable is multiuser. Multiuser persistent variables store a +value for each user with access rights to the dashboard. +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#value` +- **Range**: `rdfs:Literal` #### The `wire:index` property This property states the logical order of elements of the same type. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#value` -- **Range**: `rdfs:Literal` - +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#value` +- **Range**: `rdfs:Literal` #### The `wire:codeContentType` property -This property states the widget code MIME type. The widget code URI is -represented using `usdl-core:Resource` - -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#codeContentType` -- **Domain**: `usdl-core:Resource` -- **Range**: `rdfs:Literal` +This property states the widget code MIME type. The widget code URI is represented using `usdl-core:Resource` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#codeContentType` +- **Domain**: `usdl-core:Resource` +- **Range**: `rdfs:Literal` #### The `wire:codeCacheable` property This property states whether or not the widget code is cacheable. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#codeCacheable` -- **Domain**: `usdl-core:Resource` -- **Range**: `rdfs:Literal` - +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/Widget#codeCacheable` +- **Domain**: `usdl-core:Resource` +- **Range**: `rdfs:Literal` ## WIRE-M vocabulary The diagram below shows the WIRE-M vocabulary. ![The WIRE-M vocabulary](../images/mac_description_rdf_wire-m_diagram.png) -
The `WIRE-M` vocabulary
-Like the WIRE vocabulary, this vocabulary must be supported by the Application -Mashup GE implementations to provide a way to represent Mashup information using -RDF and allow those descriptions to be used from USDL documents. +
The `WIRE-M` vocabulary
+Like the WIRE vocabulary, this vocabulary must be supported by the Application Mashup GE implementations to provide a +way to represent Mashup information using RDF and allow those descriptions to be used from USDL documents. ### Classes - #### The `wire-m:Mashup` class This class represents a mashup. It will be implemented as a workspace. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#Mashup` - -- **Properties include**: `wire-m:hasMashupPreference`, `wire-m:hasMashupParam`, - `wire-m:hasTab`, `wire-m:hasMashupWiring`, `wire:hasImageUri`, - `wire:hasiPhoneImageUri`, `wire:version` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#Mashup` -- **subClassOf**: `usdl:CompositeService` +- **Properties include**: `wire-m:hasMashupPreference`, `wire-m:hasMashupParam`, `wire-m:hasTab`, + `wire-m:hasMashupWiring`, `wire:hasImageUri`, `wire:hasiPhoneImageUri`, `wire:version` +- **subClassOf**: `usdl:CompositeService` #### The `wire-m:Tab` class This class represents a workspace tab. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#Tab` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#Tab` -- **Properties include**: `wire-m:hasiWidget`, `wire-m:hasTabPreference`, - `dcterms:title` - -- **Used with**: `wire-m:hasTab` +- **Properties include**: `wire-m:hasiWidget`, `wire-m:hasTabPreference`, `dcterms:title` +- **Used with**: `wire-m:hasTab` #### The `wire-m:iWidget` class This class represents a widget instance. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#iWidget` - -- **Properties include**: `wire-m:hasPosition`, `wire-m:hasiWidgetRendering`, - `wire-m:hasiWidgetPreference`, `wire-m:hasiWidgetProperty ` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#iWidget` -- **Used with**: `wire-m:hasiWidget` +- **Properties include**: `wire-m:hasPosition`, `wire-m:hasiWidgetRendering`, `wire-m:hasiWidgetPreference`, + `wire-m:hasiWidgetProperty` -- **subClassOf**: `wire:Widget` +- **Used with**: `wire-m:hasiWidget` +- **subClassOf**: `wire:Widget` #### The `wire-m:MashupPreference` class This class represents a mashup preference. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#MashupPreference` - -- **Properties include**: `dcterms:title`, `wire:value` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#MashupPreference` -- **Used with**: `wire-m:hasMashupPreference` +- **Properties include**: `dcterms:title`, `wire:value` +- **Used with**: `wire-m:hasMashupPreference` #### The `wire-m:MashupParam` class This class represents a mashup parameter. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#MashupParam` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#MashupParam` -- **Properties include**: `dcterms:title`, `wire:value` - -- **Used with**: `wire-m:hasMashupParam` +- **Properties include**: `dcterms:title`, `wire:value` +- **Used with**: `wire-m:hasMashupParam` #### The `wire-m:Position` class This class represents the position of a widget instance in the tab. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#Position` - -- **Properties include**: `wire-m:x, wire-m:y, wire-m:z` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#Position` -- **Used with**: `wire-m:hasPosition` +- **Properties include**: `wire-m:x, wire-m:y, wire-m:z` +- **Used with**: `wire-m:hasPosition` #### The `wire-m:iWidgetPreference` class This class represents a widget instance preference. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#iWidgetPreference` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#iWidgetPreference` -- **Properties include**: `dcterms:title`, `wire:value`, `wire-m:readonly`, `wire-m:hidden` - -- **Used with**: `wire-m:hasiWidgetPreference` +- **Properties include**: `dcterms:title`, `wire:value`, `wire-m:readonly`, `wire-m:hidden` +- **Used with**: `wire-m:hasiWidgetPreference` #### The `wire-m:iWidgetRendering` class This class represents a widget instance rendering. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#iWidgetRendering` - -- **Properties include**: `wire-m:fullDragboard`, `wire-m:layout`, - `wire-m:minimized`, `wire:renderingHeight`, `wire:renderingWidth` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#iWidgetRendering` -- **Used with**: `wire-m:hasiWidgetRendering` +- **Properties include**: `wire-m:fullDragboard`, `wire-m:layout`, `wire-m:minimized`, `wire:renderingHeight`, + `wire:renderingWidth` +- **Used with**: `wire-m:hasiWidgetRendering` #### The `wire-m:iWidgetProperty` class This class represents a widget instance property. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#iWidgetProperty` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#iWidgetProperty` -- **Properties include**: `wire-m:readonly`, `wire:value` - -- **Used with**: `wire-m:hasiWidgetProperty` +- **Properties include**: `wire-m:readonly`, `wire:value` +- **Used with**: `wire-m:hasiWidgetProperty` #### The `wire-m:TabPreference` class This class represents a tab preference. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#TabPreference` - -- **Properties include**: `dcterms:title`, `wire:value` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#TabPreference` -- **Used with**: `wire-m:hasTabPreference` +- **Properties include**: `dcterms:title`, `wire:value` +- **Used with**: `wire-m:hasTabPreference` #### The `wire-m:Connection` class -This class represents a wiring connection between two widget instances -or operator instances. +This class represents a wiring connection between two widget instances or operator instances. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#Connection` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#Connection` -- **Properties include**: `wire-m:hasSource`, `wire-m:hasTarget`, - `dcterms:title`, `wire-m:readonly` - -- **Used with**: `wire-m:hasConnection` +- **Properties include**: `wire-m:hasSource`, `wire-m:hasTarget`, `dcterms:title`, `wire-m:readonly` +- **Used with**: `wire-m:hasConnection` #### The `wire-m:Source` class -This class represents a widget instance or operator instance that is the -source of a connection. - -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#Source` +This class represents a widget instance or operator instance that is the source of a connection. -- **Properties include**: `wire-m:sourceId`, `wire-m:endpoint`, `wire:type` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#Source` -- **Used with**: `wire-m:hasSource` +- **Properties include**: `wire-m:sourceId`, `wire-m:endpoint`, `wire:type` +- **Used with**: `wire-m:hasSource` #### The `wire-m:Target` class -This class represents a widget instance or operator instance that is the -target of a connection. - -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#Target` +This class represents a widget instance or operator instance that is the target of a connection. -- **Properties include**: `wire-m:targetId`, `wire-m:endpoint`, `wire:type` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#Target` -- **Used with**: `wire-m:hasTarget` +- **Properties include**: `wire-m:targetId`, `wire-m:endpoint`, `wire:type` +- **Used with**: `wire-m:hasTarget` #### The `wire-m:iOperator` class This class represents an operator instance inside a wiring configuration. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#iOperator` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#iOperator` -- **Properties include**: `wire-m:iOperatorId, dcterms:title` - -- **Used with**: `wire-m:hasiOperator` +- **Properties include**: `wire-m:iOperatorId, dcterms:title` +- **Used with**: `wire-m:hasiOperator` ### Properties @@ -522,266 +449,234 @@ This class represents an operator instance inside a wiring configuration. This property states a mashup preference. -- **URI**: -`http://wirecloud.conwet.fi.upm.es/ns/mashup#hasMashupPreference` - -- **Domain**: `wire-m:Mashup` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#hasMashupPreference` -- **Range**: `wire-m:MashupPreference` +- **Domain**: `wire-m:Mashup` +- **Range**: `wire-m:MashupPreference` #### The `wire-m:hasMashupParam` property This property states a mashup parameter. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#hasMashupParam` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#hasMashupParam` -- **Domain**: `wire-m:Mashup` - -- **Range**: `wire-m:MashupParam` +- **Domain**: `wire-m:Mashup` +- **Range**: `wire-m:MashupParam` #### The `wire-m:hasTab` property This property states that a given tab is part of a workspace. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#hasTab` - -- **Domain**: `wire-m:Mashup` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#hasTab` -- **Range**: `wire-m:Tab` +- **Domain**: `wire-m:Mashup` +- **Range**: `wire-m:Tab` #### The `wire-m:hasiWidget` property -This property states that a given widget instance is instantiated in a -tab. +This property states that a given widget instance is instantiated in a tab. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#hasiWidget` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#hasiWidget` -- **Domain**: `wire-m:Tab` - -- **Range**: `wire-m:iWidget` +- **Domain**: `wire-m:Tab` +- **Range**: `wire-m:iWidget` #### The `wire-m:hasTabPreference` property This property states a tab preference. -- **URI**: -`http://wirecloud.conwet.fi.upm.es/ns/mashup#hasTabPreference` - -- **Domain**: `wire-m:Tab` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#hasTabPreference` -- **Range**: `wire-m:TabPreference` +- **Domain**: `wire-m:Tab` +- **Range**: `wire-m:TabPreference` #### The `wire-m:hasPosition` property This property states the position of an widget instance in a tab. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#hasPosition` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#hasPosition` -- **Domain**: `wire-m:iWidget` - -- **Range**: `wire-m:Position` +- **Domain**: `wire-m:iWidget` +- **Range**: `wire-m:Position` #### The `wire-m:hasiWidgetPreference` property This property states a widget instance preference. -- **URI**: -`http://wirecloud.conwet.fi.upm.es/ns/mashup#hasiWidgetPreference` - -- **Domain**: `wire-m:iWidget` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#hasiWidgetPreference` -- **Range**: `wire-m:iWidgetPreference` +- **Domain**: `wire-m:iWidget` +- **Range**: `wire-m:iWidgetPreference` #### The `wire-m:hasiWidgetProperty` property This property states a widget instance property. -- **URI**: -`http://wirecloud.conwet.fi.upm.es/ns/mashup#hasiWidgetProperty` - -- **Domain**: `wire-m:iWidget` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#hasiWidgetProperty` -- **Range**: `wire-m:iWidgetProperty` +- **Domain**: `wire-m:iWidget` +- **Range**: `wire-m:iWidgetProperty` #### The `wire-m:hasiWidgetRendering` property This property states the rendering of a widget instance. -- **URI**: -`http://wirecloud.conwet.fi.upm.es/ns/mashup#hasiWidgetRendering` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#hasiWidgetRendering` -- **Domain**: `wire-m:iWidget` - -- **Range**: `wire-m:iWidgetRendering` +- **Domain**: `wire-m:iWidget` +- **Range**: `wire-m:iWidgetRendering` #### The `wire-m:hasConnection` property This property states a wiring connection. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#hasConnection` - -- **Domain**: `wire:PlatformWiring` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#hasConnection` -- **Range**: `wire-m:Connection` +- **Domain**: `wire:PlatformWiring` +- **Range**: `wire-m:Connection` #### The `wire-m:hasSource` property This property states the source of a connection. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#hasSource` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#hasSource` -- **Domain**: `wire-m:Connection` - -- **Range**: `wire-m:Source` +- **Domain**: `wire-m:Connection` +- **Range**: `wire-m:Source` #### The `wire-m:hasTarget` property This property states the target of a connection. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#hasTarget` - -- **Domain**: `wire-m:Connection` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#hasTarget` -- **Range**: `wire-m:Target` +- **Domain**: `wire-m:Connection` +- **Range**: `wire-m:Target` #### The `wire-m:targetId` property This property states the ID of a target. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#targetId` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#targetId` -- **Domain**: `wire-m:Target` - -- **Range**: `rdfs:Literal` +- **Domain**: `wire-m:Target` +- **Range**: `rdfs:Literal` #### The `wire-m:sourceId` property This property states the ID of a source. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#sourceId` - -- **Domain**: `wire-m:Source` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#sourceId` -- **Range**: `rdfs:Literal` +- **Domain**: `wire-m:Source` +- **Range**: `rdfs:Literal` #### The `wire-m:endpoint` property -This property states the ID of the widget instance or operator instance -that is the source or target of a connection. +This property states the ID of the widget instance or operator instance that is the source or target of a connection. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#endpoint` - -- **Range**: `rdfs:Literal` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#endpoint` +- **Range**: `rdfs:Literal` #### The `wire-m:hasiOperator` property This property states the wiring of an operator's instance. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#hasiOperator` - -- **Domain**: `wire:PlatformWiring` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#hasiOperator` -- **Range**: `wire-m:iOperator` +- **Domain**: `wire:PlatformWiring` +- **Range**: `wire-m:iOperator` #### The `wire-m:x` property This property states the x coordinate of a widget instance position. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#x` - -- **Domain**: `wire-m:Position` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#x` -- **Range**: `rdfs:Literal` +- **Domain**: `wire-m:Position` +- **Range**: `rdfs:Literal` #### The `wire-m:y` property This property states the y coordinate of a widget instance position. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#y` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#y` -- **Domain**: `wire-m:Position` - -- **Range**: `rdfs:Literal` +- **Domain**: `wire-m:Position` +- **Range**: `rdfs:Literal` #### The `wire-m:z` property This property states the z coordinate of a widget instance position. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#z` - -- **Domain**: `wire-m:Position` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#z` -- **Range**: `rdfs:Literal` +- **Domain**: `wire-m:Position` +- **Range**: `rdfs:Literal` #### The `wire-m:fullDragboard` property -This property states whether a widget instance occupies the whole space -in the tab. +This property states whether a widget instance occupies the whole space in the tab. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#fullDragboard` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#fullDragboard` -- **Domain**: `wire-m:iWidgetRendering` - -- **Range**: `rdfs:Literal` +- **Domain**: `wire-m:iWidgetRendering` +- **Range**: `rdfs:Literal` #### The `wire-m:layout` property This property states the layout of a widget instance. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#layout` - -- **Domain**: `wire-m:iWidgetRendering` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#layout` -- **Range**: `rdfs:Literal` +- **Domain**: `wire-m:iWidgetRendering` +- **Range**: `rdfs:Literal` #### The `wire-m:minimized` property This property states whether a widget instance is minimized in its tab. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#minimized` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#minimized` -- **Domain**: `wire-m:iWidgetRendering` - -- **Range**: `rdfs:Literal` +- **Domain**: `wire-m:iWidgetRendering` +- **Range**: `rdfs:Literal` #### The `wire-m:hidden` property This property states whether a widget instance is hidden in its tab. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#hidden` - -- **Domain**: `wire-m:iWidgetPreference` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#hidden` -- **Range**: `rdfs:Literal` +- **Domain**: `wire-m:iWidgetPreference` +- **Range**: `rdfs:Literal` #### The `wire-m:readonly` property -This property states whether a mashup configuration element is read -only. +This property states whether a mashup configuration element is read only. -- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#readonly` +- **URI**: `http://wirecloud.conwet.fi.upm.es/ns/mashup#readonly` -- **Range**: `rdfs:Literal` +- **Range**: `rdfs:Literal` diff --git a/docs/development/macdl_xml.md b/docs/development/macdl_xml.md index 15bdc5d8d2..7a25ead5c0 100644 --- a/docs/development/macdl_xml.md +++ b/docs/development/macdl_xml.md @@ -1,451 +1,356 @@ ## Introduction -The latest version of the XML Schema described in the following sections -is available at: +The latest version of the XML Schema described in the following sections is available at: - [Mashable application component description language XML Schema] -Mashable application components descriptions use the -`http://wirecloud.conwet.fi.upm.es/ns/macdescription/1` namespace for -the root element. The name of the root element varies depending on the -type of the component: `widget`, `operator` or `mashup`. Whereas it always -require the following attributes: - -- `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. - -These tree fields (`vendor`, `name` and `version`) uniquely identify the -mashable application component, therefore there can not be a repetition -of such identifier in any collection of WireCloud components (including -widgets, mashups, operators, ...). - - [Mashable application component description language XML Schema]: https://github.com/Wirecloud/wirecloud/blob/develop/src/wirecloud/commons/utils/template/schemas/xml_schema.xsd +Mashable application components descriptions use the `http://wirecloud.conwet.fi.upm.es/ns/macdescription/1` namespace +for the root element. The name of the root element varies depending on the type of the component: `widget`, `operator` +or `mashup`. Whereas it always require the following attributes: + +- `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. + +These tree fields (`vendor`, `name` and `version`) uniquely identify the mashable application component, therefore there +can not be a repetition of such identifier in any collection of WireCloud components (including widgets, mashups, +operators, ...). + +[mashable application component description language xml schema]: + https://github.com/Wirecloud/wirecloud/blob/develop/src/wirecloud/commons/utils/template/schemas/xml_schema.xsd ## Common metadata ### details element ![](../images/mac_description_details_element.png) +
The `details` element
-Mashable application components descriptions should provide generic -information about what you will obtain by using it, information about -who develops the component, etc... All this generic information is -provided through the `details` element. This element can contain any of -the following elements: - -- `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. +Mashable application components descriptions should provide generic information about what you will obtain by using it, +information about who develops the component, etc... All this generic information is provided through the `details` +element. This element can contain any of the following elements: + +- `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 (http://barnyrubble.tumblr.com/) -- `contributors`: Comma separated list of contributors. Same format - than the authors field. -- `email`: E-mail address for getting support. It is recommend to - provide, at least, this field or the issuetracker as these fields - are helpful for people who encounter issues with the component. -- `license`: Name of the license associated to the mashable - application component. -- `licenseurl`: Absolute or description-file-relative URL pointing - to the full license document. -- `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 description-file-relative URL of the mashable - application component image for the catalogue. (170x80px) +- `contributors`: Comma separated list of contributors. Same format than the authors field. +- `email`: E-mail address for getting support. It is recommend to provide, at least, this field or the issuetracker as + these fields are helpful for people who encounter issues with the component. +- `license`: Name of the license associated to the mashable application component. +- `licenseurl`: Absolute or description-file-relative URL pointing to the full license document. +- `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 description-file-relative URL of the mashable application component image for the catalogue. + (170x80px) - `smartphone`: Image to be used in smartphones. (59x60px) -- `doc`: Relative path to the markdown file containing the mashable - application component documentation. For backwards compatibility, - this field also supports an absolute URL to the documentation of the - component (pointing to a web page). -- `issuetracker`: Absolute URL to the component's issue tracker. It - is recommend to provide, at least, this field or the `email` one as - these fields are helpful for people who encounter issues with - the component. - +- `doc`: Relative path to the markdown file containing the mashable application component documentation. For backwards + compatibility, this field also supports an absolute URL to the documentation of the component (pointing to a web + page). +- `issuetracker`: Absolute URL to the component's issue tracker. It is recommend to provide, at least, this field or + the `email` one as these fields are helpful for people who encounter issues with the component. ### The `requirements` element ![](../images/mac_description_requirements_element.png) +
The `requirements` element
-The `requirements` element is used for declaring on which features the -component depends on. Currently those features are associated with the -injection (by WireCloud) of the API required for accessing a given -feature (e.g. a widget can depend on the NGSI feature to notify -WireCloud it requires the injection of the NGSI API). In future releases -of the Application Mashup GE this element will provide support for -adding other kind of dependencies (e.g. with another mashable -application component), but for now this element only accepts `feature` -sub-elements. +The `requirements` element is used for declaring on which features the component depends on. Currently those features +are associated with the injection (by WireCloud) of the API required for accessing a given feature (e.g. a widget can +depend on the NGSI feature to notify WireCloud it requires the injection of the NGSI API). In future releases of the +Application Mashup GE this element will provide support for adding other kind of dependencies (e.g. with another +mashable application component), but for now this element only accepts `feature` sub-elements. #### The `feature` element -- `name`: Name of the feature required by the application - mashup component. - +- `name`: Name of the feature required by the application mashup component. ## Platform-component interaction elements -To guarantee the platform-component interaction, templates also define a -set of elements that components use to get connected to the environment -and set different platform options. Likewise, it also defines some other -interface elements, such as the initial widget size. They are all -managed by the platform, which will ensure their persistence. +To guarantee the platform-component interaction, templates also define a set of elements that components use to get +connected to the environment and set different platform options. Likewise, it also defines some other interface +elements, such as the initial widget size. They are all managed by the platform, which will ensure their persistence. Let us go through all these elements: - ### The `preferences` element The first platform-related element is the `preferences` one: ![](../images/mac_description_preferences_element.png) -
The `preferences` element
+
The `preferences` element
-It defines user preferences, which may be changed through the platform -interface. This element is made up of one, many or none `preference` -sub-elements. This defines the actual user preference. It requires the -following attributes: +It defines user preferences, which may be changed through the platform interface. This element is made up of one, many +or none `preference` sub-elements. This defines the actual user preference. It requires the following attributes: -- `type`: preference data type: `text` (string), `number`, `boolean`, - `password` and `list`. +- `type`: preference data type: `text` (string), `number`, `boolean`, `password` and `list`. - `name`: name of the preference to be referenced in the source code. - `label`: text that the preference will show in the user interface. - `description`: text that describes the preference. - `default`: preference default value. - `readonly`: indicates whether this preference can be modified. -- `value`: initial value. If not specified, the default value will - be used as the initial value. -- `secure`: access to the value of this preference is disallowed if - the value of this attribute is true (the value of this preference - will be usable through the Application Mashup cross-domain proxy). - default: `false`. - -If the `type` attribute is set to `list`, the different choices are -defined by means of the `option` element. It has the following -attributes: +- `value`: initial value. If not specified, the default value will be used as the initial value. +- `secure`: access to the value of this preference is disallowed if the value of this attribute is true (the value of + this preference will be usable through the Application Mashup cross-domain proxy). default: `false`. + +If the `type` attribute is set to `list`, the different choices are defined by means of the `option` element. It has the +following attributes: - `label`: text to be displayed in the selection list. - `value`: value to be used when the option is selected. - ### The persistentvariables element -The next XML element is the `persistentvariables` element. Its -main purpose is to define a set of variables to store the state of the -widget/operator while it is executing, in order to have it available for -future executions. Its structure is shown in the figure below: +The next XML element is the `persistentvariables` element. Its main purpose is to define a set of variables to store the +state of the widget/operator while it is executing, in order to have it available for future executions. Its structure +is shown in the figure below: ![](../images/mac_description_persistentvariables_element.png) -
The `persistentvariables` element
+
The `persistentvariables` element
-This element is made up of a list of `variable` elements that require the -following attributes: +This element is made up of a list of `variable` elements that require the following attributes: - `name`: property name. -- `type`: property data type: only `text` (string) datatype does - make sense in here. +- `type`: property data type: only `text` (string) datatype does make sense in here. - `label`: text to be displayed in the user interface. - `description`: Descriptive text. -- `secure`: Access to the value of this persistent variable is - disallowed if the value of this attribute is true (the value of this - variable will be usable through the Application Mashup - cross-domain proxy). default: `false`. +- `secure`: Access to the value of this persistent variable is disallowed if the value of this attribute is true (the + value of this variable will be usable through the Application Mashup cross-domain proxy). default: `false`. - `multiuser`: This persisten value will store it's own value for each user with access rigths to the dashboard. - ### The wiring element -This is probably one of the most important elements. It defines both the -inputs and outputs needed by widgets/operators to intercommunicate with -other widgets/operators. The Application Mashup GE implementation must -take this information into account to manage and control the wiring -mechanism and its internal data flow. +This is probably one of the most important elements. It defines both the inputs and outputs needed by widgets/operators +to intercommunicate with other widgets/operators. The Application Mashup GE implementation must take this information +into account to manage and control the wiring mechanism and its internal data flow. The figure below depicts the `wiring` element: ![](../images/mac_description_wiring_element.png) -
The `wiring` element
+
The `wiring` element
-This element may contain any number of `inputendpoint` and -`outputendpoint` elements. +This element may contain any number of `inputendpoint` and `outputendpoint` elements. -Widgets and operators may send data (events) through an output endpoint. -To do so, they must declare the endpoint using the `outputendpoint` -element. These elements have the following attributes: +Widgets and operators may send data (events) through an output endpoint. To do so, they must declare the endpoint using +the `outputendpoint` element. These elements have the following attributes: - `name`: output endpoint name. -- `type`: output endpoint data type: only `text` (string) datatype - does make sense in here. +- `type`: output endpoint data type: only `text` (string) datatype does make sense in here. - `label`: text to be displayed in the user interface. - `description`: text that describes the output. -- `friendcode`: One or more space-separated keywords used as output endpoint tags: it will help - the platform to make suggestions in the wiring process. +- `friendcode`: One or more space-separated keywords used as output endpoint tags: it will help the platform to make + suggestions in the wiring process. -On the other hand, widgets and operators can receive asynchronous data -through the input endpoints. These endpoints are meant to be used by -widgets and operators for receiving data (events) coming from other -widgets/operators. The `inputendpoint` element supports the -following attributes: +On the other hand, widgets and operators can receive asynchronous data through the input endpoints. These endpoints are +meant to be used by widgets and operators for receiving data (events) coming from other widgets/operators. The +`inputendpoint` element supports the following attributes: - `name`: input endpoint name. -- `type`: input endpoint data type: only `text` (string) datatype - does make sense in here. +- `type`: input endpoint data type: only `text` (string) datatype does make sense in here. - `label`: text to be displayed in the user interface. -- `actionlabel`: short text that describes what is going to happen - if an event is sent to this input endpoint. Widgets could use this - text in buttons, selection boxes, etc... allowing end users to - select what to do (and the widget will send an event to the - associated target endpoint) +- `actionlabel`: short text that describes what is going to happen if an event is sent to this input endpoint. Widgets + could use this text in buttons, selection boxes, etc... allowing end users to select what to do (and the widget will + send an event to the associated target endpoint) - `description`: text that describes the input. -- `friendcode`: One or more space-separated keywords used as input endpoint tags: it will help - the platform to make suggestions in the wiring process. - +- `friendcode`: One or more space-separated keywords used as input endpoint tags: it will help the platform to make + suggestions in the wiring process. ## Specific Widget metadata -The figure below depicts the structure followed by `widget` elements (and -therefore, the structure followed by widget descriptions): +The figure below depicts the structure followed by `widget` elements (and therefore, the structure followed by widget +descriptions): ![](../images/mac_description_widget_element.png) -
widget structure
+
widget structure
### The `contents` element -Widget descriptions must link to the actual source code of the widget. -This is done through the `contents` element. +Widget descriptions must link to the actual source code of the widget. This is done through the `contents` element. ![](../images/mac_description_content_element.png) +
The `content` element binds the description with the actual widget source code
The `contents` element supports the following attributes: - `src`: absolute or description-file-relative URL of widget code. -- `contenttype`: linked resource content type: suggested values are: - `text/html` and `application/xml+xhtml`. This is an optional attribute, - with `text/html` by default. All implementations of the Application - Mashup GE must support HTML files (`text/html`), other options (like - SVG or Flash are optional). -- `charset`: Charset used by the source file. This is an optional - attribute, with `utf-8` by default. -- `cacheable`: sets if the linked code can be cached by the - platform: possible values are `true` and `false`. This is an - optional attribute, `true` by default. -- `useplatformstyle`: Use platform style to display HTML elements. - Optional attribute, `false` by default. - -In addition to these attributes, the `contents` element allows to -provide a list of extra source files (through the `altcontents` -subelement) that will be use instead of the one provided in the main -`contents` element if the conditions are met (controlled by the `scope` -attribute). - +- `contenttype`: linked resource content type: suggested values are: `text/html` and `application/xml+xhtml`. This is + an optional attribute, with `text/html` by default. All implementations of the Application Mashup GE must support + HTML files (`text/html`), other options (like SVG or Flash are optional). +- `charset`: Charset used by the source file. This is an optional attribute, with `utf-8` by default. +- `cacheable`: sets if the linked code can be cached by the platform: possible values are `true` and `false`. This is + an optional attribute, `true` by default. +- `useplatformstyle`: Use platform style to display HTML elements. Optional attribute, `false` by default. + +In addition to these attributes, the `contents` element allows to provide a list of extra source files (through the +`altcontents` subelement) that will be use instead of the one provided in the main `contents` element if the conditions +are met (controlled by the `scope` attribute). ### The `rendering` element -The `rendering` element specifies the default width and height of the -widget once it is deployed in the user workspace. +The `rendering` element specifies the default width and height of the widget once it is deployed in the user workspace. ![](../images/mac_description_content_element.png) +
The `rendering` element
The `contents` element supports the following attributes: -- `width`: initial width of the widget as layout columns. From Wirecloud - v0.8.0 you can use also pixel units (e.g. `200px`) and percentage units - (e.g. `30%`). It's recommended to use pixel or percentage units if you don't - need to support previous versions of WireCloud. -- `height`: initial height of the widget as layout rows. From Wirecloud - v0.8.0 you can use also pixel units (e.g. `200px`) and percentage units - (e.g. `30%`). It's recommended to use pixel or percentage units if you don't - need to support previous versions of WireCloud. - +- `width`: initial width of the widget as layout columns. From Wirecloud v0.8.0 you can use also pixel units (e.g. + `200px`) and percentage units (e.g. `30%`). It's recommended to use pixel or percentage units if you don't need to + support previous versions of WireCloud. +- `height`: initial height of the widget as layout rows. From Wirecloud v0.8.0 you can use also pixel units (e.g. + `200px`) and percentage units (e.g. `30%`). It's recommended to use pixel or percentage units if you don't need to + support previous versions of WireCloud. ## Specific Operator metadata -The figure below depicts the structure followed by `operator` elements (and -therefore, the structure followed by operator descriptions): +The figure below depicts the structure followed by `operator` elements (and therefore, the structure followed by +operator descriptions): ![](../images/mac_description_operator_element.png) -
The `operator` element
+
The `operator` element
### The `scripts` element -While in widgets define it code entry point, in general, through an HTML -file, operators, as they do not provide an user interface, need to -declare directly the list of javascript files to use. This script list -is declared using the `scripts` element that is composed of one or more -`script` sub-elements. `script` elements supports the following +While in widgets define it code entry point, in general, through an HTML file, operators, as they do not provide an user +interface, need to declare directly the list of javascript files to use. This script list is declared using the +`scripts` element that is composed of one or more `script` sub-elements. `script` elements supports the following attributes: - `src`: description-file-relative URL of the JavaScript file. - ## Specific Mashup metadata -The figure below depicts the structure followed by `mashup` elements (and -therefore, the structure followed by mashup descriptions): +The figure below depicts the structure followed by `mashup` elements (and therefore, the structure followed by mashup +descriptions): ![](../images/mac_description_mashup_element.png) -
The `mashup` element
+
The `mashup` element
### The `structure` element -The `structure` element is in charge of describing the structure of the -mashup. The figure below depicts what it looks like: +The `structure` element is in charge of describing the structure of the mashup. The figure below depicts what it looks +like: ![](../images/mac_description_structure_element.png) -
The `structure` element
-The `preferencevalue` element allows the modification of the initial -values of the preferences of the final workspace. +
The `structure` element
-The `tab` element is used for describing each of the tab that build up -the mashup. So this is the key element for describing the visual part of -a mashup. +The `preferencevalue` element allows the modification of the initial values of the preferences of the final workspace. -The `wiring` element is used for describing the wiring/piping -configuration of the mashup. This element also is used for describing -the operators used in the mashup. Note that this element has the same -name to the `wiring` element used on the root of the description, but -this element is different in structure. +The `tab` element is used for describing each of the tab that build up the mashup. So this is the key element for +describing the visual part of a mashup. +The `wiring` element is used for describing the wiring/piping configuration of the mashup. This element also is used for +describing the operators used in the mashup. Note that this element has the same name to the `wiring` element used on +the root of the description, but this element is different in structure. ### The `tab` element ![](../images/mac_description_tab_element.png) +
The `tab` element
-The `structure` element should contain at least one `tab` element -that represents tabs in Application Mashup GE dashboard. It has the -following attributes +The `structure` element should contain at least one `tab` element that represents tabs in Application Mashup GE +dashboard. It has the following attributes - `name`: the name of the tab -- `id`: the identification of the tab; this id is internal to - the description. +- `id`: the identification of the tab; this id is internal to the description. -The `tab` element may contain any number of `resource` elements which represent -widget instances used in the mashup. It has the following attributes: +The `tab` element may contain any number of `resource` elements which represent widget instances used in the mashup. It +has the following attributes: - `vendor`: the widget distributor - `name`: name of the widget - `version`: version of the widget - `title`: name to be displayed in the dashboard. -- `readonly`: indicates if the widget can be remove from - the dashboard. -- `id`: the widget identification; this id is internal to the - mashup description. +- `readonly`: indicates if the widget can be remove from the dashboard. +- `id`: the widget identification; this id is internal to the mashup description. -The `preferencevalues` and the `variablevalues` elements allows the modification -of the initial values and the behaviour of the preferences an persistent -variables respectively. The parametrisation of each preference/persistent -variable is controlled by one of those elements and their attributes: +The `preferencevalues` and the `variablevalues` elements allows the modification of the initial values and the behaviour +of the preferences an persistent variables respectively. The parametrisation of each preference/persistent variable is +controlled by one of those elements and their attributes: - `name`: name of the preference/persisten variable to parameterise. -- `value`: initial value for the preference/persistent variable. If - not provided, the initial value of the preference (obtained from the - widget description) will be used. -- `readonly`: indicates if the preference/persistent variable can - be modified. -- `hidden`: indicates if the user will be able to see the value for - this preference/persistent variable on the user interface of the - Application Mashup GE. - -The `position` element describes the widget position into the -dashboard. It has the following attributes: +- `value`: initial value for the preference/persistent variable. If not provided, the initial value of the preference + (obtained from the widget description) will be used. +- `readonly`: indicates if the preference/persistent variable can be modified. +- `hidden`: indicates if the user will be able to see the value for this preference/persistent variable on the user + interface of the Application Mashup GE. + +The `position` element describes the widget position into the dashboard. It has the following attributes: - `x`: the widget's X coordinate. - `y`: the widget's Y coordinate. - `z`: the widget's Z coordinate. -The `rendering` element describes some characteristics of the -widget representation. It has the following attributes: +The `rendering` element describes some characteristics of the widget representation. It has the following attributes: - `width`: widget width in the dashboard. -- `minimized`: Boolean attribute that defines whether the widget is - minimized in the dashboard +- `minimized`: Boolean attribute that defines whether the widget is minimized in the dashboard - `layout`: widget layout in the dashboard - `height`: widget height in the dashboard -- `fulldragboard`: Boolean attribute that describes whether the - widget is using all the dashboard. - +- `fulldragboard`: Boolean attribute that describes whether the widget is using all the dashboard. ##### The Mashup's `wiring` structure element -This element describes how widgets and operators in the mashup are -connected using their output and input endpoints. +This element describes how widgets and operators in the mashup are connected using their output and input endpoints. ![](../images/mac_description_mashup_wiring_element.png) +
The mashup `wiring` element
-The `wiring` element may contain any number of `operator` elements. An -`operator` element defines an operator that is used in the wiring. It has the -following attributes: +The `wiring` element may contain any number of `operator` elements. An `operator` element defines an operator that is +used in the wiring. It has the following attributes: -- `id`: identification of the operator; this id is internal to the - mashup description. +- `id`: identification of the operator; this id is internal to the mashup description. - `vendor`: the distributor of the operator. - `name`: operator name. - `version`: version of the operator. -Fields `vendor`, `name` and `version` follows the same pattern defined in the -[introduction](#introduction). - -The `wiring` element may contain any number of `connection` -elements. These elements describe which output endpoints are connected -with which input endpoints. The `connection` elements are composed -of a `source` element and a `target` element. - -The `source` element defines the output endpoint of the -connection. It has the following attributes. - -- `type`: type of the element that has the output endpoint; this - attribute could have the values `widget` or `operator`. -- `id`: id of the element that has the output endpoint; this id is - the same as the id defined in the `resource` element if the - element is a widget, whereas this id is the same as the id defined - in the `operator` element if the element is an operator. -- `endpoint`: the name of the output endpoint. This name is the same - as the defined in the `outputenpoint` element. - -The `target` element defines the input endpoint of the connection. -It has the following attributes: - -- `type`: type of element that has the input endpoint; the possible - values of this attribute are `widget` or `operator`. -- `id`: id of the element that has the input endpoint; this id is - the same as the id defined in the `resource` element if the - element is a widget, whereas this id is the same as the id defined - in the `operator` element if the element is an operator. -- `endpoint`: the name of the input endpoint; this name is the same - as the defined in the `inputenpoint` element. +Fields `vendor`, `name` and `version` follows the same pattern defined in the [introduction](#introduction). + +The `wiring` element may contain any number of `connection` elements. These elements describe which output endpoints are +connected with which input endpoints. The `connection` elements are composed of a `source` element and a `target` +element. + +The `source` element defines the output endpoint of the connection. It has the following attributes. + +- `type`: type of the element that has the output endpoint; this attribute could have the values `widget` or + `operator`. +- `id`: id of the element that has the output endpoint; this id is the same as the id defined in the `resource` + element if the element is a widget, whereas this id is the same as the id defined in the `operator` element if the + element is an operator. +- `endpoint`: the name of the output endpoint. This name is the same as the defined in the `outputenpoint` element. + +The `target` element defines the input endpoint of the connection. It has the following attributes: + +- `type`: type of element that has the input endpoint; the possible values of this attribute are `widget` or + `operator`. +- `id`: id of the element that has the input endpoint; this id is the same as the id defined in the `resource` element + if the element is a widget, whereas this id is the same as the id defined in the `operator` element if the element + is an operator. +- `endpoint`: the name of the input endpoint; this name is the same as the defined in the `inputenpoint` element. diff --git a/docs/development/ngsi_api.md b/docs/development/ngsi_api.md index 414e34f77a..903fbe9981 100644 --- a/docs/development/ngsi_api.md +++ b/docs/development/ngsi_api.md @@ -1,69 +1,64 @@ -This document is the reference documentation of the NGSI API provided by -WireCloud. For being able to use this API you have to add a requirement on this -API thought the description file of the widget/operator. See the [Using Orion -Context Broker](3.2.1_Using Orion Context) tutorial for more detailed -documentation (and examples) on how to use this API. +This document is the reference documentation of the NGSI API provided by WireCloud. For being able to use this API you +have to add a requirement on this API thought the description file of the widget/operator. See the [Using Orion Context +Broker](3.2.1_Using Orion Context) tutorial for more detailed documentation (and examples) on how to use this API. ## Data types used by the library -- The **Entity** type is used to reference entities. This type is defined as an - object composed of the following fields: - - `id` is a string with the id of the entity. Some times you will be able to use - patterns in this field. - - `isPattern` is a boolean indicating whether the id field contains a - regular expression pattern. *(Optional field)* - - `type` is the type of the **Entity**. *(Optional field)* - -- The **Attribute** type is used to reference attributes. This type is defined - as an object composed of the following fields: - * `name` is the name of the attribute - * `type` is the type of the **Attribute**. *(Optional field)* - -- The **Duration** type is used to describe time intervals and defined as a - string following the format defined at - http://books.xmlschemata.org/relaxng/ch19-77073.html. - -- The **Condition** type is used to declare the condition that will trigger - notifications. This type is defined as an object composed of the following - fields: - - `type` is an string containing `ONTIMEINTERVAL` or `ONCHANGE` - - `values`: array of string. Depends on the value of the type field: - - `ONTIMEINTERVAL`: exactly one value SHALL be present and SHALL - represent the time interval between notifications - - `ONCHANGE`: this element SHALL contain the name(s) of the Context - Attributes to be monitored for changes - -- **MetadataValue** type is used to assign metadata to attributes. This type is - defined as an object composed of the following fields: - - `name` is the name of the attribute metadata - - `type` is the type of the attribute metadata - - `value` is the value to assign to the attribute metadata - -- The **AttributeValue** type is used to assign values to attributes. This type - is defined as an object composed of the following fields: - - `name` is the name of the attribute - - `type` is the type of the attribute. *(Optional field)* - - `contextValue` is the value to assign to the attribute - - `metadata` is the metadata associated with the attribute. This field is - defined as a **MetadataValue** array - -- The **AttributeUpdate** type is used to describe a context update. This type - is defined as an object composed of the following fields: - - `entity` is the entity affected by the update. This field is defined as - an **Entity** array - - `attributes` is the new values for the attributes of the entity. This - field is defined as an **AttributeValue** array - -- The **AttributeDeletion** type is used to describe the deletion of attributes - from an entity. This type is defined as an object composed of the following - fields: - - - `entity` is the entity affected by the update. This field is defined as - an **Entity** array - - `attributes` is the new values for the attributes of the entity. This - field is defined as an **AttributeValue** array. If you use `null` or an - empty array for this field, the entity will be entirely removed. +- The **Entity** type is used to reference entities. This type is defined as an object composed of the following + fields: + - `id` is a string with the id of the entity. Some times you will be able to use patterns in this field. + - `isPattern` is a boolean indicating whether the id field contains a regular expression pattern. _(Optional + field)_ + - `type` is the type of the **Entity**. _(Optional field)_ + +- The **Attribute** type is used to reference attributes. This type is defined as an object composed of the following + fields: + + - `name` is the name of the attribute + - `type` is the type of the **Attribute**. _(Optional field)_ + +- The **Duration** type is used to describe time intervals and defined as a string following the format defined at + http://books.xmlschemata.org/relaxng/ch19-77073.html. + +- The **Condition** type is used to declare the condition that will trigger notifications. This type is defined as an + object composed of the following fields: + + - `type` is an string containing `ONTIMEINTERVAL` or `ONCHANGE` + - `values`: array of string. Depends on the value of the type field: + - `ONTIMEINTERVAL`: exactly one value SHALL be present and SHALL represent the time interval between + notifications + - `ONCHANGE`: this element SHALL contain the name(s) of the Context Attributes to be monitored for changes + +- **MetadataValue** type is used to assign metadata to attributes. This type is defined as an object composed of the + following fields: + + - `name` is the name of the attribute metadata + - `type` is the type of the attribute metadata + - `value` is the value to assign to the attribute metadata + +- The **AttributeValue** type is used to assign values to attributes. This type is defined as an object composed of + the following fields: + + - `name` is the name of the attribute + - `type` is the type of the attribute. _(Optional field)_ + - `contextValue` is the value to assign to the attribute + - `metadata` is the metadata associated with the attribute. This field is defined as a **MetadataValue** array + +- The **AttributeUpdate** type is used to describe a context update. This type is defined as an object composed of the + following fields: + + - `entity` is the entity affected by the update. This field is defined as an **Entity** array - `attributes` is + the new values for the attributes of the entity. This field is defined as an **AttributeValue** array + +- The **AttributeDeletion** type is used to describe the deletion of attributes from an entity. This type is defined + as an object composed of the following fields: + + - `entity` is the entity affected by the update. This field is defined as + an **Entity** array + - `attributes` is the new values for the attributes of the entity. This + field is defined as an **AttributeValue** array. If you use `null` or an + empty array for this field, the entity will be entirely removed. ## NGSI.Connection @@ -73,21 +68,17 @@ A new `NGSI.Connection` can be instantiated using the following constructor: NGSI.Connection(url[, options]) ``` -- `url` (String): is the url of the Orion Pub/Sub Context Broker instance -- `options` (Object; default `null`): This parameter may be `null` if no extra - option is needed. Current supported options are: - - `ngsi_proxy_url` (String; default `null`): URL of the NGSI proxy used for - subscriptions - - `request_headers` (Object; default `null`): A set of key-value pairs, with - properties representing header names. These extra headers will be use when - making request to the context broker - - `use_user_fiware_token` (Boolean; default: `false`): Use current user - authentication token retrieved from the IdM system +- `url` (String): is the url of the Orion Pub/Sub Context Broker instance +- `options` (Object; default `null`): This parameter may be `null` if no extra option is needed. Current supported + options are: - `ngsi_proxy_url` (String; default `null`): URL of the NGSI proxy used for subscriptions - + `request_headers` (Object; default `null`): A set of key-value pairs, with properties representing header names. + These extra headers will be use when making request to the context broker - `use_user_fiware_token` (Boolean; + default: `false`): Use current user authentication token retrieved from the IdM system **Usage example:** -This code creates a connection using the credentials of the user logged in -WireCloud and supporting subcriptions through the FIWARE Lab's NGSI proxy: +This code creates a connection using the credentials of the user logged in WireCloud and supporting subcriptions through +the FIWARE Lab's NGSI proxy: ```javascript var connection = new NGSI.Connection("http://orion.lab.fiware.org:1026/", { @@ -96,8 +87,8 @@ var connection = new NGSI.Connection("http://orion.lab.fiware.org:1026/", { }); ``` -This code creates a connection using the `FIWARE-Service` header to make use of -the multitenancy support provided by the context broker: +This code creates a connection using the `FIWARE-Service` header to make use of the multitenancy support provided by the +context broker: ```javascript var connection = new NGSI.Connection("http://:1026/", { @@ -107,16 +98,13 @@ var connection = new NGSI.Connection("http://:1026/", { }); ``` - ### Callback options All the method of `NGSI.Connection` support at least the following callbacks: -- `onSuccess` is called when the request finishes successfully -- `onFailure` is called when the request finishes with errors -- `onComplete` is called when the request finishes regardless of whether the - request is successful or not - +- `onSuccess` is called when the request finishes successfully +- `onFailure` is called when the request finishes with errors +- `onComplete` is called when the request finishes regardless of whether the request is successful or not ### `createRegistration` @@ -126,75 +114,63 @@ Register context information (entities and attributes) in the NGSI server createRegistration(entities, attributes, duration, providingApplication[, options]) ``` -- `entities` is the list of **Entities** that are going to be registered -- `attributes` is a list of the **Attributes** that are going to be assigned to - the previous list of entities -- `duration` is the **Duration** for this registration -- `providingApplication` is the URI of the application to which this - registration belongs to +- `entities` is the list of **Entities** that are going to be registered +- `attributes` is a list of the **Attributes** that are going to be assigned to the previous list of entities +- `duration` is the **Duration** for this registration +- `providingApplication` is the URI of the application to which this registration belongs to The `onSuccess` callback will receive an object with the following fields: -- `registrationId` is the final assigned id -- `duration` is the final assigned duration for this registration +- `registrationId` is the final assigned id +- `duration` is the final assigned duration for this registration **Usage example:** ```javascript -connection.createRegistration([ - {type: 'Technician', id: 'entity1'} - ], [ - {name: 'attr1', type: 'string'}, - {name: 'attr2'}, - {name: 'attr3', type: 'number'} - ], - 'PT24H', - 'http://app.example.com/', +connection.createRegistration( + [{ type: "Technician", id: "entity1" }], + [{ name: "attr1", type: "string" }, { name: "attr2" }, { name: "attr3", type: "number" }], + "PT24H", + "http://app.example.com/", { - onSuccess: function (data) { + onSuccess: function(data) { //data.subscriptionId } } -) +); ``` - ### `updateRegistration` Updates a particular registration. ```javascript -updateRegistration(entities, attributes, duration, providingApplication, options) +updateRegistration(entities, attributes, duration, providingApplication, options); ``` -- `regId` is the id of the registration to update -- `entities` is the list of **Entities** that its going to replace the previous established one -- `attributes` is a list of the **Attributes** that are going to be assigned to the provided list of entities -- `duration` is the new **Duration** for the registration identified by `regId` -- `providingApplication` is the new value for the providingApplication property of the registration +- `regId` is the id of the registration to update +- `entities` is the list of **Entities** that its going to replace the previous established one +- `attributes` is a list of the **Attributes** that are going to be assigned to the provided list of entities +- `duration` is the new **Duration** for the registration identified by `regId` +- `providingApplication` is the new value for the providingApplication property of the registration The `onSuccess` callback will receive an object with the following fields: -- `registrationId` is the id of the registration -- `duration` is the final assigned duration for this registration +- `registrationId` is the id of the registration +- `duration` is the final assigned duration for this registration **Example usage:** ```javascript -connection.updateRegistration("167", - [ - {type: 'Technician', id: 'entity1'} - ], - [ - {name: 'attr1', type: 'string'}, - {name: 'attr2'} - ], - 'PT24H', - 'http://app.example.com/' +connection.updateRegistration( + "167", + [{ type: "Technician", id: "entity1" }], + [{ name: "attr1", type: "string" }, { name: "attr2" }], + "PT24H", + "http://app.example.com/" ); ``` - ### `cancelRegistration` Cancels or deletes a particular registration. @@ -203,19 +179,18 @@ Cancels or deletes a particular registration. cancelRegistration(regId[, options]) ``` -- `regId` is the id of the registration to cancel +- `regId` is the id of the registration to cancel **Example usage:** ```javascript connection.cancelRegistration("167", { - onSuccess: function () { + onSuccess: function() { // Registration cancelled successfully } }); ``` - ### `discoverAvailability` Discover context information registrations in the NGSI server. @@ -224,12 +199,12 @@ Discover context information registrations in the NGSI server. discoverAvailability(entities, attributeNames[, options]) ``` -- `entities` is the list of **Entities** that are going to be queried -- `attributeNames` is the list of attribute names that are going to be queried. - This parameter is optional and thus `null` is a valid value +- `entities` is the list of **Entities** that are going to be queried +- `attributeNames` is the list of attribute names that are going to be queried. This parameter is optional and thus + `null` is a valid value -The `onSuccess` callback will receive an array with the registrations meeting -the query requirements as the first parameter. +The `onSuccess` callback will receive an array with the registrations meeting the query requirements as the first +parameter. **Example usage:** @@ -247,33 +222,28 @@ connection.discoverAvailability([ ); ``` - ### `query` -Query for context information. That information is returned using pagination -(see supported options), so its very recommended the use of the `details` -option. This option is currently disabled by default, but expect it to be -enabled by default in next versions of WireCloud. +Query for context information. That information is returned using pagination (see supported options), so its very +recommended the use of the `details` option. This option is currently disabled by default, but expect it to be enabled +by default in next versions of WireCloud. ```javascript query(entities, attributeNames[, options]) ``` -- `entities` is the list of **Entities** to query -- `attributeNames` is the list of attribute names to query. Use `null` for - retrieving all the attributes +- `entities` is the list of **Entities** to query +- `attributeNames` is the list of attribute names to query. Use `null` for retrieving all the attributes The `query` method supports other extra options: -- `flat` (Boolean; default: `false`): This options is used for simplifying the - data structure used for representing the returned data -- `limit` (Number; default: 20): This option allow you to specify the maximum - number of entities you want to receive from the server -- `offset` (Number; default: 0): Allows you to skip a given number of elements - at the beginning -- `details` (Boolean; default: `false`): Makes the server return more detailed - information about the request (currently those details are related to the - pagination) +- `flat` (Boolean; default: `false`): This options is used for simplifying the data structure used for representing + the returned data +- `limit` (Number; default: 20): This option allow you to specify the maximum number of entities you want to receive + from the server +- `offset` (Number; default: 0): Allows you to skip a given number of elements at the beginning +- `details` (Boolean; default: `false`): Makes the server return more detailed information about the request + (currently those details are related to the pagination) **Example usage:** @@ -307,9 +277,7 @@ This is the value of the data parameter passed to the `onSuccess` callback when "name": "current_position", "type": "coordinates", "contextValue": "43.47557, -3.8048315", - "metadata": [ - {"name": "location", "type": "string", "value": "WGS84"} - ] + "metadata": [{ "name": "location", "type": "string", "value": "WGS84" }] } ] }, @@ -323,9 +291,7 @@ This is the value of the data parameter passed to the `onSuccess` callback when "name": "current_position", "type": "coordinates", "contextValue": "43.47258, -3.8026643", - "metadata": [ - {"name": "location", "type": "string", "value": "WGS84"} - ] + "metadata": [{ "name": "location", "type": "string", "value": "WGS84" }] } ] }, @@ -339,9 +305,7 @@ This is the value of the data parameter passed to the `onSuccess` callback when "name": "current_position", "type": "coordinates", "contextValue": "43.47866, -3.7991238", - "metadata": [ - {"name": "location", "type": "string", "value": "WGS84"} - ] + "metadata": [{ "name": "location", "type": "string", "value": "WGS84" }] } ] }, @@ -355,9 +319,7 @@ This is the value of the data parameter passed to the `onSuccess` callback when "name": "current_position", "type": "coordinates", "contextValue": "43.471214, -3.7994885", - "metadata": [ - {"name": "location", "type": "string", "value": "WGS84"} - ] + "metadata": [{ "name": "location", "type": "string", "value": "WGS84" }] } ] } @@ -391,7 +353,6 @@ This is the value of the data parameter when `flat` is `true`: } ``` - ### `updateAttributes` Update context information. @@ -400,93 +361,89 @@ Update context information. updateAttributes(update[, options]) ``` -* `update` a list of **AttributeUpdates** +- `update` a list of **AttributeUpdates** -The `onSuccess` callback will receive an array with the response and a array -with the not accepted updates as the first and the second parameter -respectively. +The `onSuccess` callback will receive an array with the response and a array with the not accepted updates as the first +and the second parameter respectively. **Example usage:** ```javascript -connection.updateAttributes([ +connection.updateAttributes( + [ { - 'entity': {type: 'Technician', id: 'entity1'}, - 'attributes': [ - {name: 'mobile_phone', type: 'string', contextValue: '0034223456789'}, - {name: 'attr2', contextValue: 'value'}, - {name: 'attr3', contextValue: 5} + entity: { type: "Technician", id: "entity1" }, + attributes: [ + { name: "mobile_phone", type: "string", contextValue: "0034223456789" }, + { name: "attr2", contextValue: "value" }, + { name: "attr3", contextValue: 5 } ] } - ], { - onSuccess: function (data) { - } + ], + { + onSuccess: function(data) {} } ); ``` - ### `addAttributes` -Add/update entity attributes. This operation will create the attribute on those entities where they doesn't exist. In addition to this, this operation will also create entities if they doesn't exist. +Add/update entity attributes. This operation will create the attribute on those entities where they doesn't exist. In +addition to this, this operation will also create entities if they doesn't exist. ```javascript addAttributes(toAdd[, options]) ``` -* `toAdd` a list of **AttributeUpdates** +- `toAdd` a list of **AttributeUpdates** -The `onSuccess` callback will receive an array with the response and a array -with the not accepted updates as the first and the second parameter -respectively. +The `onSuccess` callback will receive an array with the response and a array with the not accepted updates as the first +and the second parameter respectively. **Example usage:** ```javascript -connection.addAttributes([ +connection.addAttributes( + [ { - 'entity': {type: 'Technician', id: 'entity1'}, - 'attributes': [ - {'name': 'new_attribute', 'type': 'string', 'contextValue': 'value'} - ] - } - ], { - onSuccess: function (data, partial_errors) { + entity: { type: "Technician", id: "entity1" }, + attributes: [{ name: "new_attribute", type: "string", contextValue: "value" }] } + ], + { + onSuccess: function(data, partial_errors) {} } ); ``` - ### `deleteAttributes` -Delete attributes form entities. This method can be use also for removing -entities from the context broker. +Delete attributes form entities. This method can be use also for removing entities from the context broker. ```javascript deleteAttributes(toDelete[, options]) ``` -* `toDelete` a list of **AttributeDeletion** +- `toDelete` a list of **AttributeDeletion** -The `onSuccess` callback will receive an array with the response and a array -with the not accepted updates as the first and the second parameter -respectively. +The `onSuccess` callback will receive an array with the response and a array with the not accepted updates as the first +and the second parameter respectively. **Example usage (removing the `position` attribute from the `Madrid` entity):** ```javascript -connection.deleteAttributes([ +connection.deleteAttributes( + [ { - 'entity': {type: 'City', id: 'Madrid'}, - 'attributes': { - 'name': 'position', - 'type': 'coords' + entity: { type: "City", id: "Madrid" }, + attributes: { + name: "position", + type: "coords" } } - ], { - onSuccess: function (data, partial_errors) { - } + ], + { + onSuccess: function(data, partial_errors) {} } ); ``` @@ -494,66 +451,60 @@ connection.deleteAttributes([ **Example usage (removing `Madrid` from the context broker):** ```javascript -connection.deleteAttributes([ +connection.deleteAttributes( + [ { - 'entity': {type: 'City', id: 'Madrid'} - } - ], { - onSuccess: function (data, partial_errors) { + entity: { type: "City", id: "Madrid" } } + ], + { + onSuccess: function(data, partial_errors) {} } ); ``` - ### `createSubscription` Subscribe to changes in the context information. ```javascript -createSubscription(entities, attributeNames, duration, throttling, conditions, options) -``` - -- `entities` is the list of **Entities** to query in this subscription -- `attributeNames` is the list of attribute names to query in this subscription. - Use `null` for retrieving all the attributes -- `duration` is the **Duration** of this subscription -- `throttling` is the proposed minimum interval between notifications. This - value must be provided using the **Duration** type. You can also pass `null` - if you don't want to provide a throttling value -- `conditions` is a list of **Conditions** that will trigger queries using the - provided information and their subsequent notifications to the `onNotify` - callback - -This method, supports a new type of callback: `onNotify`. This callback is -required and can be either an URL or a function. In the later case, the NGSI -Connection must be created using a NGSI proxy and will be called every time a +createSubscription(entities, attributeNames, duration, throttling, conditions, options); +``` + +- `entities` is the list of **Entities** to query in this subscription +- `attributeNames` is the list of attribute names to query in this subscription. Use `null` for retrieving all the + attributes +- `duration` is the **Duration** of this subscription +- `throttling` is the proposed minimum interval between notifications. This value must be provided using the + **Duration** type. You can also pass `null` if you don't want to provide a throttling value +- `conditions` is a list of **Conditions** that will trigger queries using the provided information and their + subsequent notifications to the `onNotify` callback + +This method, supports a new type of callback: `onNotify`. This callback is required and can be either an URL or a +function. In the later case, the NGSI Connection must be created using a NGSI proxy and will be called every time a notification comes from the NGSI server. -The first parameter of a `onNotify` callback function will be an object with the -response data. +The first parameter of a `onNotify` callback function will be an object with the response data. In addition to this, the `createSubscription` method supports an extra option: -* `flat` (Boolean; default: `false`): This options is used for simplifying the - data structure used for representing the returned data +- `flat` (Boolean; default: `false`): This options is used for simplifying the data structure used for representing + the returned data **Example usage:** ```javascript -connection.createSubscription([ - {type: 'Technician', id: 'tech*', isPattern: true}, - {type: 'Van', id: 'van1'}, - ], +connection.createSubscription( + [{ type: "Technician", id: "tech*", isPattern: true }, { type: "Van", id: "van1" }], null, - 'PT24H', + "PT24H", null, - [{type: 'ONCHANGE', condValues: ['position']}], + [{ type: "ONCHANGE", condValues: ["position"] }], { - onNotify: function (data) { + onNotify: function(data) { // called when a notification arrives }, - onSuccess: function (data) { + onSuccess: function(data) { // subscription created successfully // data.subscriptionId contains the id associated with the created subscription } @@ -569,33 +520,25 @@ Update context subscription. updateSubscription(subId, duration, throttling, conditions[, options]) ``` -- `subId` is the id of the context subscription to cancel -- `duration` is the **Duration** of this subscription -- `throttling` is the proposed minimum interval between notifications. This - value must be provided using the **Duration** type. This parameter is - optional accepting `null`, in that case the throttling configuration of the - subscription will not be updated -- `conditions` is a list of **Conditions** that will trigger queries using the - provided information and their subsequent notifications to the `onNotify` - callback. This parameter is optional accepting `null`, in that case the - conditions configuration of the subscription will not be updated +- `subId` is the id of the context subscription to cancel +- `duration` is the **Duration** of this subscription +- `throttling` is the proposed minimum interval between notifications. This value must be provided using the + **Duration** type. This parameter is optional accepting `null`, in that case the throttling configuration of the + subscription will not be updated +- `conditions` is a list of **Conditions** that will trigger queries using the provided information and their + subsequent notifications to the `onNotify` callback. This parameter is optional accepting `null`, in that case the + conditions configuration of the subscription will not be updated **Example usage:** ```javascript -connection.updateSubscription('sub1', - 'PT20H', - null, - null, - { - onSuccess: function (response_data) { - // subscription updated successfully - } +connection.updateSubscription("sub1", "PT20H", null, null, { + onSuccess: function(response_data) { + // subscription updated successfully } -); +}); ``` - ### `cancelSubscription` Cancels or deletes context subscription. @@ -604,48 +547,42 @@ Cancels or deletes context subscription. cancelSubscription(subId[, options]) ``` -- `subId` is the id of the context subscription to cancel +- `subId` is the id of the context subscription to cancel **Example usage:** ```javascript -connection.cancelSubscription('sub1', - { - onSuccess: function (data) { - // Subscription canceled successfully - // data.subscriptionId should be equal to 'sub1' - } +connection.cancelSubscription("sub1", { + onSuccess: function(data) { + // Subscription canceled successfully + // data.subscriptionId should be equal to 'sub1' } -); +}); ``` - ### `getAvailableTypes` -Get info about about the used context types. This information is currently -composed of the type name and the attributes used with that type (the attribute -set returned by this operation is the union of the attributes used in each of the +Get info about about the used context types. This information is currently composed of the type name and the attributes +used with that type (the attribute set returned by this operation is the union of the attributes used in each of the entities belonging to that type). ```javascript -getAvailableTypes(options) +getAvailableTypes(options); ``` The `getAvailableTypes` method supports an extra option: -- `limit` (Number; default: 20): This option allow you to specify the maximum - number of entities you want to receive from the server -- `offset` (Number; default: 0): Allows you to skip a given number of elements - at the beginning -- `details` (Boolean; default: `true`): Makes the server return more detailed - information about the request (currently those details are related to the - pagination) +- `limit` (Number; default: 20): This option allow you to specify the maximum number of entities you want to receive + from the server +- `offset` (Number; default: 0): Allows you to skip a given number of elements at the beginning +- `details` (Boolean; default: `true`): Makes the server return more detailed information about the request (currently + those details are related to the pagination) **Example usage:** ```javascript connection.getAvailableTypes({ - onSuccess: function (types, details) { + onSuccess: function(types, details) { // The types parameter contains the information // about the available types, see next slide for // more info @@ -658,41 +595,31 @@ connection.getAvailableTypes({ ```json [ { - "attributes": [ - "speed", - "fuel", - "temperature" - ], + "attributes": ["speed", "fuel", "temperature"], "name": "Car" }, { - "attributes": [ - "pressure", - "hummidity", - "temperature" - ], + "attributes": ["pressure", "hummidity", "temperature"], "name": "Room" } ] ``` - ### `getTypeInfo` -Get info about about a concrete entity type. This information is currently -composed of the type name and the attributes used with that type (the attribute -set returned by this operation is the union of the attributes used in each of the +Get info about about a concrete entity type. This information is currently composed of the type name and the attributes +used with that type (the attribute set returned by this operation is the union of the attributes used in each of the entities belonging to that type). ```javascript -getTypeInfo(type, options) +getTypeInfo(type, options); ``` **Example usage:** ```javascript connection.getTypeInfo("Room", { - onSuccess: function (type_info) { + onSuccess: function(type_info) { // The type_info parameter contains the information // about the Room type, see next slide for more info } @@ -703,11 +630,7 @@ connection.getTypeInfo("Room", { ```json { - "attributes": [ - "hummidity", - "pressure", - "temperature" - ], + "attributes": ["hummidity", "pressure", "temperature"], "name": "Room" } ``` diff --git a/docs/development/object_storage_api.md b/docs/development/object_storage_api.md index 2d15a735d7..51a76f9bc1 100644 --- a/docs/development/object_storage_api.md +++ b/docs/development/object_storage_api.md @@ -1,15 +1,11 @@ -Object Storage offers persistent storage for digital objects that can be files, -databases or other datasets which need to be archived. Objects are stored in -named locations known as containers. Containers can be nested thus objects can -be stored hierarchically. - -This section provides the reference documentation of the ObjectStorage API -provided by WireCloud that can be uses in your widgets or operators. For being -able to use this API you have to add a requirement on this API thought the -description file of the widget/operator. See the [Using Object -Storage](3.2.2_Using Object Storage) tutorial for more detailed documentation -(and examples) on how to use this API. +Object Storage offers persistent storage for digital objects that can be files, databases or other datasets which need +to be archived. Objects are stored in named locations known as containers. Containers can be nested thus objects can be +stored hierarchically. +This section provides the reference documentation of the ObjectStorage API provided by WireCloud that can be uses in +your widgets or operators. For being able to use this API you have to add a requirement on this API thought the +description file of the widget/operator. See the [Using Object Storage](3.2.2_Using Object Storage) tutorial for more +detailed documentation (and examples) on how to use this API. ## KeystoneAPI @@ -19,51 +15,43 @@ A new **KeystoneAPI** can be instantiated using the following constructor: KeystoneAPI(url[, options]) ``` -- `url` is the url of the Keystone server -- `options`: - - `token` (String): is the token to used for authenticating request to the - Keystone server. *(Optional)* - - `use_user_fiware_token` (Boolean): make **KeystoneAPI** to use the token - obtained by WireCloud for the current user from the FIWARE's IdM server. - Takes precedence over the `token` option. *(Optional)* - -The `token` and `use_user_fiware_token` options are optional. When passed to the -`KeystoneAPI` constructor, these values are stored internally and used as the -default value in the invocation of its methods. In any case, these options can -also be passed to the `KeystoneAPI` methods for not using the default values. +- `url` is the url of the Keystone server +- `options`: + - `token` (String): is the token to used for authenticating request to the Keystone server. _(Optional)_ + - `use_user_fiware_token` (Boolean): make **KeystoneAPI** to use the token obtained by WireCloud for the current + user from the FIWARE's IdM server. Takes precedence over the `token` option. _(Optional)_ +The `token` and `use_user_fiware_token` options are optional. When passed to the `KeystoneAPI` constructor, these values +are stored internally and used as the default value in the invocation of its methods. In any case, these options can +also be passed to the `KeystoneAPI` methods for not using the default values. ### getTenants List all of the tenants in the Keystone server available for the authenticated user. ```javascript -getTenants([options]) +getTenants([options]); ``` The `onSuccess` callback will receive the list of tenants as the first argument. - ### getAuthToken Gets an authentication token that permits access to the Object Storage API. ```javascript -getAuthToken([options]) +getAuthToken([options]); ``` Extra options: -- `tenantName` (String): The name of the tenant to be associated to the - generated token. Both the tenantId and tenantName attributes are optional, but - should not be specified together -- `tenantId` (String): The id of the tenant to be associated to the generated - token. Both the `tenantId` and `tenantName` attributes are optional, but - should not be specified together +- `tenantName` (String): The name of the tenant to be associated to the generated token. Both the tenantId and + tenantName attributes are optional, but should not be specified together +- `tenantId` (String): The id of the tenant to be associated to the generated token. Both the `tenantId` and + `tenantName` attributes are optional, but should not be specified together The `onSuccess` callback will receive auth token info as the first argument. - ## ObjectStorageAPI A new `ObjectStorageAPI` can be instantiated using the following constructor: @@ -72,23 +60,20 @@ A new `ObjectStorageAPI` can be instantiated using the following constructor: ObjectStorageAPI(url[, options]) ``` -- `url` is the url of the Object Storage server -- `options`: - - `token` (String): is the token to use by default for authenticating - requests to the Object Storage server +- `url` is the url of the Object Storage server +- `options`: + - `token` (String): is the token to use by default for authenticating requests to the Object Storage server All the method of `ObjectStorageAPI` support at least the following option: -- `token` (String): is the token to used for authenticating the request +- `token` (String): is the token to used for authenticating the request and the following callbacks: -- `onSuccess` is called when the request finishes successfully. The parameters - passed to this callback depends on the invoked method. -- `onFailure` is called when the request finish with errors -- `onComplete` is called when the request finish regardless of whether the - request is successful or not - +- `onSuccess` is called when the request finishes successfully. The parameters passed to this callback depends on the + invoked method. +- `onFailure` is called when the request finish with errors +- `onComplete` is called when the request finish regardless of whether the request is successful or not ### createContainer @@ -98,8 +83,7 @@ Creates a container in which other containers and objects can be stored. createContainer(container[, options]) ``` -- `container` is the name of the container to create - +- `container` is the name of the container to create ### listContainer @@ -109,8 +93,7 @@ Returns a list of the contents of a container. listContainer(container[, options]) ``` -- `container` is the name of the container to list - +- `container` is the name of the container to list ### deleteContainer @@ -120,8 +103,7 @@ Deletes a specified container from the storage system. deleteContainer(container[, options]) ``` -- `container` is the name of the container to delete - +- `container` is the name of the container to delete ### getFile @@ -131,18 +113,16 @@ Retrieves a specified object from the storage system. getFile(container, file_name[, options]) ``` -* `container` is the name of the container where the file is -* `file_name` is the name of the file to download +- `container` is the name of the container where the file is +- `file_name` is the name of the file to download Extra options: -- `response_type` (String, default: "blob"): Valid values are all the supported - by the `responseType` option (see the [request option section][request_options] - for more details), except "" +- `response_type` (String, default: "blob"): Valid values are all the supported by the `responseType` option (see the + [request option section][request_options] for more details), except "" [request_options]: ../widgetapi/widgetapi.md#request-options-general-options - ### uploadFile Stores a binary object in the specified location. @@ -151,21 +131,18 @@ Stores a binary object in the specified location. uploadFile(container, file[, options]) ``` -- `container` is the name of the container where the file is going to be uploaded -- `file` is the content to be uploaded. Must be an instance of - [`Blob`][JavaScript_Blob] or [`File`][JavaScript_File]. +- `container` is the name of the container where the file is going to be uploaded +- `file` is the content to be uploaded. Must be an instance of [`Blob`][javascript_blob] or [`File`][javascript_file]. Extra options: -- `file_name`: name to use for uploading the file. This option is required when - passing a `Blob` as the `file` argument. This option is not required when - passing a `File` instance as the name is obtained from its `name` attribute. - Anyway, the name passed with this options has precedence over the `name` - attribute of the `File` instances. - -[JavaScript_Blob]: https://developer.mozilla.org/en/docs/Web/API/Blob -[JavaScript_File]: https://developer.mozilla.org/en/docs/Web/API/File +- `file_name`: name to use for uploading the file. This option is required when passing a `Blob` as the `file` + argument. This option is not required when passing a `File` instance as the name is obtained from its `name` + attribute. Anyway, the name passed with this options has precedence over the `name` attribute of the `File` + instances. +[javascript_blob]: https://developer.mozilla.org/en/docs/Web/API/Blob +[javascript_file]: https://developer.mozilla.org/en/docs/Web/API/File ### deleteFile @@ -175,5 +152,5 @@ Deletes a specified object from the storage system. deleteFile(container, file_name[, options]) ``` -* `container` is the name of the container where the file is going to be deleted -* `file_name` is the name of the file to delete +- `container` is the name of the container where the file is going to be deleted +- `file_name` is the name of the file to delete diff --git a/docs/development/platform/testing.md b/docs/development/platform/testing.md index 192fd491de..c633f5f059 100644 --- a/docs/development/platform/testing.md +++ b/docs/development/platform/testing.md @@ -1,15 +1,15 @@ Before running any of the tests provided by WireCloud, you need to install some extra dependencies: -``` -$ pip install django-nose "mock>=1.0,<2.0" +```bash +pip install django-nose "mock>=1.0,<2.0" ``` ## Unit tests Server unit tests are executed: -``` +```bash python manage.py test -v 2 --noinput --nologcapture -a tags="wirecloud-noselenium" ``` @@ -22,8 +22,8 @@ configuration provided in this file when running the tests. There are also unit tests for the JavaScript code that is executed in the client side. You can tun those tests by executing the following command: -``` -$ grunt karma +```bash +grunt karma ``` > **Note**: JavaScript unit tests are work in progress, do not expect a great @@ -33,8 +33,8 @@ $ grunt karma The integration tests make use of selenium, you can also install it through pip: -``` -$ pip install selenium +```bash +pip install selenium ``` Once installed you, you will have to install the drivers for the browsers you @@ -87,7 +87,7 @@ WIRECLOUD_SELENIUM_TEST_BROWSERS = { Now you can pass the integration tests by running the following command: -``` +```bash python manage.py test -v 2 --noinput --nologcapture -a tags="wirecloud-selenium" ``` diff --git a/docs/development/platform/themes.md b/docs/development/platform/themes.md index 7d95e0658f..46c3926b93 100644 --- a/docs/development/platform/themes.md +++ b/docs/development/platform/themes.md @@ -13,7 +13,7 @@ original theme. However, to do so, you have to previously create a new folder with the following structure: -``` +```text mytheme +-- __init__.py +-- static @@ -102,7 +102,7 @@ folders, each of them containing the different resources used by the theme (templates, images, SCSS files, etc). The folder structure of a WireCloud theme should be similar to the following one: -``` +```text mytheme +-- __init__.py +-- static diff --git a/docs/development/platform/translation.md b/docs/development/platform/translation.md index ce1e958321..53a63fd521 100644 --- a/docs/development/platform/translation.md +++ b/docs/development/platform/translation.md @@ -1,16 +1,20 @@ First of all, you need to download WireCloud's source code from the github repository: - $ git clone https://github.com/Wirecloud/wirecloud.git +```bash +git clone https://github.com/Wirecloud/wirecloud.git +``` Once you have the source code to translate, next step is creating or updating the catalogue of messages to translate, this can be accomplished with the following commands: - $ cd ${wirecloud_repo_path}/src - $ cd ${module} - $ django-admin makemessages -l ${locale} - $ django-admin makemessages -l ${locale} -d djangojs +```bash +cd ${wirecloud_repo_path}/src +cd ${module} +django-admin makemessages -l ${locale} +django-admin makemessages -l ${locale} -d djangojs +``` Where: @@ -36,14 +40,18 @@ Once you feel comfortable with your translated message catalogue, you can compile it for testing purporses by running the following commands (for each module): - $ cd ${wirecloud_repo_path}/src - $ cd ${module} - $ django-admin compilemessages +```bash +cd ${wirecloud_repo_path}/src +cd ${module} +django-admin compilemessages +``` After compiling messages, you can test them by running WireCloud. As we're developing, the recommended way is by executing the runserver command: - $ python manage.py runserver --insecure +```bash +python manage.py runserver --insecure +``` You have several choices for contributing your translations. First, if you feel comfortable sending github pull request, this is the preffered way, followed by diff --git a/docs/development/widget_and_operators.md b/docs/development/widget_and_operators.md index 3c2896e580..8bc5a6f69f 100644 --- a/docs/development/widget_and_operators.md +++ b/docs/development/widget_and_operators.md @@ -1,35 +1,28 @@ -Before starting the creation of a widget, the developer should be aware of -certain design principles of the widgets: - -- Widgets are supposed to be small, reusable and user centric web applications. -- Generic widgets are desirable, but ad-hoc solutions are allowed too if they - are quick and cheap enough. -- Widgets should be adapted to real problems. -- Widgets are mainly elements of the front-end layer (View). Widgets can access - backend services directly, but is preferred to create operators when possible - for those tasks. Then those widgets and operators can be connected by making - use of the wiring editor. -- During the development of widgets any technology accepted by web browsers - (XHTML, JavaScript, SVG, Flash, applets ....) can be used. +Before starting the creation of a widget, the developer should be aware of certain design principles of the widgets: + +- Widgets are supposed to be small, reusable and user centric web applications. +- Generic widgets are desirable, but ad-hoc solutions are allowed too if they are quick and cheap enough. +- Widgets should be adapted to real problems. +- Widgets are mainly elements of the front-end layer (View). Widgets can access backend services directly, but is + preferred to create operators when possible for those tasks. Then those widgets and operators can be connected by + making use of the wiring editor. +- During the development of widgets any technology accepted by web browsers (XHTML, JavaScript, SVG, Flash, applets + ....) can be used. Widgets can be split up into three different components: -- A Descriptor (`config.xml`), which is a declarative description of the widget. - This file contains, among other things, references to the rest of resources of - the widget. This description file is written using the Mashable Application - Component Description Language (a.k.a [MACDL](macdl.md)). -- Code, composed of HTML files, JavaScript files, CSS files, SVG files ...: - those files contains the implementation of the widget and they work exactly if - you were creating a standard web page. The only thing to take into account is - that your code will have access to a new API: the - [Widget API](../widgetapi/widgetapi.md). -- Static resources, such as images, documentation and other static resources. - -All those files should be packaged together into a zip file (usually renamed to -use the `.wgt` extension). The following figure shows one possible structure of -files for a widget: +- A Descriptor (`config.xml`), which is a declarative description of the widget. This file contains, among other + things, references to the rest of resources of the widget. This description file is written using the Mashable + Application Component Description Language (a.k.a [MACDL](macdl.md)). +- Code, composed of HTML files, JavaScript files, CSS files, SVG files ...: those files contains the implementation of + the widget and they work exactly if you were creating a standard web page. The only thing to take into account is + that your code will have access to a new API: the [Widget API](../widgetapi/widgetapi.md). +- Static resources, such as images, documentation and other static resources. -``` +All those files should be packaged together into a zip file (usually renamed to use the `.wgt` extension). The following +figure shows one possible structure of files for a widget: + +```text . +-- docs | | ... @@ -49,62 +42,47 @@ files for a widget: +-- DESCRIPTION.md ``` -> It's recommended to use this kind of structure (or a similar one), but you can -> use whatever you want, except that the `config.xml` file MUST be at the root -> of the zip file. +> It's recommended to use this kind of structure (or a similar one), but you can use whatever you want, except that the +> `config.xml` file MUST be at the root of the zip file. -Operators are created in the same way as widgets, the only difference is that -the descriptor file (`config.xml`) does not link to an initial HTML document (as -operators doesn't have a visual component). Instead, you will have to link the +Operators are created in the same way as widgets, the only difference is that the descriptor file (`config.xml`) does +not link to an initial HTML document (as operators doesn't have a visual component). Instead, you will have to link the list of used JavaScript files from the `config.xml` file. Operators can be classified using three types: -- **Data source operators:** Operators that provide information that can be - consumed by other widgets/operators. For example, an operator that retrieves - some type of information from a web service. -- **Data target operators:** Operators that are provided information and use it - to do some tasks. For example, an operator that receives some information and - push it to a web service. -- **Data transformation operators:** This type of operators can be very useful - since they can transform data in order to make it usable by widgets or - operators that expect data structure to be slightly different. +- **Data source operators:** Operators that provide information that can be consumed by other widgets/operators. For + example, an operator that retrieves some type of information from a web service. +- **Data target operators:** Operators that are provided information and use it to do some tasks. For example, an + operator that receives some information and push it to a web service. +- **Data transformation operators:** This type of operators can be very useful since they can transform data in order + to make it usable by widgets or operators that expect data structure to be slightly different. +# Preparing your widget/operator projects -Preparing your widget/operator projects -======================================= +As you see, building a WireCloud widget/operator is a matter of editing some files and packaging them into a zip file, +so simple widgets/operators can be created using a simple editor and a zip tool. -As you see, building a WireCloud widget/operator is a matter of editing some -files and packaging them into a zip file, so simple widgets/operators can be -created using a simple editor and a zip tool. - -However, you will need a more sophisticated schema if you want to pass unit -tests, deploy widgets/operators automatically, etc. +However, you will need a more sophisticated schema if you want to pass unit tests, deploy widgets/operators +automatically, etc. WireCloud provides the following tools to ease this process: -- A - [mock of the Widget API](https://github.com/Wirecloud/mock-applicationmashup), - so you can pass your unit tests without having to deploy your widget/operator - into a WireCloud instance. -- A [set of tools for grunt](https://github.com/Wirecloud/grunt-wirecloud) - allowing you to deploy widgets and operators using grunt tasks. -- A [grunt-init template for operator projects](https://github.com/Wirecloud/grunt-init-wirecloud-operator) - and another [grunt-init template for widget projects](https://github.com/Wirecloud/grunt-init-wirecloud-widget). - Projects created using those templates, will make use of the Widget API mock - and [jasmine](http://jasmine.github.io/) for unit testing the widget/operator, - [grunt](http://gruntjs.com/) for building it and grunt-wirecloud for deploying - it. Remember that you can always fork those templates for adapting them to - your needs (or requesting new features, bug fixes, etc. through the issue - tracker of the template repo). -- An [Eclipse plugin](eclipse_ide.md) for those preferring a full IDE. - - -What next? -========== +- A [mock of the Widget API](https://github.com/Wirecloud/mock-applicationmashup), so you can pass your unit tests + without having to deploy your widget/operator into a WireCloud instance. +- A [set of tools for grunt](https://github.com/Wirecloud/grunt-wirecloud) allowing you to deploy widgets and + operators using grunt tasks. +- A [grunt-init template for operator projects](https://github.com/Wirecloud/grunt-init-wirecloud-operator) and + another [grunt-init template for widget projects](https://github.com/Wirecloud/grunt-init-wirecloud-widget). + Projects created using those templates, will make use of the Widget API mock and + [jasmine](http://jasmine.github.io/) for unit testing the widget/operator, [grunt](http://gruntjs.com/) for building + it and grunt-wirecloud for deploying it. Remember that you can always fork those templates for adapting them to your + needs (or requesting new features, bug fixes, etc. through the issue tracker of the template repo). +- An [Eclipse plugin](eclipse_ide.md) for those preferring a full IDE. + +# What next? We recommend you to continue following the -[WireCloud course at the FIWARE Academy](http://edu.fiware.org/course/view.php?id=53), -as we think that it's easier to learn by examples. Anyway, the following -sections will provide the reference documentation for developing widgets and +[WireCloud course at the FIWARE Academy](http://edu.fiware.org/course/view.php?id=53), as we think that it's easier to +learn by examples. Anyway, the following sections will provide the reference documentation for developing widgets and operators for WireCloud. diff --git a/docs/index.md b/docs/index.md index c0e8e8c675..b8c31f6ec0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,44 +7,38 @@ [![](https://img.shields.io/badge/FIWARE-Visualization-88a1ce.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABsAAAAVCAYAAAC33pUlAAAABHNCSVQICAgIfAhkiAAAA8NJREFUSEuVlUtIFlEUx+eO+j3Uz8wSLLJ3pBiBUljRu1WLCAKXbXpQEUFERSQF0aKVFAUVrSJalNXGgmphFEhQiZEIPQwKLbEUK7VvZrRvbr8zzjfNl4/swplz7rn/8z/33HtmRhn/MWzbXmloHVeG0a+VSmAXorXS+oehVD9+0zDN9mgk8n0sWtYnHo5tT9daH4BsM+THQC8naK02jCZ83/HlKaVSzBey1sm8BP9nnUpdjOfl/Qyzj5ust6cnO5FItJLoJqB6yJ4QuNcjVOohegpihshS4F6S7DTVVlNtFFxzNBa7kcaEwUGcbVnH8xOJD67WG9n1NILuKtOsQG9FngOc+lciic1iQ8uQGhJ1kVAKKXUs60RoQ5km93IfaREvuoFj7PZsy9rGXE9G/NhBsDOJ63Acp1J82eFU7OIVO1OxWGwpSU5hb0GqfMydMHYSdiMVnncNY5Vy3VbwRUEydvEaRxmAOSSqJMlJISTxS9YWTYLcg3B253xsPkc5lXk3XLlwrPLuDPKDqDIutzYaj3eweMkPeCCahO3+fEIF8SfLtg/5oI3Mh0ylKM4YRBaYzuBgPuRnBYD3mmhA1X5Aka8NKl4nNz7BaKTzSgsLCzWbvyo4eK9r15WwLKRAmmCXXDoA1kaG2F4jWFbgkxUnlcrB/xj5iHxFPiBN4JekY4nZ6ccOiQ87hgwhe+TOdogT1nfpgEDTvYAucIwHxBfNyhpGrR+F8x00WD33VCNTOr/Wd+9C51Ben7S0ZJUq3qZJ2OkZz+cL87ZfWuePlwRcHZjeUMxFwTrJZAJfSvyWZc1VgORTY8rBcubetdiOk+CO+jPOcCRTF+oZ0okUIyuQeSNL/lPrulg8flhmJHmE2gBpE9xrJNkwpN4rQIIyujGoELCQz8ggG38iGzjKkXufJ2Klun1iu65bnJub2yut3xbEK3UvsDEInCmvA6YjMeE1bCn8F9JBe1eAnS2JksmkIlEDfi8R46kkEkMWdqOv+AvS9rcp2bvk8OAESvgox7h4aWNMLd32jSMLvuwDAwORSE7Oe3ZRKrFwvYGrPOBJ2nZ20Op/mqKNzgraOTPt6Bnx5citUINIczX/jUw3xGL2+ia8KAvsvp0ePoL5hXkXO5YvQYSFAiqcJX8E/gyX8QUvv8eh9XUq3h7mE9tLJoNKqnhHXmCO+dtJ4ybSkH1jc9XRaHTMz1tATBe2UEkeAdKu/zWIkUbZxD+veLxEQhhUFmbnvOezsJrk+zmqMo6vIL2OXzPvQ8v7dgtpoQnkF/LP8Ruu9zXdJHg4igAAAABJRU5ErkJgggA=)](https://www.fiware.org/developers/catalogue/) [![Support badge](https://img.shields.io/badge/tag-fiware--wirecloud-orange.svg?logo=stackoverflow)](https://stackoverflow.com/questions/tagged/fiware-wirecloud) -WireCloud builds on cutting-edge end-user development, RIA and semantic -technologies to offer a next-generation end-user centred web application mashup -platform aimed at leveraging the long tail of the Internet of Services. +## Wirecloud -WireCloud builds on cutting-edge end-user (software) development, RIA and -semantic technologies to offer a next-generation end-user centred web -application mashup platform aimed at allowing end users without programming -skills to easily create web applications and dashboards/cockpits (e.g. to -visualize their data of interest or to control their domotized home or -environment). Web application mashups integrate heterogeneous data, application -logic, and UI components (widgets) sourced from the Web to create new coherent -and value-adding composite applications. They are targeted at leveraging the -"long tail" of the Web of Services (a.k.a. the Programmable Web) by exploiting -rapid development, DIY, and shareability. They typically serve a specific -situational (i.e. immediate, short-lived, customized) need, frequently with high -potential for reuse. Is this "situational" character which precludes them to be -offered as 'off-the-shelf' functionality by solution providers, and therefore -creates the need for a tool like WireCloud. - -This project is part of [FIWARE](https://www.fiware.org). Check it out in the -[Catalogue](https://catalogue.fiware.org/enablers/application-mashup-wirecloud) +- [Introduction](index.md) +- [Installation Guide](installation_guide.md) +- [Administration Guide](administration_guide.md) +- [User Guide](user_guide.md) +- Programmer Guide: + - [Application Mashup RESTful API](restapi/index.md) + - MACDL: + - [Introduction](development/macdl.md) + - [MACDL (XML)](development/macdl_xml.md) + - [MACDL (RDF)](development/macdl_rdf.md) + - Widget & Operator Development: + - [Basic Concepts](development/widget_and_operators.md) + - [Widget API](widgetapi/widgetapi.md) + - [NGSI API](development/ngsi_api.md) + - [ObjectStorage API](development/object_storage_api.md) + - [WireCloud IDE](development/eclipse_ide.md) +WireCloud builds on cutting-edge end-user development, RIA and semantic technologies to offer a next-generation end-user +centred web application mashup platform aimed at leveraging the long tail of the Internet of Services. -## Index +WireCloud builds on cutting-edge end-user (software) development, RIA and semantic technologies to offer a +next-generation end-user centred web application mashup platform aimed at allowing end users without programming skills +to easily create web applications and dashboards/cockpits (e.g. to visualize their data of interest or to control their +domotized home or environment). Web application mashups integrate heterogeneous data, application logic, and UI +components (widgets) sourced from the Web to create new coherent and value-adding composite applications. They are +targeted at leveraging the "long tail" of the Web of Services (a.k.a. the Programmable Web) by exploiting rapid +development, DIY, and shareability. They typically serve a specific situational (i.e. immediate, short-lived, +customized) need, frequently with high potential for reuse. Is this "situational" character which precludes them to be +offered as 'off-the-shelf' functionality by solution providers, and therefore creates the need for a tool like +WireCloud. -- [Introduction](index.md) -- [Installation Guide](installation_guide.md) -- [Administration Guide](administration_guide.md) -- [User Guide](user_guide.md) -- Programmer Guide: - - [Application Mashup RESTful API](restapi/index.md) - - MACDL: - - [Introduction](development/macdl.md) - - [MACDL (XML)](development/macdl_xml.md) - - [MACDL (RDF)](development/macdl_rdf.md) - - Widget & Operator Development: - - [Basic Concepts](development/widget_and_operators.md) - - [Widget API](widgetapi/widgetapi.md) - - [NGSI API](development/ngsi_api.md) - - [ObjectStorage API](development/object_storage_api.md) - - [WireCloud IDE](development/eclipse_ide.md) +This project is part of [FIWARE](https://www.fiware.org). Check it out in the +[Catalogue](https://catalogue.fiware.org/enablers/application-mashup-wirecloud) diff --git a/docs/installation_guide.md b/docs/installation_guide.md index a29a08ecfc..02020d707e 100644 --- a/docs/installation_guide.md +++ b/docs/installation_guide.md @@ -1,111 +1,118 @@ ## Introduction -This Installation WireCloud version 1.2 (starting from FIWARE release 7.4). Any -feedback on this document is highly welcomed, including bugs, typos or things -you think should be included but are not. Please send it to the "Contact Person" -email that appears in the [Catalogue page for this GEi][catalogue]. +This Installation WireCloud version 1.2 (starting from FIWARE release 7.4). Any feedback on this document is highly +welcomed, including bugs, typos or things you think should be included but are not. Please send it to the "Contact +Person" email that appears in the [Catalogue page for this GEi][catalogue]. [catalogue]: http://catalogue.fiware.org/enablers/application-mashup-wirecloud - ## Requirements -This section describes all the requirements of a basic WireCloud installation. -**However, these dependencies are not meant to be installed manually in this -step, as they will be installed throughout the documentation:** - -- A Database Manager (MySQL, PostgreSQL, SQLite3...) -- Python 2.7 or python 3.4+. In any case, the following python packages must be - installed: - - Django 1.9-1.11 - - lxml 2.3.0+ - - django-appconf 1.0.1+ - - django_compressor 2.0+ - - rdflib 3.2.0+ - - requests 2.1.0+ - - futures 2.1.3+ (only on python 2.7) - - selenium 3.4+ - - pytz - - django_relatives 0.3.x - - user-agents - - regex - - markdown - - haystack 2.4.1+ - - whoosh 2.7.2+ - - pycrypto - - pyScss 1.3.4+ - - Pygments - - pillow - - jsonpatch - -All these dependencies are available for Linux, Mac OS and Windows, so WireCloud -should work on any of these operating systems. However, it is better to use -Debian Wheezy+, CentOS 6+, Ubuntu 12.04+ or Mac OS X 10.9+ (only recommended for -development/testing) as these operating systems are actively tested. -Specifically, this installation guide was tested in the following systems: - -- Ubuntu 16.04 -- Ubuntu 14.04 -- Ubuntu 12.04 -- CentOS 6 -- CentOS 7 -- Debian Wheezy -- Debian Jessie -- Mac OS 10.9+ - -> **NOTE**: WireCloud can make use of the -> [Marketplace](http://catalogue.fiware.org/enablers/marketplace-wmarket), -> the [Store](http://catalogue.fiware.org/enablers/store-wstore) and the -> [Repository](http://catalogue.fiware.org/enablers/repository-repository-ri) -> GEs, but take into account that those GEs has been deprecated in favor of the -> Bussiness API Ecosystem GE. +This section describes all the requirements of a basic WireCloud installation. **However, these dependencies are not +meant to be installed manually in this step, as they will be installed throughout the documentation:** + +- A Database Manager (MySQL, PostgreSQL, SQLite3...) +- Python 2.7 or python 3.4+. In any case, the following python packages must be installed: + - Django 1.9-1.11 + - lxml 2.3.0+ + - django-appconf 1.0.1+ + - django_compressor 2.0+ + - rdflib 3.2.0+ + - requests 2.1.0+ + - futures 2.1.3+ (only on python 2.7) + - selenium 3.4+ + - pytz + - django_relatives 0.3.x + - user-agents + - regex + - markdown + - haystack 2.4.1+ + - whoosh 2.7.2+ + - pycrypto + - pyScss 1.3.4+ + - Pygments + - pillow + - jsonpatch + +All these dependencies are available for Linux, Mac OS and Windows, so WireCloud should work on any of these operating +systems. However, it is better to use Debian Wheezy+, CentOS 6+, Ubuntu 12.04+ or Mac OS X 10.9+ (only recommended for +development/testing) as these operating systems are actively tested. Specifically, this installation guide was tested in +the following systems: + +- Ubuntu 16.04 +- Ubuntu 14.04 +- Ubuntu 12.04 +- CentOS 6 +- CentOS 7 +- Debian Wheezy +- Debian Jessie +- Mac OS 10.9+ + +> **NOTE**: WireCloud can make use of the [Marketplace](http://catalogue.fiware.org/enablers/marketplace-wmarket), the +> [Store](http://catalogue.fiware.org/enablers/store-wstore) and the +> [Repository](http://catalogue.fiware.org/enablers/repository-repository-ri) GEs, but take into account that those GEs +> has been deprecated in favor of the Bussiness API Ecosystem GE. > > [http://catalogue.fiware.org](http://catalogue.fiware.org)). - ## Installing basic dependencies -Before installing WireCloud, you will need to have some basic dependencies installed: python and [pip](http://www.pip-installer.org/en/latest/installing.html). - -> **NOTE**: Although virtualenv is not required, you should install it before installing WireCloud if you intend to use it. It is highly recommended to use virtualenv (see the using [virtualenv section](#using-virtualenv) for more info) when installing WireCloud in CentOS/RedHat as those systems usually raise problems when installing python packages from their official repositories and, at the same time, from pip (a common case in those systems, as some packages should be updated for being compatible with WireCloud, but are requirements of other system applications). Anyway, although harder, it is possible to install WireCloud in those systems without using virtual environments. +Before installing WireCloud, you will need to have some basic dependencies installed: python and +[pip](http://www.pip-installer.org/en/latest/installing.html). +> **NOTE**: Although virtualenv is not required, you should install it before installing WireCloud if you intend to use +> it. It is highly recommended to use virtualenv (see the using [virtualenv section](#using-virtualenv) for more info) +> when installing WireCloud in CentOS/RedHat as those systems usually raise problems when installing python packages +> from their official repositories and, at the same time, from pip (a common case in those systems, as some packages +> should be updated for being compatible with WireCloud, but are requirements of other system applications). Anyway, +> although harder, it is possible to install WireCloud in those systems without using virtual environments. ### Debian/Ubuntu This guide assumes you system's package list is up to date. Otherwise, run the following command: - $ apt-get update +```bash +$ apt-get update +``` before installing software in Debian/Ubuntu: - $ apt-get install python python-pip --no-install-recommends +```bash +apt-get install python python-pip --no-install-recommends +``` It's recommended to upgrade your pip installation: - $ pip install -U pip +```bash +pip install -U pip +``` And make sure you have a updated version of setuptools: - $ pip install "setuptools>18.5" +```bash +pip install "setuptools>18.5" +``` It's also recommended to install the following packages: - $ apt-get install build-essential python-dev libxml2-dev libxslt1-dev zlib1g-dev libpcre3-dev libcurl4-openssl-dev libjpeg-dev +```bash +apt-get install build-essential python-dev libxml2-dev libxslt1-dev zlib1g-dev libpcre3-dev libcurl4-openssl-dev libjpeg-dev +``` and the following pip packages: - $ pip install pyOpenSSL ndg-httpsclient pyasn1 +```bash +pip install pyOpenSSL ndg-httpsclient pyasn1 +``` ### CentOS & Red Hat Enterprise Linux - #### CentOS/RHEL 6 -CentOS/RHEL 6 only ships python 2.6, so you have to install python 2.7 from a -different repository. We recommend you to use the Software Collection -respository: +CentOS/RHEL 6 only ships python 2.6, so you have to install python 2.7 from a different repository. We recommend you to +use the Software Collection respository: -``` +```text # 1. Install a package with repository for your system: # On CentOS, install package centos-release-scl available in CentOS repository: $ sudo yum install centos-release-scl @@ -120,99 +127,129 @@ $ sudo yum install python27 $ scl enable python27 bash ``` -After installing python 2.7 from Software Collections, you have to manually -install pip using `easy_install`: +After installing python 2.7 from Software Collections, you have to manually install pip using `easy_install`: - $ easy_install pip +```bash +easy_install pip +``` It's also recommended to install the following packages: - $ yum install gcc libxslt-devel zlib-devel pcre-devel libcurl-devel libjpeg-devel libffi-devel openssl-devel +```bash +yum install gcc libxslt-devel zlib-devel pcre-devel libcurl-devel libjpeg-devel libffi-devel openssl-devel +``` and the following pip packages: - $ pip install pyOpenSSL ndg-httpsclient pyasn1 - +```bash +pip install pyOpenSSL ndg-httpsclient pyasn1 +``` -> **NOTE**: installing python2.7 using SCL automatically installs -> `python27-python-devel`, if you install python using another source, you -> should ensure the equivalent package is also installed. +> **NOTE**: installing python2.7 using SCL automatically installs `python27-python-devel`, if you install python using +> another source, you should ensure the equivalent package is also installed. #### CentOS/RHEL 7 -The python package shiped by default by CentOS/RHEL 7 is enough for using -WireCloud, so you can install it directly from their repositories: +The python package shiped by default by CentOS/RHEL 7 is enough for using WireCloud, so you can install it directly from +their repositories: - $ yum install python +```bash +yum install python +``` -Whereas pip and other packages should be installed from 3rd party repositories. -The most common one is the EPEL repository (see -http://fedoraproject.org/wiki/EPEL for instructions about how to add it). If you -has such a repository, you will be able to install pip using the following -command: +Whereas pip and other packages should be installed from 3rd party repositories. The most common one is the EPEL +repository (see http://fedoraproject.org/wiki/EPEL for instructions about how to add it). If you has such a repository, +you will be able to install pip using the following command: - $ yum install epel-release - $ yum install python-pip +```bash +yum install epel-release +yum install python-pip +``` It's also recommended to install the following packages: - $ yum install gcc python-devel libxslt-devel zlib-devel pcre-devel libcurl-devel libjpeg-devel libffi-devel openssl-devel +```bash +yum install gcc python-devel libxslt-devel zlib-devel pcre-devel libcurl-devel libjpeg-devel libffi-devel openssl-devel +``` and the following pip packages: - $ pip install pyOpenSSL ndg-httpsclient pyasn1 +```bash +pip install pyOpenSSL ndg-httpsclient pyasn1 +``` ### Mac OS -Python comes installed by default in Mac OS, so you don't need to install it. pip can be installed using the following command: +Python comes installed by default in Mac OS, so you don't need to install it. pip can be installed using the following +command: - $ sudo easy_install pip +```bash +sudo easy_install pip +``` However, we recommend you to upgrade your python installation using the [Homebrew](http://brew.sh/) tools for Mac: - $ brew install python +```bash +brew install python +``` This command will install, as bonus, the pip command tool. It's also recommended to install the following package: - $ brew install pcre +```bash +brew install pcre +``` You will also need the command line developer tools for xcode. You can install them by running the following command: - $ xcode-select --install +```bash +xcode-select --install +``` ### Using virtualenv -[virtualenv](http://virtualenv.readthedocs.org/en/latest/virtualenv.html) is a tool to create isolated Python environments. Those Virtual Environments, are an isolated working copy of Python which allows you to work on a specific project without worry of affecting other projects. +[virtualenv](http://virtualenv.readthedocs.org/en/latest/virtualenv.html) is a tool to create isolated Python +environments. Those Virtual Environments, are an isolated working copy of Python which allows you to work on a specific +project without worry of affecting other projects. virtualenv can be installed using pip: - $ pip install virtualenv +```bash +pip install virtualenv +``` Once installed virtualenv, you will be able to create virtual environments using the following command: - $ virtualenv venv +```bash +virtualenv venv +``` -This will create an `venv` folder for storing all the resources related to the virtual environment. To begin using the virtual environment, it needs to be activated: +This will create an `venv` folder for storing all the resources related to the virtual environment. To begin using the +virtual environment, it needs to be activated: - $ source venv/bin/activate +```bash +source venv/bin/activate +``` -You can then begin installing any new modules without affecting the system default Python or other virtual environments. If you are done working in the virtual environment for the moment, you can deactivate it: +You can then begin installing any new modules without affecting the system default Python or other virtual environments. +If you are done working in the virtual environment for the moment, you can deactivate it: - $ deactivate +```bash +deactivate +``` This puts you back to the system’s default Python interpreter with all its installed libraries. To delete a virtual environment, just delete its folder. - ## Installing WireCloud using pip (recommended) You can always install the latest stable version of WireCloud using pip: - $ sudo pip install wirecloud - +```bash +sudo pip install wirecloud +``` ## Installing WireCloud from sources @@ -220,112 +257,116 @@ The WireCloud source code is available on the [GitHub WireCloud repository](http To get the latest development version of the code, you can choose between two options: -- Go to the WireCloud repository on GitHub, switch to the `1.0.x` branch (or select a specific 1.0.x tag, e.g. `1.0.0`) and click on the *Download ZIP* button to download the repository as a zip file, or just click on this [link](https://github.com/Wirecloud/wirecloud/zipball/1.0.x). Unzip it. -- Or use a [GIT](http://git-scm.com/) client to get the latest development version via Git: +- Go to the WireCloud repository on GitHub, switch to the `1.0.x` branch (or select a specific 1.0.x tag, e.g. + `1.0.0`) and click on the _Download ZIP_ button to download the repository as a zip file, or just click on this + [link](https://github.com/Wirecloud/wirecloud/zipball/1.0.x). Unzip it. +- Or use a [GIT](http://git-scm.com/) client to get the latest development version via Git: - $ git clone https://github.com/Wirecloud/wirecloud.git - $ cd wirecloud - $ git checkout 1.0.x +```bash +git clone https://github.com/Wirecloud/wirecloud.git +cd wirecloud +git checkout 1.0.x +``` -> **NOTE**: The `1.0.x` branch provides the latests stable version for the `1.0` -> version of WireCloud (that is, the version described in this guide). the -> latest development version for the `1.0.x` serie is provided by the -> `1.0.x-dev` branch, while the latest development version of WireCloud is -> available in the `develop` branch. +> **NOTE**: The `1.0.x` branch provides the latests stable version for the `1.0` version of WireCloud (that is, the +> version described in this guide). the latest development version for the `1.0.x` serie is provided by the `1.0.x-dev` +> branch, while the latest development version of WireCloud is available in the `develop` branch. > -> It's recommended to check if you are reading the latest version of this guide -> (e.g. following this [link][latest_docs]) if you are going to install the -> latest version of WireCloud from the `develop` branch instead of using the -> `1.0.x` branch. +> It's recommended to check if you are reading the latest version of this guide (e.g. following this +> [link][latest_docs]) if you are going to install the latest version of WireCloud from the `develop` branch instead of +> using the `1.0.x` branch. -Once downloaded the source code, you can install WireCloud using the `setup.py` script (this step requires root privileges): +Once downloaded the source code, you can install WireCloud using the `setup.py` script (this step requires root +privileges): - $ cd ${path_to_source_code}/src - $ python setup.py bdist_wheel - $ sudo pip install dist/wirecloud-${version}-py2.py3-none-any.whl +```bash +cd ${path_to_source_code}/src +python setup.py bdist_wheel +sudo pip install dist/wirecloud-${version}-py2.py3-none-any.whl +``` Where `${version}` is the version of WireCloud to install. -> **NOTE**: There are extra dependencies for being able to use the `setup.py` -> script: `setuptools` >= 18.5 and `wheel` > 0.24. You can install them using -> pip: `pip install "setuptools>18.5" "wheel>=0.24"` +> **NOTE**: There are extra dependencies for being able to use the `setup.py` script: `setuptools` >= 18.5 and `wheel` > +> 0.24. You can install them using pip: `pip install "setuptools>18.5" "wheel>=0.24"` [latest_docs]: https://wirecloud.readthedocs.org/en/latest/installation_guide/ - ## Installing WireCloud using Docker -WireCloud can also be deployed using [Docker](https://www.docker.com/), the images can be found on [docker hub](https://hub.docker.com/r/fiware/wirecloud/). This guide doesn't cover WireCloud installation using docker, please refere to the [docker's documentation](https://docs.docker.com/userguide/dockerimages/), as it can be used as any other docker image (e.g. it can also be used with docker-machine); and to the documentation available on docker hub about the WireCloud's image for more info about how to procede in this case. Anyway, once installed, you can make changes in the configuration of your WireCloud container following the steps described in this guide as well as make use of any of the administration procedures described in the [Administration Guide](administration_guide.md) section. +WireCloud can also be deployed using [Docker](https://www.docker.com/), the images can be found on +[docker hub](https://hub.docker.com/r/fiware/wirecloud/). This guide doesn't cover WireCloud installation using docker, +please refere to the [docker's documentation](https://docs.docker.com/userguide/dockerimages/), as it can be used as any +other docker image (e.g. it can also be used with docker-machine); and to the documentation available on docker hub +about the WireCloud's image for more info about how to procede in this case. Anyway, once installed, you can make +changes in the configuration of your WireCloud container following the steps described in this guide as well as make use +of any of the administration procedures described in the [Administration Guide](administration_guide.md) section. -> WireCloud's DockerFiles and image documentation are hosted on the [docker-wirecloud](https://github.com/Wirecloud/docker-wirecloud/) repository. +> WireCloud's DockerFiles and image documentation are hosted on the +> [docker-wirecloud](https://github.com/Wirecloud/docker-wirecloud/) repository. ## Creating a new instance of WireCloud -Once installed WireCloud, you will have access to the `wirecloud-admin` script. -This script is, among other things, used for deploy new instances of WireCloud. -Before creating the instance, we recommend you to create a special user for -managing and running WireCloud. Through the use of this user, WireCloud will be -able to limit the potential effects of a security breach. +Once installed WireCloud, you will have access to the `wirecloud-admin` script. This script is, among other things, used +for deploy new instances of WireCloud. Before creating the instance, we recommend you to create a special user for +managing and running WireCloud. Through the use of this user, WireCloud will be able to limit the potential effects of a +security breach. -For example, you can create such a user using the following commands in -Debian/Ubuntu: +For example, you can create such a user using the following commands in Debian/Ubuntu: - $ adduser --system --group --shell /bin/bash wirecloud +```bash +adduser --system --group --shell /bin/bash wirecloud +``` -Remember to use this user for creating new instances, for running the -`manage.py` script and for running the WireCloud instance (e.g. when using -Apache). +Remember to use this user for creating new instances, for running the `manage.py` script and for running the WireCloud +instance (e.g. when using Apache). -New instances of WireCloud can be created using the `wirecloud-admin`'s -`startproject` command. This will create a new directory containing the -`manage.py` script, the configuration files, ... related to the new instance. -Moreover, you can add new python modules into this directory to customise your -instance. +New instances of WireCloud can be created using the `wirecloud-admin`'s `startproject` command. This will create a new +directory containing the `manage.py` script, the configuration files, ... related to the new instance. Moreover, you can +add new python modules into this directory to customise your instance. - $ cd /opt - $ wirecloud-admin startproject wirecloud_instance +```bash +cd /opt +wirecloud-admin startproject wirecloud_instance +``` -> **NOTE**: This guide assumes that the WireCloud instances are created in -> `/opt`, although you can create them in any place on the filesystem. Anyway, -> if you decide to install into `/opt` and you chose to create a user for -> WireCloud, take into account that this user might not have enough permissions -> for writing inside `/opt`. +> **NOTE**: This guide assumes that the WireCloud instances are created in `/opt`, although you can create them in any +> place on the filesystem. Anyway, if you decide to install into `/opt` and you chose to create a user for WireCloud, +> take into account that this user might not have enough permissions for writing inside `/opt`. > -> One option is to create the instance using a user with enough permissions -> (e.g. `root`) and then changing the owner of the instance (e.g. -> `chown wirecloud:wirecloud -R /opt/wirecloud_instance`). - -After creating the new instance, you have to configure it choosing a database, -populating it and performing final Django configurations. These steps can be -skipped using the `--quick-start` option. This will configure the instance to -use SQLite3 with a default `admin` user (**password**: `admin`). This method is -very useful for creating a WireCloud instance for testing: +> One option is to create the instance using a user with enough permissions (e.g. `root`) and then changing the owner of +> the instance (e.g. `chown wirecloud:wirecloud -R /opt/wirecloud_instance`). - $ cd /opt - $ wirecloud-admin startproject wirecloud_instance --quick-start +After creating the new instance, you have to configure it choosing a database, populating it and performing final Django +configurations. These steps can be skipped using the `--quick-start` option. This will configure the instance to use +SQLite3 with a default `admin` user (**password**: `admin`). This method is very useful for creating a WireCloud +instance for testing: -> **NOTE**: Remember to change the default `admin` credentials as soon as -> possible, especially if the instance is publicly accessible. +```bash +cd /opt +wirecloud-admin startproject wirecloud_instance --quick-start +``` -If you make use of the `--quick-start` option, you should be able to go directly -to the [Running WireCloud](#running-wirecloud) section. +> **NOTE**: Remember to change the default `admin` credentials as soon as possible, especially if the instance is +> publicly accessible. +If you make use of the `--quick-start` option, you should be able to go directly to the +[Running WireCloud](#running-wirecloud) section. ## Database installation and configuration -To set up the database engine, it is necessary to modify the `DATABASE` -configuration setting in the instance `settings.py` file (e.g. -`/opt/wirecloud_instance/wirecloud_instance/settings.py`). You can use any of -the [database engines supported by Django]. +To set up the database engine, it is necessary to modify the `DATABASE` configuration setting in the instance +`settings.py` file (e.g. `/opt/wirecloud_instance/wirecloud_instance/settings.py`). You can use any of the [database +engines supported by Django]. The following examples show you how to configure SQLite and PostgreSQL databases. -[database engines supported by Django]: https://docs.djangoproject.com/en/1.11/ref/settings/#databases - +[database engines supported by django]: https://docs.djangoproject.com/en/1.11/ref/settings/#databases ### SQLite -Setting up a SQLite database can be just accomplished within seconds by using the following parameters into the `settings.py` file: +Setting up a SQLite database can be just accomplished within seconds by using the following parameters into the +`settings.py` file: ```python DATABASES = { @@ -342,16 +383,20 @@ DATABASES = { where `${dbfile}` is the full path to the database file. -Python directly comes with support for SQLite, but we recommend you to install the pysqlite2 module as it provides a more updated driver: +Python directly comes with support for SQLite, but we recommend you to install the pysqlite2 module as it provides a +more updated driver: - $ sudo pip install pysqlite - -Finally, please take into account that SQLite database is **not recommended for production purposes**. It is only useful for evaluation purposes. +```bash +sudo pip install pysqlite +``` +Finally, please take into account that SQLite database is **not recommended for production purposes**. It is only useful +for evaluation purposes. ### PostgreSQL -For production purposes, PostgreSQL database is a much better choice. To do so, the following parameters must be set in `settings.py`: +For production purposes, PostgreSQL database is a much better choice. To do so, the following parameters must be set in +`settings.py`: ```python DATABASES = { @@ -366,49 +411,72 @@ DATABASES = { } ``` -where `${dbname}` represents the name of the database, `${dbuser}` is the name of the user with privileges on the database and `${dbpassword}` is the password to use for authenticating the user. `${dbhost}` and `${dbport}` are the host and the port of the database server to use (leave these settings empty if the server is running on the same machine as WireCloud). +where `${dbname}` represents the name of the database, `${dbuser}` is the name of the user with privileges on the +database and `${dbpassword}` is the password to use for authenticating the user. `${dbhost}` and `${dbport}` are the +host and the port of the database server to use (leave these settings empty if the server is running on the same machine +as WireCloud). The only thing that remains is installing the python bindings for PostgreSQL: - $ sudo pip install psycopg2 +```bash +sudo pip install psycopg2 +``` Or alternatively, for Debian/Ubuntu: - $ sudo apt-get install python-psycopg2 +```bash +sudo apt-get install python-psycopg2 +``` #### Installing PostgresSQL on Debian/Ubuntu First install the object-relational database system. - $ sudo apt-get install postgresql +```bash +sudo apt-get install postgresql +``` -Afterwards you have to create the project Database. We assume that your user has super administrator permissions in PostgreSQL. This usually means that you have to login as the postgres user (i.e. `$ sudo su postgres`). +Afterwards you have to create the project Database. We assume that your user has super administrator permissions in +PostgreSQL. This usually means that you have to login as the postgres user (i.e. `$ sudo su postgres`). Both the PostgreSQL database and its user can be created with the following commands: - $ createuser ${dbuser} [-P] - $ createdb --owner=${dbuser} ${dbname} +```bash +createuser ${dbuser} [-P] +createdb --owner=${dbuser} ${dbname} +``` If you want to create a password protected user you must use the `-P` option. -If you want to create a database called 'wirecloud' and a user called 'wc_user' with privileges on this database, you should write the following: +If you want to create a database called 'wirecloud' and a user called 'wc_user' with privileges on this database, you +should write the following: - $ createuser wc_user [-P] - $ createdb --owner=wc_user wirecloud +```bash +createuser wc_user [-P] +createdb --owner=wc_user wirecloud +``` -Finally, it is also needed to allow local connections to the database, i.e. from the computer you are installing WireCloud. To do so, add the following rules to the beginning of the `/etc/postgresql/X.X/main/pg_hba.conf` file. In other words, the following two rules MUST be the first two rules of the file: +Finally, it is also needed to allow local connections to the database, i.e. from the computer you are installing +WireCloud. To do so, add the following rules to the beginning of the `/etc/postgresql/X.X/main/pg_hba.conf` file. In +other words, the following two rules MUST be the first two rules of the file: +```text # TYPE DATABASE USER CIDR-ADDRESS METHOD local wirecloud wc_user trust local test_wirecloud wc_user trust # only necessary for testing Wirecloud +``` Reload `pg_hba.conf` in PostgreSQL server with the following command: - $ sudo service postgresql reload +```bash +sudo service postgresql reload +``` And finally, restart PostgreSQL and check if your user has access using this command: - $ psql wirecloud -U wc_user +```bash +psql wirecloud -U wc_user +``` #### Installing PostgresSQL on other platforms @@ -416,59 +484,55 @@ Please, follow the [oficial PostgresSQL installation guide](http://www.postgresq ## Database population -Before running WireCloud, it is necessary to populate the database. This can be -achieved by using this command: +Before running WireCloud, it is necessary to populate the database. This can be achieved by using this command: - $ python manage.py migrate +```bash +python manage.py migrate +``` -This command is used for migrating the database between different versions of -WireCloud, but when executed the first time, it will serve for creating the -initial database structure. Once create, we have to create a superuser to be -able to login into WireCloud and to be able to perform administrative tasks from -the web interface. Use the `createsuperuser` command for creating such a user. -An example of the command output, where `user`/`password` are `admin`/`admin`, -is the following: +This command is used for migrating the database between different versions of WireCloud, but when executed the first +time, it will serve for creating the initial database structure. Once create, we have to create a superuser to be able +to login into WireCloud and to be able to perform administrative tasks from the web interface. Use the `createsuperuser` +command for creating such a user. An example of the command output, where `user`/`password` are `admin`/`admin`, is the +following: +```bash +python manage.py createsuperuser +``` - $ python manage.py createsuperuser +```text Username (leave blank to use 'wirecloud'): admin Email address: admin@myemaildomain.com Password: ***** (admin) Password (again): ***** (admin) Superuser created successfully. +``` -WireCloud 1.0 added some predefined dashboards, so you have to create them by -running the following command: +WireCloud 1.0 added some predefined dashboards, so you have to create them by running the following command: +```bash +python manage.py populate ``` -$ python manage.py populate -``` - ## Search indexes configuration -Wirecloud uses [Haystack](http://haystacksearch.org/) to handle the search -indexes. +Wirecloud uses [Haystack](http://haystacksearch.org/) to handle the search indexes. -Currently, [Solr][], [ElasticSearch2][] and [Whoosh][] are supported. Whoosh is enabled by -default. +Currently, [Solr][], [ElasticSearch2][] and [Whoosh][] are supported. Whoosh is enabled by default. -To modify the search engine configuration, it is necessary to modify the -`HAYSTACK_CONNECTIONS` configuration setting in the instance `settings.py` file -(e.g. `/opt/wirecloud_instance/wirecloud_instance/settings.py`). +To modify the search engine configuration, it is necessary to modify the `HAYSTACK_CONNECTIONS` configuration setting in +the instance `settings.py` file (e.g. `/opt/wirecloud_instance/wirecloud_instance/settings.py`). -[Solr]: http://lucene.apache.org/solr/ -[ElasticSearch2]: https://www.elastic.co/products/elasticsearch -[Whoosh]: https://whoosh.readthedocs.io/en/latest/ +[solr]: http://lucene.apache.org/solr/ +[elasticsearch2]: https://www.elastic.co/products/elasticsearch +[whoosh]: https://whoosh.readthedocs.io/en/latest/ ### Whoosh configuration -[Whoosh][] is a fast, featureful full-text indexing and searching library -implemented in pure Python. It is very easy to configure and does not require to -configure any service, so it is ideal for basic installations. This make this -engine the default engine for using WireCloud, altough probably ElasticSearch2 -or Solr are better choices if you require to provide an high availablility -installation of WireCloud. +[Whoosh][] is a fast, featureful full-text indexing and searching library implemented in pure Python. It is very easy to +configure and does not require to configure any service, so it is ideal for basic installations. This make this engine +the default engine for using WireCloud, altough probably ElasticSearch2 or Solr are better choices if you require to +provide an high availablility installation of WireCloud. This is the default configuration: @@ -481,17 +545,16 @@ HAYSTACK_CONNECTIONS = { } ``` -You can add the `HAYSTACK_CONNECTIONS` setting in the `settings.py` file to -change the `PATH` where Whoosh indices will be stored. - +You can add the `HAYSTACK_CONNECTIONS` setting in the `settings.py` file to change the `PATH` where Whoosh indices will +be stored. ### ElasticSearch2 configuration -[ElasticSearch][] support is not installed by default, so the first thing is to -install the python module required to connect to ElasticSearch: +[ElasticSearch][] support is not installed by default, so the first thing is to install the python module required to +connect to ElasticSearch: -``` -$ pip install elasticsearch==2.4.1 +```bash +pip install elasticsearch==2.4.1 ``` Next step is to configure haystack to use ElasticSearch: @@ -508,13 +571,13 @@ HAYSTACK_CONNECTIONS = { Where `URL` is the URL of the ElasticSearch2 server. - ### Solr cofiguration -Solr support is not installed by default, so the first thing is to install the python library required to connect to Solr: +Solr support is not installed by default, so the first thing is to install the python library required to connect to +Solr: -``` -$ pip install pysolr +```bash +pip install pysolr ``` Once installed `pysolr`, you have to change the Haystack configuration: @@ -531,24 +594,33 @@ HAYSTACK_CONNECTIONS = { Where the `URL` setting should point to the Solr core URL. -Haystack provides a command for generating the solr schema (needed to create the -solr core), but requires you to configure haystack to use the rSsolr engine before -running that command. You can provide and invalid URL (e.g. an empty string: -`''`) and change this configuration once you have created the core in the -Solr server. - -The Solr core can be created by running the following commannd: `bin/solr create -c wirecloud_core -n basic_config` on the Solr installation, where `wirecloud_core` is the core name. Then you have to execute the `python manage.py build_solr_schema` command jointly with the `--configure-directory` option on the WireCloud installation. Ideally, you should use the `--configure-directory` to point into the configuration folder (e.g. to `${SOLR_ROOT}/server/solr/wirecloud_core/conf`) of the Solr core, so it gets configured automatically. But if this is not possible (because the folder is in a remote server), you should point it into a temporal folder and copy the generated files (`schema.xml` and `solrconfig.xml`) to the final destination. You should also ensure the configuration folder does not contain a `managed-schema.xml` file, as this file is created by default and conflicts with the configuration created by Haystack. +Haystack provides a command for generating the solr schema (needed to create the solr core), but requires you to +configure haystack to use the rSsolr engine before running that command. You can provide and invalid URL (e.g. an empty +string: `''`) and change this configuration once you have created the core in the Solr server. +The Solr core can be created by running the following commannd: `bin/solr create -c wirecloud_core -n basic_config` on +the Solr installation, where `wirecloud_core` is the core name. Then you have to execute the +`python manage.py build_solr_schema` command jointly with the `--configure-directory` option on the WireCloud +installation. Ideally, you should use the `--configure-directory` to point into the configuration folder (e.g. to +`${SOLR_ROOT}/server/solr/wirecloud_core/conf`) of the Solr core, so it gets configured automatically. But if this is +not possible (because the folder is in a remote server), you should point it into a temporal folder and copy the +generated files (`schema.xml` and `solrconfig.xml`) to the final destination. You should also ensure the configuration +folder does not contain a `managed-schema.xml` file, as this file is created by default and conflicts with the +configuration created by Haystack. ## Extra options -Here’s a list of general settings available in WireCloud and their default values. These settings are configured in the `settings.py` file. Also, take into account that most of these settings are based on settings provided by Django (see [Django documentation](https://docs.djangoproject.com/en/dev/ref/settings) for more info). - +Here’s a list of general settings available in WireCloud and their default values. These settings are configured in the +`settings.py` file. Also, take into account that most of these settings are based on settings provided by Django (see +[Django documentation](https://docs.djangoproject.com/en/dev/ref/settings) for more info). ### ADMINS + > (Tuple, default: `()` [Empty tuple]) -A tuple that lists people who get code error notifications. When `DEBUG=False` and a view raises an exception, WireCloud will email these people with the full exception information. Each member of the tuple should be a tuple of (Full name, email address). Example: +A tuple that lists people who get code error notifications. When `DEBUG=False` and a view raises an exception, WireCloud +will email these people with the full exception information. Each member of the tuple should be a tuple of (Full name, +email address). Example: ```python (('John', 'john@example.com'), ('Mary', 'mary@example.com')) @@ -556,37 +628,39 @@ A tuple that lists people who get code error notifications. When `DEBUG=False` a Note that Django will email all of these people whenever an error happens. - ### ALLOW_ANONYMOUS_USER -> (Boolean; default: `True`) -A boolean that turns on/off anonymous user access. Take into account that disabling anonymous access will reduce the usefulness of embedded and public workspaces as they will require users to be logged in. +> (Boolean; default: `True`) +A boolean that turns on/off anonymous user access. Take into account that disabling anonymous access will reduce the +usefulness of embedded and public workspaces as they will require users to be logged in. ### DEBUG + > (Boolean; default: `False`) A boolean that turns on/off debug mode. **Never deploy a site into production with `DEBUG` turned on.** -One of the main features of debug mode is the display of detailed error pages. If WireCloud raises an exception when `DEBUG` is `True`, Django will display a detailed traceback, including a lot of metadata about your environment, such as all the currently defined Django settings (from `settings.py`). - +One of the main features of debug mode is the display of detailed error pages. If WireCloud raises an exception when +`DEBUG` is `True`, Django will display a detailed traceback, including a lot of metadata about your environment, such as +all the currently defined Django settings (from `settings.py`). ### DEFAULT_LANGUAGE -> (String; default: "browser") -Language code to use by default (e.g. "en"). This setting also support other values: "browser", meaning "use the language detected from browser" and "default" for using the value of the `LANGUAGE_CODE` setting. +> (String; default: "browser") +Language code to use by default (e.g. "en"). This setting also support other values: "browser", meaning "use the +language detected from browser" and "default" for using the value of the `LANGUAGE_CODE` setting. ### FIWARE_PORTALS + > (TUPLE, DEFAULT: `()`[Empty tuple]) -List of associated portals. This setting is used for signing out from other -portals at the same time the user sign out from Wirecloud, providing a single -sign out experience. This setting is also used for building the navigation bar -when using the `wirecloud.fiwarelabtheme` and `wirecloud.fiwarelabdarktheme` -themes. +List of associated portals. This setting is used for signing out from other portals at the same time the user sign out +from Wirecloud, providing a single sign out experience. This setting is also used for building the navigation bar when +using the `wirecloud.fiwarelabtheme` and `wirecloud.fiwarelabdarktheme` themes. As example, this is the configuration used in FIWARE Lab: @@ -624,8 +698,7 @@ FIWARE_PORTALS = ( ) ``` -If you want to add a portal into this list, but not in the navigation bar, you -only have to use the display attribute: +If you want to add a portal into this list, but not in the navigation bar, you only have to use the display attribute: ```python FIWARE_IDM_SERVER = "https://account.mydomain.com" @@ -645,14 +718,13 @@ FIWARE_PORTALS = ( ``` ### FORCE_DOMAIN + > (String, default: `None`) -Set `FORCE_DOMAIN` using an string if you want to force WireCloud to use a -concrete domain name (without including the port) when building internal URLs. -If this setting is `None` (the default), WireCloud will try to use the [Django's -sites framework](https://docs.djangoproject.com/en/1.11/ref/contrib/sites/) for -obtaining the domain info. If the sites framework is not used, the domain is -extracted from the request. +Set `FORCE_DOMAIN` using an string if you want to force WireCloud to use a concrete domain name (without including the +port) when building internal URLs. If this setting is `None` (the default), WireCloud will try to use the +[Django's sites framework](https://docs.djangoproject.com/en/1.11/ref/contrib/sites/) for obtaining the domain info. If +the sites framework is not used, the domain is extracted from the request. **Example Usage**: @@ -660,145 +732,134 @@ extracted from the request. FORCE_DOMAIN = "mashup.lab.fiware.org" ``` -> This setting is mainly useful when WireCloud is behind a web server acting as -> proxy. - +> This setting is mainly useful when WireCloud is behind a web server acting as proxy. ### FORCE_PORT -> (Integer, default: `None`) -Set `FORCE_PORT` using a number if you want to force WireCloud to use -that port when building internal URLs. +> (Integer, default: `None`) -If this setting is `None` (the default), WireCloud will use the port info from -incoming requests for building internal URLs. +Set `FORCE_PORT` using a number if you want to force WireCloud to use that port when building internal URLs. -> This setting is mainly useful when WireCloud is behind a web server acting as -> proxy. +If this setting is `None` (the default), WireCloud will use the port info from incoming requests for building internal +URLs. +> This setting is mainly useful when WireCloud is behind a web server acting as proxy. ### FORCE_PROTO -> (String, default: `None`) -Set `FORCE_PROTO` to "http" or to "https" if you want to force WireCloud to use -one of those schemes when building internal URLs. +> (String, default: `None`) -If this setting is `None` (the default), WireCloud will check if the request -comes from a secure connection and, in that case, it will use https as the -scheme for building the internal URLs. In any other case, WireCloud will use -http as the scheme for the internal URLs. +Set `FORCE_PROTO` to "http" or to "https" if you want to force WireCloud to use one of those schemes when building +internal URLs. -> This setting is mainly useful when WireCloud is behind a web server acting as -> proxy. +If this setting is `None` (the default), WireCloud will check if the request comes from a secure connection and, in that +case, it will use https as the scheme for building the internal URLs. In any other case, WireCloud will use http as the +scheme for the internal URLs. +> This setting is mainly useful when WireCloud is behind a web server acting as proxy. ### LANGUAGE_CODE -> (String; default: "en-us") -A string representing the language code to use as fallback when no translation exist for a given literal to the user’s preferred language. For example, U.S. English is "en-us". +> (String; default: "en-us") +A string representing the language code to use as fallback when no translation exist for a given literal to the user’s +preferred language. For example, U.S. English is "en-us". ### LOGGING -> (Dictionary; default: A logging configuration dictionary) -A data structure containing configuration information. The contents of this data -structure will be passed as the argument to the configuration method described -in [LOGGING_CONFIG]. +> (Dictionary; default: A logging configuration dictionary) -Among other things, the default logging configuration passes HTTP 500 server -errors to an email log handler when `DEBUG` is `False`. +A data structure containing configuration information. The contents of this data structure will be passed as the +argument to the configuration method described in [LOGGING_CONFIG]. -You can see the default logging configuration by looking in -wirecloud/commons/utils/conf.py (or view the [online -source](https://github.com/Wirecloud/wirecloud/blob/1.2.x/src/wirecloud/commons/utils/conf.py)). +Among other things, the default logging configuration passes HTTP 500 server errors to an email log handler when `DEBUG` +is `False`. -[LOGGING_CONFIG]: https://docs.djangoproject.com/es/1.11/ref/settings/#logging-config +You can see the default logging configuration by looking in wirecloud/commons/utils/conf.py (or view the +[online source](https://github.com/Wirecloud/wirecloud/blob/1.2.x/src/wirecloud/commons/utils/conf.py)). +[logging_config]: https://docs.djangoproject.com/es/1.11/ref/settings/#logging-config ### SERVER_EMAIL + > (String; default: 'root@localhost') The email address that error messages come from, such as those sent to `ADMINS`. - ### THEME_ACTIVE -> (String, default: "wirecloud.defaulttheme") -A string representing the module that will be use for theming WireCloud. Current -themes shipped with WireCloud are `wirecloud.defaulttheme`, -`wirecloud.fiwaretheme` and `wirecloud.fiwarelabtheme`. You can also use [custom -themes](development/platform/themes). +> (String, default: "wirecloud.defaulttheme") -> **NOTE**: `wirecloud.fiwarelabtheme` was previously (WireCloud 0.8.1-) known as -> `wirecloud.oiltheme`. Although you can still reference it as -> `wirecloud.oiltheme` is recommended to switch to the new name: -> `wirecloud.fiwarelabtheme`. +A string representing the module that will be use for theming WireCloud. Current themes shipped with WireCloud are +`wirecloud.defaulttheme`, `wirecloud.fiwaretheme` and `wirecloud.fiwarelabtheme`. You can also use +[custom themes](development/platform/themes). +> **NOTE**: `wirecloud.fiwarelabtheme` was previously (WireCloud 0.8.1-) known as `wirecloud.oiltheme`. Although you can +> still reference it as `wirecloud.oiltheme` is recommended to switch to the new name: `wirecloud.fiwarelabtheme`. ### URL_MIDDLEWARE_CLASSES + > (Dictionary; default: A middleware configuration dictionary) -A data structure containing the middleware configuration per URL group where the URL group name are the keys of the dictionary and the value should be a tuple of middleware classes to use for that group. +A data structure containing the middleware configuration per URL group where the URL group name are the keys of the +dictionary and the value should be a tuple of middleware classes to use for that group. -You should use this setting as replacement of the Django's MIDDLEWARE_CLASSES setting (See [Django's middleware documentation](https://docs.djangoproject.com/en/1.11/topics/http/middleware/)) +You should use this setting as replacement of the Django's MIDDLEWARE_CLASSES setting (See +[Django's middleware documentation](https://docs.djangoproject.com/en/1.11/topics/http/middleware/)) -Currently available groups are "default", "api" and "proxy". For example, if you want to add a middleware class to the "api" group, you can use the following code: +Currently available groups are "default", "api" and "proxy". For example, if you want to add a middleware class to the +"api" group, you can use the following code: ```python URL_MIDDLEWARE_CLASSES['api'] += ('my.middleware.module.MyMiddlware',) ``` - ### WIRECLOUD_HTTPS_VERIFY -> *new in WireCloud 0.7.0* + +> _new in WireCloud 0.7.0_ > > (Boolean or String, default: `True`) -Set `WIRECLOUD_HTTPS_VERIFY` to `False` if you want WireCloud not validate HTTPS -certificates. If this setting is `True` (the default), WireCloud will verify -https certificates using the CA certificates bundled with python requests or -using the certificates provided by the system (this depends on the procedure -followed for installing the python requests module). You can also provide a path -to a CA bundle file to use instead (e.g. +Set `WIRECLOUD_HTTPS_VERIFY` to `False` if you want WireCloud not validate HTTPS certificates. If this setting is `True` +(the default), WireCloud will verify https certificates using the CA certificates bundled with python requests or using +the certificates provided by the system (this depends on the procedure followed for installing the python requests +module). You can also provide a path to a CA bundle file to use instead (e.g. `WIRECLOUD_HTTPS_VERIFY = "/etc/ssl/certs/ca-certificates.crt"`). - ## Django configuration -The `settings.py` file allows you to set several options in WireCloud. If -`DEBUG` is `False` you will need to collect WireCloud static files using the -following command and answering 'yes' when asked: +The `settings.py` file allows you to set several options in WireCloud. If `DEBUG` is `False` you will need to collect +WireCloud static files using the following command and answering 'yes' when asked: - $ python manage.py collectstatic +```bash +python manage.py collectstatic +``` -In addition, you should serve the static files with a fast performance http -server like [Apache](http://httpd.apache.org/), [Nginx](http://nginx.org/), -[Gunicorn](http://gunicorn.org/), etc. We provide documentation on -[how to serve WireCloud using Apache 2](#running-wirecloud-using-apache-2). -Anyway, if you want to use any of the other http servers (e.g using Gunicorn), -Django provides +In addition, you should serve the static files with a fast performance http server like +[Apache](http://httpd.apache.org/), [Nginx](http://nginx.org/), [Gunicorn](http://gunicorn.org/), etc. We provide +documentation on [how to serve WireCloud using Apache 2](#running-wirecloud-using-apache-2). Anyway, if you want to use +any of the other http servers (e.g using Gunicorn), Django provides [documentation on how to do it](https://docs.djangoproject.com/en/dev/howto/deployment/). -> **NOTE**: Don't forget to rerun the collectstatic command each time the -> WireCloud code is updated, this include each time a WireCloud plugin or Django -> app is enabled/disabled and when the default theme is changed. - +> **NOTE**: Don't forget to rerun the collectstatic command each time the WireCloud code is updated, this include each +> time a WireCloud plugin or Django app is enabled/disabled and when the default theme is changed. ## Advanced configurations ### Installing the WireCloud Pub Sub add-on -The development of the Pub Sub add-on is carried out at they own [github -repository](https://github.com/conwetlab/wirecloud-pubsub). You can always find -the latest information about how to install and use it on the main page of the -repository. +The development of the Pub Sub add-on is carried out at they own +[github repository](https://github.com/conwetlab/wirecloud-pubsub). You can always find the latest information about how +to install and use it on the main page of the repository. Newer versions of the Pub Sub add-on can be installed directly using pip: - $ pip install wirecloud-pubsub +```bash +pip install wirecloud-pubsub +``` -Since wirecloud_pubsub uses `django.contrib.static` functionalities, you should -add it to your `INSTALLED_APPS` in `settings.py`: +Since wirecloud_pubsub uses `django.contrib.static` functionalities, you should add it to your `INSTALLED_APPS` in +`settings.py`: ```python INSTALLED_APPS = ( @@ -816,160 +877,171 @@ DEFAULT_SILBOPS_BROKER = 'http://pubsub.server.com:8080/silbops/CometAPI' Don't forget to run the collectstatic commands on your WireCloud installation: - $ ./manage.py collectstatic - +```bash +./manage.py collectstatic +``` ### NGSI proxy -WireCloud comes with a JavaScript library that allows widgets and operators to -connect to NGSI-9/10 servers. This support works out of the box when installing -WireCloud except for receiving notification directly to widgets and operators. -To enable it WireCloud requires what is called [NGSI proxy], this proxy is a -facade that receives NGSI notifications and passes them to Widgets or Operators. +WireCloud comes with a JavaScript library that allows widgets and operators to connect to NGSI-9/10 servers. This +support works out of the box when installing WireCloud except for receiving notification directly to widgets and +operators. To enable it WireCloud requires what is called [NGSI proxy], this proxy is a facade that receives NGSI +notifications and passes them to Widgets or Operators. -This NGSI proxy doesn't need to be installed in the same machine as WireCloud -and can be shared with other WireCloud instances. Follow this [link][NGSI proxy] -for more information about how to install and configure such a NGSI proxy. - -[NGSI proxy]: https://github.com/conwetlab/ngsi-proxy +This NGSI proxy doesn't need to be installed in the same machine as WireCloud and can be shared with other WireCloud +instances. Follow this [link][ngsi proxy] for more information about how to install and configure such a NGSI proxy. +[ngsi proxy]: https://github.com/conwetlab/ngsi-proxy ### Integration with the IdM GE -The first thing to take into account is that this version of WireCloud is compatible with KeyRock v6 and KeyRock v7. To enable this integration, the first step is creating a new Application using the IdM server that is going to be used (for example: `https://account.lab.fiware.org`). See the [KeyRock's User and Programmers Guide] for more information about how to create such an Application. Redirect URI must be: `http(s)://${wirecloud_server}/complete/fiware/`. Take note of the *Client ID* and the *Client Secret* values (those values are available in the Application details page, inside the *OAuth2 Credentials* section) as they are going to be used later. +The first thing to take into account is that this version of WireCloud is compatible with KeyRock v6 and KeyRock v7. To +enable this integration, the first step is creating a new Application using the IdM server that is going to be used (for +example: `https://account.lab.fiware.org`). See the [KeyRock's User and Programmers Guide] for more information about +how to create such an Application. Redirect URI must be: `http(s)://${wirecloud_server}/complete/fiware/`. Take note of +the _Client ID_ and the _Client Secret_ values (those values are available in the Application details page, inside the +_OAuth2 Credentials_ section) as they are going to be used later. On the WireCloud instance: -1. Install the `social-auth-app-django` module (e.g. `pip install "social-auth-app-django"`) -2. Edit `settings.py`: - - Remove `wirecloud.oauth2provider` from `INSTALLED_APPS` - - Add `social_django` to `INSTALLED_APPS` - - Add `wirecloud.fiware.social_auth_backend.FIWAREOAuth2` to `AUTHENTICATION_BACKENDS`. example: - - ```python - AUTHENTICATION_BACKENDS = ( - 'wirecloud.fiware.social_auth_backend.FIWAREOAuth2', - ) - ``` +- Install the `social-auth-app-django` module (e.g. `pip install "social-auth-app-django"`) +- Edit `settings.py`: + - Remove `wirecloud.oauth2provider` from `INSTALLED_APPS` + - Add `social_django` to `INSTALLED_APPS` + - Add `wirecloud.fiware.social_auth_backend.FIWAREOAuth2` to `AUTHENTICATION_BACKENDS`. example: - > **Note**: Django supports several authentication backends (see this [link](https://docs.djangoproject.com/en/1.11/topics/auth/customizing/#specifying-authentication-backends) for more details). For example, you can continue authenticating users using the local db by also listing `django.contrib.auth.backends.ModelBackend` in `AUTHENTICATION_BACKENDS`, although this will require extra configuration not documented in this guide. +```python +AUTHENTICATION_BACKENDS = ( + 'wirecloud.fiware.social_auth_backend.FIWAREOAuth2', +) +``` - - Add a `FIWARE_IDM_SERVER` setting pointing to the IdM server to use (e.g. `FIWARE_IDM_SERVER = "https://account.lab.fiware.org"`) - - Add `SOCIAL_AUTH_FIWARE_KEY` and `SOCIAL_AUTH_FIWARE_SECRET` settings using the *Client ID* and the *Client Secret* values provided by the IdM. You should end having something like this: +> **Note**: Django supports several authentication backends (see this +> [link](https://docs.djangoproject.com/en/1.11/topics/auth/customizing/#specifying-authentication-backends) for more +> details). For example, you can continue authenticating users using the local db by also listing +> `django.contrib.auth.backends.ModelBackend` in `AUTHENTICATION_BACKENDS`, although this will require extra +> configuration not documented in this guide. - ```python - SOCIAL_AUTH_FIWARE_KEY = "43" - SOCIAL_AUTH_FIWARE_SECRET = "a6ded8771f7438ce430dd93067a328fd282c6df8c6c793fc8225e2cf940f746e6b229158b5e3828e2716b915d2c4762a34219e1792b85e4d3cdf66d70d72840b" - ``` +- Add a `FIWARE_IDM_SERVER` setting pointing to the IdM server to use (e.g. + `FIWARE_IDM_SERVER = "https://account.lab.fiware.org"`) +- Add `SOCIAL_AUTH_FIWARE_KEY` and `SOCIAL_AUTH_FIWARE_SECRET` settings using the _Client ID_ and the _Client Secret_ + values provided by the IdM. You should end having something like this: -3. Edit `urls.py`: - - Replace the login endpoint: - - Add the following import line at the beginning of the file: - `from wirecloud.fiware import views as wc_fiware` - - Remove: - `url(r'^login/?$', django_auth.login, name="login"),` - - Add: - `url(r'^login/?$', wc_fiware.login, name="login"),` - - Add `social-auth-app-django` url endpoints at the end of the pattern list: `url('', include('social_django.urls', namespace='social')),` +```python +SOCIAL_AUTH_FIWARE_KEY = "43" +SOCIAL_AUTH_FIWARE_SECRET = "a6ded8771f7438ce430dd93067a328fd282c6df8c6c793fc8225e2cf940f746e6b229158b5e3828e2716b915d2c4762a34219e1792b85e4d3cdf66d70d72840b" +``` -4. [Optional]: Change the `THEME_ACTIVE` setting to `wirecloud.fiwarelabtheme`. - This theme is the one used by the FIWARE Lab's Mashup portal. -5. [Optional]: Provide a [`FIWARE_PORTALS` setting](#fiware_portals). This - setting is used for signing out from other portals at the same time the user - sign out from WireCloud, providing a single sign out experience. This setting - is also used for building the navigation bar. -6. Run `python manage.py migrate; python manage.py collectstatic --noinput` +- Edit `urls.py`: + - Replace the login endpoint: + - Add the following import line at the beginning of the file: + `from wirecloud.fiware import views as wc_fiware` + - Remove: `url(r'^login/?$', django_auth.login, name="login"),` + - Add: `url(r'^login/?$', wc_fiware.login, name="login"),` + - Add `social-auth-app-django` url endpoints at the end of the pattern list: + `url('', include('social_django.urls', namespace='social')),` -[KeyRock's User and Programmers Guide]: https://fi-ware-idm.readthedocs.org/en/latest/user_guide/#registering-an-application -[`FIWARE_PORTALS` setting]: #fiware_portals +- [Optional]: Change the `THEME_ACTIVE` setting to `wirecloud.fiwarelabtheme`. This theme is the one used by the + FIWARE Lab's Mashup portal. +- [Optional]: Provide a [`FIWARE_PORTALS` setting](#fiware_portals). This setting is used for signing out from other + portals at the same time the user sign out from WireCloud, providing a single sign out experience. This setting is + also used for building the navigation bar. +- Run `python manage.py migrate; python manage.py collectstatic --noinput` +[keyrock's user and programmers guide]: + https://fi-ware-idm.readthedocs.org/en/latest/user_guide/#registering-an-application +[`fiware_portals` setting]: #fiware_portals ### Enabling the real-time synchronization support -WireCloud 1.0 adds experimental support for real time synchronization through -web sockets. +WireCloud 1.0 adds experimental support for real time synchronization through web sockets. The steps for enabling this support are the following: -1. Install [Django channels](https://channels.readthedocs.io/en/latest/): - ``` - $ pip install channels - ``` -2. Add `channels` and `wirecloud.live` into the `INSTALLED_APPS` setting in the - `settings.py` file. -3. Configure the channels framework by configuring the `CHANNEL_LAYERS` setting. - For example, you can make use of the following configuration: - - ```python - CHANNEL_LAYERS = { - "default": { - "BACKEND": "asgiref.inmemory.ChannelLayer", - "ROUTING": "wirecloud.live.routing.channel_routing", - }, - } - ``` - -Once done those steps, you will be able to use WireCloud using the runserver -command. Take into account that is not possible to deploy WireCloud when using -the real-time synchronization support using the standar Apache configuration. -We are working on providing better documentation and examples on how to deploy -WireCloud in this case for a production ready environment, in the meantime, you -can take a look into the [Django channels -documentation](https://channels.readthedocs.io/en/latest/deploying.html). +- Install [Django channels](https://channels.readthedocs.io/en/latest/): + +```bash +pip install channels +``` + +- Add `channels` and `wirecloud.live` into the `INSTALLED_APPS` setting in the `settings.py` file. +- Configure the channels framework by configuring the `CHANNEL_LAYERS` setting. For example, you can make use of the + following configuration: + +```python +CHANNEL_LAYERS = { + "default": { + "BACKEND": "asgiref.inmemory.ChannelLayer", + "ROUTING": "wirecloud.live.routing.channel_routing", + }, +} +``` + +Once done those steps, you will be able to use WireCloud using the runserver command. Take into account that is not +possible to deploy WireCloud when using the real-time synchronization support using the standar Apache configuration. We +are working on providing better documentation and examples on how to deploy WireCloud in this case for a production +ready environment, in the meantime, you can take a look into the +[Django channels documentation](https://channels.readthedocs.io/en/latest/deploying.html). ## Running WireCloud -We recommend running WireCloud based on an Apache Web Server. However, it is -also possible to run it using the Django internal web server, just for testing -purposes. In any case, WireCloud should be configured for being served over -HTTPS, this can be accomplished in severals ways as you can use another server -as frontend and configure the encryption on that server. We recommend you to -visit the [Security/Server Side -TLS](https://wiki.mozilla.org/Security/Server_Side_TLS) page from mozilla for -more information about how to configure efficiently your https security -parameters. +We recommend running WireCloud based on an Apache Web Server. However, it is also possible to run it using the Django +internal web server, just for testing purposes. In any case, WireCloud should be configured for being served over HTTPS, +this can be accomplished in severals ways as you can use another server as frontend and configure the encryption on that +server. We recommend you to visit the [Security/Server Side TLS](https://wiki.mozilla.org/Security/Server_Side_TLS) page +from mozilla for more information about how to configure efficiently your https security parameters. ### Running WireCloud using the Django internal web server -> **NOTE**: Be aware that this way of running WireCloud should be used for evaluation/testing purposes. Do not use it in a production environment. +> **NOTE**: Be aware that this way of running WireCloud should be used for evaluation/testing purposes. Do not use it in +> a production environment. To start WireCloud, type the following command: - $ python manage.py runserver 0.0.0.0:8000 --insecure +```bash +python manage.py runserver 0.0.0.0:8000 --insecure +``` -Then, go to `http://computer_name_or_IP_address:8000/` where computer_name_or_IP_address is the name or IP address of the computer on which WireCloud is installed, and use the username and password you provided when populating the database to sign in on the platform. +Then, go to `http://computer_name_or_IP_address:8000/` where computer_name_or_IP_address is the name or IP address of +the computer on which WireCloud is installed, and use the username and password you provided when populating the +database to sign in on the platform. ### Running WireCloud using Apache 2 -If you choose to deploy WireCloud in Apache, the [mod_wsgi](https://github.com/GrahamDumpleton/mod_wsgi) module must be installed (and so does Apache!). +If you choose to deploy WireCloud in Apache, the [mod_wsgi](https://github.com/GrahamDumpleton/mod_wsgi) module must be +installed (and so does Apache!). #### Installing Apache 2 on Debian/Ubuntu To do so, type the following command on Debian/Ubuntu: - $ sudo apt-get install apache2 libapache2-mod-wsgi +```bash +sudo apt-get install apache2 libapache2-mod-wsgi +``` Once you have installed Apache and mod_wsgi you have to enable the latest: - $ a2enmod wsgi +```bash +a2enmod wsgi +``` -The next step is the creation of a `VirtualHost` for WireCloud using the -Apache's configuration files. On Debian and Ubuntu the configuration files for -the VirtualHosts are stored at `/etc/apache2/sites-available` and enabled and -disabled using `a2enmod` and `a2dissite`. The syntax of the `VirtualHost` -definition depends on the version of Apache 2 of your system, so they are going -to be described in different sections. +The next step is the creation of a `VirtualHost` for WireCloud using the Apache's configuration files. On Debian and +Ubuntu the configuration files for the VirtualHosts are stored at `/etc/apache2/sites-available` and enabled and +disabled using `a2enmod` and `a2dissite`. The syntax of the `VirtualHost` definition depends on the version of Apache 2 +of your system, so they are going to be described in different sections. #### Installing Apache 2 on CentOS/RedHat - $ yum install httpd mod_wsgi +```bash +yum install httpd mod_wsgi +``` #### Apache 2.2 You can use this template as starting point: -```ApacheConf +```xml ... ### Wirecloud ### @@ -1001,17 +1073,17 @@ You can use this template as starting point: ``` -Assuming that your WireCloud instance is available at `/opt/wirecloud_instance` -and you created a `wirecloud` user on the system, then we have the following values: +Assuming that your WireCloud instance is available at `/opt/wirecloud_instance` and you created a `wirecloud` user on +the system, then we have the following values: -- `${path_to_wirecloud_instance}` = `/opt/wirecloud_instance` -- `${wirecloud_instance}` = `wirecloud_instance` -- `${wirecloud_user}` = `wirecloud` -- `${wirecloud_group}` = `wirecloud` +- `${path_to_wirecloud_instance}` = `/opt/wirecloud_instance` +- `${wirecloud_instance}` = `wirecloud_instance` +- `${wirecloud_user}` = `wirecloud` +- `${wirecloud_group}` = `wirecloud` You should end with something similar to: -```ApacheConf +```xml ... ### Wirecloud ### @@ -1045,22 +1117,22 @@ You should end with something similar to: Once you have the site enabled, restart Apache - # apache2ctl graceful +```bash +apache2ctl graceful +``` and go to `http://computer_name_or_IP_address/` to get into WireCloud. -See the [Apache 2.2 documentation about how to configure the TLS -encryption](http://httpd.apache.org/docs/2.2/ssl/ssl_howto.html) and the -[Security/Server Side TLS](https://wiki.mozilla.org/Security/Server_Side_TLS) -page from mozilla for more information about how to configure efficiently your -https security parameters. - +See the +[Apache 2.2 documentation about how to configure the TLS encryption](http://httpd.apache.org/docs/2.2/ssl/ssl_howto.html) +and the [Security/Server Side TLS](https://wiki.mozilla.org/Security/Server_Side_TLS) page from mozilla for more +information about how to configure efficiently your https security parameters. #### Apache 2.4 You can use this template as starting point: -```ApacheConf +```xml ... @@ -1101,17 +1173,17 @@ You can use this template as starting point: ``` -Assuming that your WireCloud instance is available at `/opt/wirecloud_instance` -and you created a `wirecloud` user on the system, then we have the following values: +Assuming that your WireCloud instance is available at `/opt/wirecloud_instance` and you created a `wirecloud` user on +the system, then we have the following values: -- `${path_to_wirecloud_instance}` = `/opt/wirecloud_instance` -- `${wirecloud_instance}` = `wirecloud_instance` -- `${wirecloud_user}` = `wirecloud` -- `${wirecloud_group}` = `wirecloud` +- `${path_to_wirecloud_instance}` = `/opt/wirecloud_instance` +- `${wirecloud_instance}` = `wirecloud_instance` +- `${wirecloud_user}` = `wirecloud` +- `${wirecloud_group}` = `wirecloud` You should end with something similar to: -```ApacheConf +```xml ... @@ -1154,53 +1226,53 @@ You should end with something similar to: Once you have the site enabled, restart Apache - # apache2ctl graceful +```bash +apache2ctl graceful +``` and go to `http://computer_name_or_IP_address/` to get into WireCloud. -See the [Apache 2.4 documentation about how to configure the TLS -encryption](http://httpd.apache.org/docs/2.2/ssl/ssl_howto.html) and the -[Security/Server Side TLS](https://wiki.mozilla.org/Security/Server_Side_TLS) -page from mozilla for more information about how to configure efficiently your -https security parameters. - +See the +[Apache 2.4 documentation about how to configure the TLS encryption](http://httpd.apache.org/docs/2.2/ssl/ssl_howto.html) +and the [Security/Server Side TLS](https://wiki.mozilla.org/Security/Server_Side_TLS) page from mozilla for more +information about how to configure efficiently your https security parameters. ## FAQ ### I'm getting strange errors (e.g. Internal Server Errors). Is there any way to get better info about the problem? -The best option without compromising the security of your server is to provide -the adecuate values for the [`ADMINS`](#admins), -[`SERVER_EMAIL`](#server_email), [`LOGGING`](#logging), ... settings. This way -you will receive a detailed email for each error detected in WireCloud. +The best option without compromising the security of your server is to provide the adecuate values for the +[`ADMINS`](#admins), [`SERVER_EMAIL`](#server_email), [`LOGGING`](#logging), ... settings. This way you will receive a +detailed email for each error detected in WireCloud. -If you don't receive those emails or if you are just creating the instance, you -can set the [`DEBUG` setting](#debug) to `True`, making WireCloud provide a more -verbose and detailed web page when an error occurs. - -> **NOTE**: Remember to restore the `DEBUG` setting to its previous value: -> `False`. +If you don't receive those emails or if you are just creating the instance, you can set the [`DEBUG` setting](#debug) to +`True`, making WireCloud provide a more verbose and detailed web page when an error occurs. +> **NOTE**: Remember to restore the `DEBUG` setting to its previous value: `False`. ### pip has problems installing lxml. What I have to do? See http://lxml.de/installation.html#installation for more detailed info. -For instance, in Debian and Ubuntu you probably have to install the `python-dev`, `libxml2-dev` and `libxslt1-dev` packages: - - $ sudo apt-get install python-dev libxml2-dev libxslt1-dev +For instance, in Debian and Ubuntu you probably have to install the `python-dev`, `libxml2-dev` and `libxslt1-dev` +packages: -In Mac OS, remember to install XCode and its Command Line Tools. If this doesn't work and you use're using the [Homebrew](http://brew.sh/) tools for Mac, you can try the following commands: +```bash +sudo apt-get install python-dev libxml2-dev libxslt1-dev +``` - $ brew install libxml2 - $ pip install lxml +In Mac OS, remember to install XCode and its Command Line Tools. If this doesn't work and you use're using the +[Homebrew](http://brew.sh/) tools for Mac, you can try the following commands: +```bash +brew install libxml2 +pip install lxml +``` ### I don't want to receive Django's invalid HTTP_HOST mails -Django will send mails for any raised `SuspiciousOperation` exception by -default. You can disable those mails by adding the following snipet into your -`settings.py` file: +Django will send mails for any raised `SuspiciousOperation` exception by default. You can disable those mails by adding +the following snipet into your `settings.py` file: ```python LOGGING['loggers']['django.security.DisallowedHost'] = { @@ -1209,51 +1281,59 @@ LOGGING['loggers']['django.security.DisallowedHost'] = { } ``` -This method can be used also for disabling other `SuspiciousOperation` error mails. -See the [Django documentation](https://docs.djangoproject.com/es/1.9/topics/logging/#django-security) -for more info. +This method can be used also for disabling other `SuspiciousOperation` error mails. See the +[Django documentation](https://docs.djangoproject.com/es/1.9/topics/logging/#django-security) for more info. ### I don't remember the admin credentials. How can I recover it? You have two options: -- change the password of your admin user: see `python manage.py help changepassword` -- create a new admin user: see `python manage.py help createsuperuser` - +- change the password of your admin user: see `python manage.py help changepassword` +- create a new admin user: see `python manage.py help createsuperuser` ### I get errors while running the `manage.py` script or when running the `startproject` command If the error is similar to the following one: - Traceback (most recent call last): - File "./manage.py", line 8 in - from django.core.management import execute_from_command_line - ImportError: No module named django.core.management +```text + Traceback (most recent call last): + File "./manage.py", line 8 in + from django.core.management import execute_from_command_line + ImportError: No module named django.core.management +``` check that you python installation is correctly configured (using the python interpreter used for running WireCloud): - $ python - Python 2.7.6 (default, Nov 13 2013, 20:19:29) - [GCC 4.2.1 Compatible Apple LLVM 5.0 (clang-500.2.79)] on darwin - Type "help", "copyright", "credits" or "license" for more information. - >>> import django - >>> django.VERSION - (1, 5, 5, 'final', 0) +```bash +$ python +``` +```text +Python 2.7.6 (default, Nov 13 2013, 20:19:29) +[GCC 4.2.1 Compatible Apple LLVM 5.0 (clang-500.2.79)] on darwin +Type "help", "copyright", "credits" or "license" for more information. +>>> import django +>>> django.VERSION +(1, 5, 5, 'final', 0) +``` ### WireCloud server is giving 503 error responses If you see messages in the apache log file like: - (13)Permission denied: mod_wsgi (pid=26962): Unable to connect to WSGI \ - daemon process '' on '/etc/httpd/logs/wsgi.26957.0.1.sock' \ - after multiple attempts. +```text +(13)Permission denied: mod_wsgi (pid=26962): Unable to connect to WSGI \ +daemon process '' on '/etc/httpd/logs/wsgi.26957.0.1.sock' \ +after multiple attempts. +``` edit `/etc/httpd/conf.d/wsgi.conf` and add the following line: - WSGISocketPrefix /var/run/wsgi - -See the following [link](https://code.google.com/p/modwsgi/wiki/ConfigurationIssues#Location_Of_UNIX_Sockets) for more information about this problem. +```text +WSGISocketPrefix /var/run/wsgi +``` +See the following [link](https://code.google.com/p/modwsgi/wiki/ConfigurationIssues#Location_Of_UNIX_Sockets) for more +information about this problem. ### I get the following error \... @@ -1265,137 +1345,155 @@ Check your python requests module version. Remove `MIDDLEWARE` configuration from your `settings.py` file. - ## Sanity check procedures -The Sanity Check Procedures are the steps that a System Administrator will take -to verify that an installation is ready to be tested. This is therefore a -preliminary set of tests to ensure that obvious or basic malfunctioning is fixed +The Sanity Check Procedures are the steps that a System Administrator will take to verify that an installation is ready +to be tested. This is therefore a preliminary set of tests to ensure that obvious or basic malfunctioning is fixed before proceeding to unit tests, integration tests and user validation. ### End to End testing -Please note that the following information is required before carrying out this -procedure: +Please note that the following information is required before carrying out this procedure: -- computer_name_or_IP_address is the name or IP address of the computer on which - WireCloud has been installed. -- Valid credentials for the WireCloud instance to test (e.g. user: `admin` / - password: `admin`, as stated in the [Database population](#database-population) - section of this guide). +- computer_name_or_IP_address is the name or IP address of the computer on which WireCloud has been installed. +- Valid credentials for the WireCloud instance to test (e.g. user: `admin` / password: `admin`, as stated in the + [Database population](#database-population) section of this guide). The following file: -- [CoNWeT_weather-mashup-example_1.0.2.wgt](attachments/CoNWeT_weather-mashup-example_1.0.2.wgt) +- [CoNWeT_weather-mashup-example_1.0.2.wgt](attachments/CoNWeT_weather-mashup-example_1.0.2.wgt) To quickly check if the application is running, follow these steps: -1. Open a browser and type `http://${computer_name_or_IP_address}/login` in the address bar. -2. The following user login form should appear: +1. Open a browser and type `http://${computer_name_or_IP_address}/login` in the address bar. +2. The following user login form should appear: Login form -3. Enter the credentials and click on the *Log in* button. -4. Click on the *My Resources* button: +3. Enter the credentials and click on the _Log in_ button. +4. Click on the _My Resources_ button: Click *My Resources* -5. Click on the *Upload* button: +5. Click on the _Upload_ button: Click *Upload* -6. Add the `CoNWeT_weather-mashup-example_1.0.2.wgt` file to the upload form and click *Upload*. -7. You should see two widgets (*Web Map Service* and *Weather Widget Example*) and one mashup (*Weather Mashup Example*) components: +6. Add the `CoNWeT_weather-mashup-example_1.0.2.wgt` file to the upload form and click _Upload_. +7. You should see two widgets (_Web Map Service_ and _Weather Widget Example_) and one mashup (_Weather Mashup + Example_) components: - Click *Upload* + Click *Upload* -8. Go back to the editor view: +8. Go back to the editor view: Click *Back* -9. Click on the *New workspace* option: +9. Click on the _New workspace_ option: Click *New workspace* -10. And use the *Weather Mashup Example* as template: +10. And use the _Weather Mashup Example_ as template: Create a new workspace using the *Weather Mashup Example* template -11. The view should automatically change to the *Weather Example Mashup* workspace and widgets should appear in it: +11. The view should automatically change to the _Weather Example Mashup_ workspace and widgets should appear in it: Final weather dashboard -12. Select the pin tool in the *Web Map Service* widget clicking the appropriated button as shown in the image. -13. And click the desired location. The *Weather Widget Example* should update the forecast info: +12. Select the pin tool in the _Web Map Service_ widget clicking the appropriated button as shown in the image. +13. And click the desired location. The _Weather Widget Example_ should update the forecast info: Example usage -By performing this sequence of steps, you will check that the WireCloud Mashup -platform is running and correctly deployed, and its database has been properly -set up and populated. +By performing this sequence of steps, you will check that the WireCloud Mashup platform is running and correctly +deployed, and its database has been properly set up and populated. ### List of Running Processes -We need to check that the Apache web server and the Postgres database are running. WireCloud uses a python interpreter, but it will not be listed as it runs embedded into apache2. If we execute the following command: +We need to check that the Apache web server and the Postgres database are running. WireCloud uses a python interpreter, +but it will not be listed as it runs embedded into apache2. If we execute the following command: - ps -ewF | grep 'apache2\|postgres' | grep -v grep +```bash +ps -ewF | grep 'apache2\|postgres' | grep -v grep +``` It should show something similar to the following: - $ ps -ewF | grep 'apache2\|postgres' | grep -v grep - postgres 1631 1 0 25212 9452 0 Jul03 ? 00:00:19 /usr/lib/postgresql/9.1/bin/postgres -D /var/lib/postgresql/9.1/main -c config_file=/etc/postgresql/9.1/main/postgresql.conf - postgres 1702 1631 0 25208 3784 0 Jul03 ? 00:00:47 postgres: writer process - postgres 1703 1631 0 25208 1452 0 Jul03 ? 00:00:39 postgres: wal writer process - postgres 1704 1631 0 25462 2964 0 Jul03 ? 00:00:16 postgres: autovacuum launcher process - postgres 1705 1631 0 17370 1660 0 Jul03 ? 00:00:18 postgres: stats collector process - root 3811 1 0 50067 10848 0 13:13 ? 00:00:00 /usr/sbin/apache2 -k start - www-data 3818 3811 0 68663 39820 0 13:13 ? 00:00:00 /usr/sbin/apache2 -k start - www-data 3819 3811 0 68687 39448 0 13:13 ? 00:00:00 /usr/sbin/apache2 -k start - www-data 3822 3811 0 68901 40160 0 13:13 ? 00:00:00 /usr/sbin/apache2 -k start +```bash +ps -ewF | grep 'apache2\|postgres' | grep -v grep +``` +```text +postgres 1631 1 0 25212 9452 0 Jul03 ? 00:00:19 /usr/lib/postgresql/9.1/bin/postgres -D /var/lib/postgresql/9.1/main -c config_file=/etc/postgresql/9.1/main/postgresql.conf +postgres 1702 1631 0 25208 3784 0 Jul03 ? 00:00:47 postgres: writer process +postgres 1703 1631 0 25208 1452 0 Jul03 ? 00:00:39 postgres: wal writer process +postgres 1704 1631 0 25462 2964 0 Jul03 ? 00:00:16 postgres: autovacuum launcher process +postgres 1705 1631 0 17370 1660 0 Jul03 ? 00:00:18 postgres: stats collector process +root 3811 1 0 50067 10848 0 13:13 ? 00:00:00 /usr/sbin/apache2 -k start +www-data 3818 3811 0 68663 39820 0 13:13 ? 00:00:00 /usr/sbin/apache2 -k start +www-data 3819 3811 0 68687 39448 0 13:13 ? 00:00:00 /usr/sbin/apache2 -k start +www-data 3822 3811 0 68901 40160 0 13:13 ? 00:00:00 /usr/sbin/apache2 -k start +``` ### Network interfaces Up & Open To check the ports in use and listening, execute the command: - $ sudo netstat -ltp +```bash +sudo netstat -ltp +``` The expected results must be something similar to the following: - Active Internet connections (only servers) - Proto Recv-Q Send-Q Local Address Foreign Address State PID/Program name - tcp 0 0 localhost:postgresql *:* LISTEN 1631/postgres - tcp 0 0 *:https *:* LISTEN 3811/apache2 +```text +Active Internet connections (only servers) +Proto Recv-Q Send-Q Local Address Foreign Address State PID/Program name +tcp 0 0 localhost:postgresql *:* LISTEN 1631/postgres +tcp 0 0 *:https *:* LISTEN 3811/apache2 +``` or these ones in case the machine is configured to use IPv6: - Active Internet connections (only servers) - Proto Recv-Q Send-Q Local Address Foreign Address State PID/Program name - tcp 0 0 localhost:postgresql *:* LISTEN 1631/postgres - tcp6 0 0 [::]:https [::]:* LISTEN 3811/apache2 - +```text +Active Internet connections (only servers) +Proto Recv-Q Send-Q Local Address Foreign Address State PID/Program name +tcp 0 0 localhost:postgresql *:* LISTEN 1631/postgres +tcp6 0 0 [::]:https [::]:* LISTEN 3811/apache2 +``` ### Databases -The last step in the sanity check, once that we have identified the processes and ports, is to check the different databases that have to be up and accepting queries. If we execute the following command: +The last step in the sanity check, once that we have identified the processes and ports, is to check the different +databases that have to be up and accepting queries. If we execute the following command: - $ psql -U wc_user wirecloud +```bash +psql -U wc_user wirecloud +``` It should show a message text similar to the following: - psql (9.1.4) - Type "help" for help. - - wirecloud=> +```text +psql (9.1.4) +Type "help" for help. +wirecloud=> +``` ## Diagnosis Procedures -The Diagnosis Procedures are the first steps that a System Administrator will take to locate the source of an error in a GE. Once the nature of the error is identified with these tests, the system admin will very often have to resort to more concrete and specific testing to pinpoint the exact point of error and a possible solution. Such specific testing is out of the scope of this section. +The Diagnosis Procedures are the first steps that a System Administrator will take to locate the source of an error in a +GE. Once the nature of the error is identified with these tests, the system admin will very often have to resort to more +concrete and specific testing to pinpoint the exact point of error and a possible solution. Such specific testing is out +of the scope of this section. ### Resource availability -WireCloud runs fine with a minimun of 512 MB of available RAM (1024 MB recommended) and 10 GB of hard disk space. Nevertheless memory usage strongly depends on the number of concurrent users. According to normal usage patterns taken from the log history, memory usage exceeding 256 MB per user are to be considered abnormally high. WireCloud is not CPU-intensive and thus CPU usages over 5% per user is considered abnormal. WireCloud is I/O-intensive and performances below 12 http requests per second are considered abnormal. +WireCloud runs fine with a minimun of 512 MB of available RAM (1024 MB recommended) and 10 GB of hard disk space. +Nevertheless memory usage strongly depends on the number of concurrent users. According to normal usage patterns taken +from the log history, memory usage exceeding 256 MB per user are to be considered abnormally high. WireCloud is not +CPU-intensive and thus CPU usages over 5% per user is considered abnormal. WireCloud is I/O-intensive and performances +below 12 http requests per second are considered abnormal. The results from monitoring the FIWARE Lab Mashup portal usage shows that the aforementioned ranges remains valid. @@ -1403,8 +1501,8 @@ The results from monitoring the FIWARE Lab Mashup portal usage shows that the af Resource consumption strongly depends on the load, especially on the number of concurrent users logged in. -- The main memory consumption of the Apache Web server should be between 64 MB and 1024 MB. -- Postgresql should consume a small amount of memory, not more than 64 MB. +- The main memory consumption of the Apache Web server should be between 64 MB and 1024 MB. +- Postgresql should consume a small amount of memory, not more than 64 MB. ### I/O flows diff --git a/docs/restapi/index.md b/docs/restapi/index.md index 1fa8104999..c23dd2ecd0 100644 --- a/docs/restapi/index.md +++ b/docs/restapi/index.md @@ -1,8 +1,5 @@ -The Application Mashup API is a RESTful, resource-oriented API accessed via HTTP -that uses various representations for information interchange. This API provides -the functionality to create and modify workspaces and the functionality to -manage the resources available at the Application Mashup server for building -these workspaces. +The Application Mashup API is a RESTful, resource-oriented API accessed via HTTP that uses various representations for +information interchange. This API provides the functionality to create and modify workspaces and the functionality to +manage the resources available at the Application Mashup server for building these workspaces. -You can read documentation about this API on -[APIary](http://docs.fiwareapplicationmashup.apiary.io/#). +You can read documentation about this API on [APIary](http://docs.fiwareapplicationmashup.apiary.io/#). diff --git a/docs/user_guide.md b/docs/user_guide.md index 033c5de4b4..47e458fa34 100644 --- a/docs/user_guide.md +++ b/docs/user_guide.md @@ -1,196 +1,160 @@ -Supported browsers ------------------- +## Supported browsers WireCloud 1.2 supports the following desktop browsers: -- Firefox 45+ -- Chrome 52+ -- Safari 10+ -- Opera 39+ +- Firefox 45+ +- Chrome 52+ +- Safari 10+ +- Opera 39+ -WireCloud 1.2 also works on the mobile version of the previous browsers, except -the wiring editor currently does not work with touch screens. +WireCloud 1.2 also works on the mobile version of the previous browsers, except the wiring editor currently does not +work with touch screens. -> **Note:** Although WireCloud supports those browsers, some widgets and operators -> may not support all of them. Read each widget and operators documentation for -> knowing if they have any restriction on the used browser. +> **Note:** Although WireCloud supports those browsers, some widgets and operators may not support all of them. Read +> each widget and operators documentation for knowing if they have any restriction on the used browser. -Creating a new workspace ------------------------- +## Creating a new workspace -Mashups in WireCloud are built in the context of **workspaces**. A -workspace consists of the set of widgets and operators that can be -mashed-up, even spanning multiple tabs. Widgets and operators in a -workspace can share data though data flow- or event-based mechanisms. +Mashups in WireCloud are built in the context of **workspaces**. A workspace consists of the set of widgets and +operators that can be mashed-up, even spanning multiple tabs. Widgets and operators in a workspace can share data though +data flow- or event-based mechanisms. -The workspace in use is shown in the upper area of the screen. It -resembles the well-known REST nomenclature. For example, the following -screenshot shows a workspace named "Workspace", pertaining the user -"admin" and running in the FIWARE Lab’s instance of WireCloud, i.e. it -is named admin/Workspace. +The workspace in use is shown in the upper area of the screen. It resembles the well-known REST nomenclature. For +example, the following screenshot shows a workspace named "Workspace", pertaining the user "admin" and running in the +FIWARE Lab’s instance of WireCloud, i.e. it is named admin/Workspace. Empty workspace -Near the workspace name there is a button which you can click on to -expand the workspace dropdown menu: +Near the workspace name there is a button that you can click on to expand the workspace dropdown menu: Workspace menu -Once expanded, the menu shows a list of the already created workspaces -(see *Workspace*, *My Multimedia Workspace* and *IssueTrouble* in the -figure above) which allows you to quickly switch between them, followed -by a list of options: +Once expanded, the menu shows a list of the already created workspaces (see _Workspace_, _My Multimedia Workspace_ and +_IssueTrouble_ in the figure above) that allows you to quickly switch between them, followed by a list of options: - **New workspace** creates a new workspace - **Rename** changes the name of the current workspace - **Share** shows the sharing configuration of the current workspace -- **Upload to my resources** allows you to save the current - workspace to the local catalogue for later usage -- **Embed** shows information about how to embed the current workspace in other - web pages +- **Upload to my resources** allows you to save the current workspace to the local catalogue for later usage +- **Embed** shows info about how to embed current workspace in other web pages - **Settings** changes the settings of the current workspace - **Remove** deletes the current workspace -If you want to create a new workspace named "History Info", choose *New -workspace* in the dropdown menu: +If you want to create a new workspace named "History Info", choose _New workspace_ in the dropdown menu: Click *New workspace* -A dialog will pop up requiring a name for the new workspace. Type the -desired name and click the accept button: +A dialog will pop up requiring a name for the new workspace. Type the desired name and click the accept button: Dialog for creating a new workspace -Once accepted, the name of the new workspace is shown in the upper area of -the window: +Once accepted, the name of the new workspace is shown in the upper area of the window: -History Info + -The following screenshot shows the "Settings" menu, where you can set -workspace features: +The following screenshot show the "Settings" menu, where you can set workspace features: create_workspace/WorkspaceSettings.png +## Browsing the Marketplace -Browsing the Marketplace ------------------------- +A mashup tool like WireCloud must support access to **marketplaces**, where people can offer and deal with services made +accessible through widgets and operators, like goods, and finally mashup them to create value added services and +applications. -A mashup tool like WireCloud must support access to **marketplaces**, where -people can offer and deal with services made accessible through widgets and -operators, like goods, and finally mash them up to create value added services -and applications. +On the marketplace you can quickly find and compare widgets and operators, which enable you to attend an +industry-ecosystem better than before. Widgets, operators, and even pre-built mashups become tradable goods, which can +be offered and acquired on Internet based marketplaces. Partner companies and other users can combine existing services +to new services whereby new business models will be incurred and the value added chain is extended. -On the marketplace you can quickly find and compare widgets and operators, -which enable you to attend an industry-ecosystem better than before. Widgets, -operators, and even pre-built mashups become tradable goods, which can be -offered and acquired on Internet based marketplaces. Partner companies and -other users can combine existing services to new services whereby new business -models will be incurred and the value added chain is extended. - -The following figure shows a screenshot of WireCloud where you can see -the FIWARE Lab marketplace. +The following figure shows a screenshot of WireCloud where you can see the FIWARE Lab marketplace. Initial marketplace view - ### Managing marketplaces -When looking for an offer of widgets, operators and mashups, you first need to -choose a marketplace. Use the dropdown menu shown in the workspace path for this -purpose. +When looking for an offer of widgets, operators and mashups, you first need to choose a marketplace. Use the dropdown +menu shown in the workspace path for this purpose. Marketplace dropdown -As shown in the previous screenshot, this menu allows you to choose among the -different marketplaces you have access to. To add a new marketplace, you only -need to provide its endpoint (URL). You can also delete the current markeplace -through the *Delete Marketplace* option in the context menu. +As shown in the previous screenshot, this menu allows you to choose among the different marketplaces you have access to. +To add a new marketplace, you only need to provide its endpoint (URL). You can also delete the current markeplace +through the _Delete Marketplace_ option in the context menu. -You can add the FIWARE Lab marketplace using the *Add new marketplace* option -as shown in the following screenshots: +You can add the FIWARE Lab marketplace using the _Add new marketplace_ option as shown in the following screenshots: Click *Add new marketplace* *Add new marketplace* dialog -WireCloud offers a built-in local catalogue called *My Resources*, which allows -you to search among the widgets, operators and mashups currently available to -the user. The following figure shows a screenshot of the *My Resources* for a -user in a given instance of WireCloud. +WireCloud offers a built-in local catalogue called _My Resources_, which allows you to search among the widgets, +operators and mashups currently available for the user. The following figure shows a screenshot of the _My Resources_ +for a user in a given instance of WireCloud. *My Resources* view -If you are a widget developer with brand new widgets to share, or you just have -downloaded a WireCloud-compliant widget from somewhere, you can easily upload -your new widgets to the built-in local catalogue through the *Upload* button -available on the *My Resources* view. +If you are a widget developer with brand new widgets to share, or you just have downloaded a WireCloud-compliant widget +from anywhere, you can easily upload your new widgets to the built-in local catalogue through the _Upload_ button +available on the _My Resources_ view. Click *Upload* MAC upload dialog +## Building a new mashup -Building a new mashup ---------------------- - -If you followed the instructions documented in the "[Creating a new -workspace](#creating-a-new-workspace)" section, you should -have a "History Info" workspace. Let's assume that we start from this -point: +If you followed the instructions documented in the "[Creating a new workspace](#creating-a-new-workspace)" section, you +should have a "History Info" workspace. Let's assume that we start from this point: Starting point -Then go to the Marketplace to choose among the available components in the -catalogue those you want to use in your mashup: +Go then to the Marketplace to choose among the components available in the catalogue those you want to use in your +mashup: Button for searching more components -To ensure that you find the required widgets/operators for this example -mashup, go to the FIWARE Lab marketplace and install them using the -[*WireCloudUserGuide* offering](https://store.lab.fiware.org/#/offering/458). -You can also download them using the following URLs: +To ensure that you find the required widgets/operators for this example mashup, go to the FIWARE Lab marketplace and +install them using the [_WireCloudUserGuide_ offering](https://store.lab.fiware.org/#/offering/458). You can also +download them using the following URLs: - [CoNWeT_simple-history-module2linear-graph_2.3.2.wgt](attachments/CoNWeT_simple-history-module2linear-graph_2.3.2.wgt) - [CoNWeT_ngsi-source_3.0.7.wgt](attachments/CoNWeT_ngsi-source_3.0.7.wgt) - [CoNWeT_ngsientity2poi_3.0.3.wgt](attachments/CoNWeT_ngsientity2poi_3.0.3.wgt) -- [CoNWeT_map-viewer_2.6.2.wgt](attachments/CoNWeT_map-viewer_2.6.2.wgt) +- [CoNWeT_map-viewer_2.5.8.wgt](attachments/CoNWeT_map-viewer_2.5.8.wgt) - [CoNWeT_linear-graph_3.0.0b3.wgt](attachments/CoNWeT_linear-graph_3.0.0b3.wgt) -Once installed, you should be able to see all the widgets/operators used -in this example in the *My Resources* view: +Once installed, you should be able to see all the widgets/operators used in this example in the _My Resources_ view: List of used components -Go to the editor view and click on the *Add components* button: +Go to the editor view and click on the _Add components_ button: Click *Add conponents* -Look for the *Linear Graph* widget and click on the *Add to workspace* -button: +Look for the _Linear Graph_ widget and click on the _Add to workspace_ button: Click *Add to workspace* -This will add the *Linear Graph* widget into the dashboard, which you can move -and resize until you obtain the desired layout: +This will add the _Linear Graph_ widget into the dashboard, you can move and resize it until you obtain the desired +layout: Initial *Linear Graph* layout -Add the *Map Viewer* widget to the dashboard following the same steps -for adding the *Linear Graph* widget. After rearranging it you will be -presented with the following view, which shows you the two widgets in -the default tab. You can see the tabs used in your workspace at the -footer bar, and you can create new tabs to better organize the +Add the _Map Viewer_ widget to the dashboard following the same steps for adding the _Linear Graph_ widget. After +rearranging it you will be presented with the following view, which shows you the two widgets in the default tab. You +can see the tabs used in your workspace at the footer bar, and you can create new tabs to better organize the distribution of the widgets in your mashup. Final layout ### Changing the settings of a widget -Once you have added the desired widgets to your mashup and you have -placed and resized them to configure the information dashboard of your -choice, you can change their settings. To do so, go to the upper-right -corner of the widget and click the properties icon as shown in the -following screenshot: +Once you have added the desired widgets to your mashup and you have placed and resized them to configure the information +dashboard of your choice, you can change their settings. To do so, go to the upper-right corner of the widget and click +the properties icon as shown in the following screenshot: Widget *Menu* button @@ -198,106 +162,75 @@ You will then be presented with a dropdown menu with several options. Widget menu dropdown -- **Rename** changes the widget name shown in workspace editor and - wiring Editor views +- **Rename** changes the widget name shown in workspace editor and wiring Editor views - **Reload** reloads the widget - **Upgrade/Downgrade** allows you to change the version of the widget - **Logs** shows a dialog with the log history of the widget -- **Settings** shows a form for changing the settings of the current - widget +- **Settings** shows a form for changing the settings of the current widget - **User's Manual** will open the widget documentation -- **Full Dragboard** maximises the selected widget, so it will take up - the full canvas area. This option becomes **Exit Full Dragboard** if - the widget is already on "Full Dragboard" mode. In that case, this - option will restore the size of the widget to the one it had before - maximising it -- **Extract from grid** lifts up the widget from the canvas, allowing - you to place it wherever you want on the canvas, even on top of - other widgets. This option becomes **Snap to grid** if the widget is - currently outside the grid, in this case, this option docks the - widget into the grid. - -Finally, click on the **Settings** and you will be prompted with a -customised dialog for the settings of the widget. In this example, the -*Map Viewer* should be provided with initial location, zoom level and -mark shadow radius to customise the visualisation. +- **Full Dragboard** maximises the selected widget, so it will take up the full canvas area. This option becomes + **Exit Full Dragboard** if the widget is already on "Full Dragboard" mode. In that case, this option will restore + the size of the widget to the one it had before maximising it +- **Extract from grid** lifts up the widget from the canvas, allowing you to place it wherever you want on the canvas, + even on top of other widgets. This option becomes **Snap to grid** if the widget is currently outside the grid, in + this case, this option docks the widget into the grid. -*Map Viewer* Settings +Finally, click on the **Settings** and you will be prompted with a customised dialog for the settings of the widget. In +this example, the _Map Viewer_ should be provided with initial location, zoom level and mark shadow radius to customise +the visualisation. -> Note that you need to provide an API key to be able to use the widget -> correctly. You can get this from http://console.cloud.google.com/. -> For all features you need to activate the following APIs: -> - Maps JavaScript API -> - Maps Geocoding API -> See also the following documentation -> https://developers.google.com/maps/documentation/javascript/get-api-key. +*Map Viewer* Settings -As we have configured the initial position and the initial zoom, we need to -reload the widget. To do so, we click again on the properties icon and then on -the *Reload* option: +As we have configure the initial position and the initial zoom, we need to reload the widget. To do so, we click again +on the properties icon and then on the _Reload_ option: Reload option -Now we have our widget centered in the new location, Santander, using the -configured initial zoom level. +Now we have our widget centered in the new location, Santander, and using the configured initial zoom level. MapViewer widget after being configured -At this time, you have created a mashup with two individual widgets. The -*Linear Graph* widget is empty and needs to be wired with something that -provides information to draw, and the *Map Viewer* is a good option to -show any kind of "Points of Interest" and to allow the user to select them -easily. +At this time, you have created a mashup with two individual widgets. The _Linear Graph_ widget is empty and need to be +wired with something that provides information to draw, and the _Map Viewer_ is a good option to show any kind of +"Points of Interest" and allow the user to select them easily. Mashup with the map viewer configured ### Wiring widgets and operators -Once you have chosen the desired widgets, you can wire them to enable -their intercommunication and to achieve coordinated behaviour. Widgets -and operators in WireCloud, are capable of sending and/or receiving -events and data through well-identified ports called endpoints. When you -connect two compatible endpoints, the second one (i.e. the input or -target endpoint) prepares to receive data flows and/or events coming -from the first one (i.e. the output or source endpoint). +Once you have chosen the desired widgets, you can wire them to enable their intercommunication and to achieve +coordinated behaviour. Widgets and operators in WireCloud, are capable of sending and/or receiving events and data +through well-identified ports called endpoints. When you connect two compatible endpoints, the second one (i.e. the +input or target endpoint) prepares to receive data flows and/or events coming from the first one (i.e. the output or +source endpoint). #### Basic wiring concepts -To wire the widgets and add operators to your mashup go to the Wiring -view of the tool: +To wire the widgets and add operators to your mashup go to the Wiring view of the tool: Click *Wiring* -You will then be presented with an empty wiring configuration (denoted by an -empty canvas displaying a welcome message): +You will then be presented with an empty wiring configuration (denoted by an empty canvas displaying a welcome message): Emtpy wiring -One of the most important characteristics that should be intrinsic to -the design of widgets is that they must be as generic as possible. For -example, it makes much more sense to have a generic *Map Viewer* widget -that can be wired through an operator to any source of information of -your choice, than to have a specific one that has hard-coded the data source. -Operators represent the means to achieve this generality, -because they represent the means to dynamically associate the widgets -with the concrete services or sources of information you want to use in -the context of a particular mashup. +One of the most important characteristics that should be intrinsic to the design of widgets is that they must be as +generic as possible. For example, it makes much more sense to have a generic _Map Viewer_ widget that can be wired +through an operator to any source of information of your choice, than to have an specific one that has hard-coded the +source of data. Operators represents the means to achieve this generality, because they represents the means to +dynamically associate the widgets with the concrete services or sources of information you want to use in the context of +a particular mashup. -In this case, we have an *NGSI source* operator that is going to -provide the data information to the *Map Viewer* widget. This kind of -operator is called piping operator. So we have to add it to the -wiring. +In this case, we have an _NGSI source_ operator that is going to provide the data information to the _Map Viewer_ +widget. This kind of operators are called piping operators. So we have to add it to the wiring. -To do so, open the components side panel and search the *NGSI source* operator, -then click on the *Create* button: +To do so, open the components side panel and search the _NGSI source_ operator, then click on the _Create_ button: Click *Create* -This will create an instance of that operator and will appear in the bottom of -the box associated with the *NGSI Source* operator. You can see that it is -highlighted indicating that the new operator is not used in the wiring -configuration. All operators not used when leaving the wiring editor will be -removed from the wiring configuration. +This will create an instance of that operator and will appear in the bottom of the box associated with the _NGSI Source_ +operator. You can see that it is highlighted indicating that the new operator is not used in the wiring configuration. +All operators not used when leaving the wiring editor will be removed from the wiring configuration. Now drag the operator from the operator list to the wiring canvas: @@ -307,113 +240,99 @@ Now drag the operator from the operator list to the wiring canvas: *NGSI Source* added to the wiring canvas -Once added, we need to configure it so it knows what info to retrieve from the -[Orion Context Broker] and from what instance. To do so, click on the -**Settings** menu entry: +Once added, we need to configure it so it knows what info to retrieve from the [Orion Context Broker] and from what +instance. To do so, click on the **Settings** menu entry: NGSI Source Settings option And make sure the following configuration is used: -- **NGSI server URL**: `http://orion.lab.fiware.org:1026/` -- **NGSI proxy URL**: `https://ngsiproxy.lab.fiware.org` -- **Use the FIWARE credentials of the user**: Enabled -- **Use the FIWARE credentials of the workspace owner**: Disabled -- **NGSI tenant/service:** Empty -- **NGSI scope:** `/` -- **NGSI entity types**: `Node, AMMS, Regulator` -- **Id pattern**: Empty -- **Monitored NGSI attributes**: `Latitud, Longitud, presence, batteryCharge, illuminance, ActivePower, ReactivePower, electricPotential, electricalCurrent` - -Now, the source of information that is going to be presented in the -*Map Viewer* widget is ready. So, the next step is adding the *Map Viewer* -widget to the wiring canvas, this way we will be able to connect them. This is -accomplished in the same way we did with the *NGSI Source* operator, but using -the *Widget* tab in the sidebar: +- **NGSI server URL**: `http://orion.lab.fiware.org:1026/` +- **NGSI proxy URL**: `https://ngsiproxy.lab.fiware.org` +- **Use the FIWARE credentials of the user**: Enabled +- **Use the FIWARE credentials of the workspace owner**: Disabled +- **NGSI tenant/service:** Emtpy +- **NGSI scope:** `/` +- **NGSI entity types**: `Node, AMMS, Regulator` +- **Id pattern**: Empty +- **Monitored NGSI attributes**: + `Latitud, Longitud, presence, batteryCharge, illuminance, ActivePower, ReactivePower, electricPotential, electricalCurrent` + +Now, we have ready the source of information that is going to be presented in the _Map Viewer_ widget. So, the next step +is adding the _Map Viewer_ widget to the wiring canvas, this way we will be able to connect them. This is accomplished +in the same way we did with the _NGSI Source_ operator, but using the _Widget_ tab in the sidebar: wiring/Wiring_NGSISource_MapViewer.png -> **NOTE**: We have created the instance of the *Map Viewer* widget in the -> editor view, but you can also create widget instances from the wiring editor -> using the *Create* button: +> **NOTE**: We have created the instance of the _Map Viewer_ widget in the editor view, but you can also create widget +> instances from the wiring editor using the _Create_ button: > > *Create* button > > Remember to resize and place the new widget after exiting the wiring editor. -After adding the *Map Viewer* widget into the wiring canvas, you should have -something similiar to this: +After adding the _Map Viewer_ widget into the wiring canvas, you should have something similiar to this: Wiring diagram after adding the *Map Viewer* widget -The wiring editor comes with a recommendation system for connections. -For example, move the pointer to the *Provide entity* endpoint. You will -see that the endpoint getd highlighted, this means that the recommendation -system is searching for compatible endpoints. In this case there are no -compatible endpoints. +The wiring editor comes with a recommendation system for connections. For example, move the pointer to the _Provide +entity_ endpoint. You will see that the endpoint get highlighted, this means that the recommendation system is searching +for compatible endpoints. In this case there are no compatible endpoints. Missing connection recommendations -This is because the output of the *NGSI source* cannot be connected directly -to the *Map Viewer* widget. We can use a transform operator to convert the -event data provided by the *NGSI source* operator to the format used by the *Map -Viewer* widget. In this example, the operator that is going to perform this -transformation is called *NGSI Entity to PoI*: +This is because the output of the _NGSI source_ cannot be connected directly with the _Map Viewer_ widget. We can use a +transform operator to convert the event data provided by the _NGSI source_ operator to the format used by the _Map +Viewer_ widget. In this example, the operator that is going to perform this transformation is called _NGSI Entity to +PoI_: Wiring diagram after adding the *NGSI Entity to PoI* operator -After adding the operator, we can move the pointer to the *Provide -entity* endpoint to see that now we have a connection recommendation: +After adding the operator, we can move the pointer to the _Provide entity_ endpoint to see that now we have a connection +recommendation: Connection recommendation over the *Provide entity* endpoint -So, we can connect it. To do so, push down the mouse button on the -*Provide entity* endpoint and drag the arrow to the *Entity* endpoint: +So, we can connect it. To do so, push down the mouse button on the _Provide entity_ endpoint and drag the arrow to the +_Entity_ endpoint: Dragging a connection Created connection -We also have to connect the *PoI* endpoint of the *NGSI Entity To PoI* operator -to the *Insert/Update PoI* endpoint on the *Map Viewer* widget: +We have to connect also the _PoI_ endpoint of the _NGSI Entity To PoI_ operator to the _Insert/Update PoI_ endpoint on +the _Map Viewer_ widget: Wiring diagram after connecting the *NGSI entity To PoI* operator and the *Map Viewer* widget -Once again, we need to configure the *NGSI Entity To PoI* operator. This is done -in the same way as we have done with the *NGSI Source*. In this case the values -should be: +Once again, we need to configure the _NGSI Entity To PoI_ operator, this is done in the same way as we have done with +the _NGSI Source_. In this case the values should be: -- **Coordinates attribute**: `Latitud, Longitud` -- **Marker Icon**: Empty +- **Coordinates attribute**: `Latitud, Longitud` +- **Marker Icon**: Empty -If you return to the *Editor* view, you will see that the map widget has -been updated and is showing the PoIs obtained from the *NGSI source* -operator. +If you return to the _Editor_ view, you will see that the map widget has been updated and is showing the PoIs obtained +from the _NGSI source_ operator. Map Viewer widget displaying shome PoIs -You can use the *Map Viewer* and moving its viewport, selecting PoI's, etc. -But really, what we have is not just the *Map Viewer* widget connected to -a source of data, but using piping and transformation operators which -gives us great flexibility. +You can use the _Map Viewer_ moving the viewport, selecting PoI's, etc. But in really, what we have is just the _Map +Viewer_ widget connected to a source of data, but using piping and transformation operators that is going to give us a +great flexibility. Map Viewer widget displaying the details of an entity - -[Orion Context Broker]: http://catalogue.fiware.org/enablers/publishsubscribe-context-broker-orion-context-broker - +[orion context broker]: http://catalogue.fiware.org/enablers/publishsubscribe-context-broker-orion-context-broker #### Other wiring common tasks -One of the most common operations is the task of removing the connections -in the wiring. For example, when you make some mistake for some -reason, you can fix it by clicking the *Remove* button that appears in the -middle a of the connection: +One of the most common operations is the task of getting the connections removed in the wiring. For example, when you +make some mistake for some reason, you can fix it by clicking the _Remove_ button that appears in the middle a of the +connection: *Remove* button -Sometimes what you want is to modify one of the connections. The Wiring Editor -allows you to do this operation without having to remove the connection and -having to create a new one. To do so, you only have to select the connection and +Sometimes what you want is to modify one of the connections. The Wiring Editor allows you to do this operation without +having to remove the connection and having to create a new one. To do so, you only have to select the connection and drag the connection from the endpoint you want to modify: How to modify a connection @@ -421,35 +340,31 @@ drag the connection from the endpoint you want to modify: Connection once modified Connection once modified -Another common task is to change the shape of connections. To do so, you have to -click on the *Customize* option of the connection: +Another common task is to change the shape of connections. To do so, you have to click on the _Customize_ option of the +connection: *Customize* option -Once enabled, you only have to move the handles that appear to modify the shape -of the connection. +Once enabled, you only have to move the handles that appear to modify the shape of the connection. wiring/reshape_arrow1.png wiring/reshape_arrow2.png -If you want to stop customising the connection, click outside the connection or -use the *Stop Customizing* option: +If you want to stop customising the connection, click outside the connection or use the _Stop Customizing_ option: *Stop Customizing* option -You can also minimize operators with the intention of improving space -usage. This can be accomplished using the *Collapse* option that appears -in the component menu: +You can also minimize operators with the intention of improving space usage. This can be accomplished using the +_Collapse_ option that appears in the component menu: *Collapse* option Collapsed operators -#### Concluding our example +#### Cloncluding our example -Continue wiring the rest of the widgets in your mashup following your -intuition, the documentation and the contextual help offered by each -widget/operator. Finally, you should get to a final result similar to -the one in the following screenshot: +Continue wiring the rest of the widgets in your mashup following your intuition, the documentation and the contextual +help offered by each widget/operator. Anyway, just in case you have difficulties, you can see the final result in the +following screenshot: Final wiring configuration @@ -461,71 +376,57 @@ Now you can play with your new workspace. Final mashup linear graph with zoom -Behaviour Oriented Wiring -------------------------- +## Behaviour Oriented Wiring -Starting with WireCloud 0.8.0, you can create wiring configurations by means of -composing several *behaviours*. +Starting at WireCloud 0.8.0, you can create wiring configurations by means of compositing several _behaviours_. -A *behaviour* is a set of joined components with the connections established -between them for adding a feature or behaviour to the application mashup. For -example, we can split the wiring configuration used by the dashboard created on +A _behaviour_ is a set of components jointly with the connections established between them for adding a feature or +behaviour to the application mashup. For example, we can split the wiring configuration used by the dashboard created on the previous section into two behaviours: -- The first one can be called: **Show lampposts on map**. This behaviour is - composed of the `NGSI Source`, `NGSI Entity To PoI` and `Map Viewer` components - as well as the connections between those components: +- The first one can be called: **Show lampposts on map**. This behaviour is composed of the `NGSI Source`, + `NGSI Entity To PoI` and `Map Viewer` components as well as the connections between those components: - *Show lampposts on map* behaviour (Santander example) + *Show lampposts on map* behaviour (Santander example) -- The second one can be called: **Show lamppost details**. This behaviour is - composed of the `Map Viewer`, `History Module to Linear Graph` and - `Linear Graph` components as well as the connections between those components: +- The second one can be called: **Show lamppost details**. This behaviour is composed of the `Map Viewer`, + `History Module to Linear Graph` and `Linear Graph` components as well as the connections between those components: - *Show lampposts details* behaviour (Santander example) + *Show lampposts details* behaviour (Santander example) -> Take into account that components and connections can be present in more than -> one behaviour. For example, in the previous example the *Map Viewer* widgets -> was used in both behaviours. +> Take into account that components and connections can be present in more than one behaviour. For example, in the +> previous example the _Map Viewer_ widgets was used in both behaviours. -WireCloud will continue supporting the creation of application mashups without -having to use the behaviour methodology. However, by using this brand new -feature WireCloud provides several benefits: +WireCloud will continue supporting the creation of application mashups without having to use the behaviour methodology. +However, by using this brand new feature WireCloud provides several benefits: -- Splitting the wiring configuration into severals behaviours helps to provide a - more organised and structured diagram as well as a way for documenting the - reasons for using and connecting components in a particular way. -- Even though using the behaviour oriented wiring has a harder - learning curve, using it eases the development of wiring configurations as it - allows you to develop them using several phases. -- This documentation is also a good starting point for novice and experienced - developers wanting to replicate the behaviour of a given - application mashup. They only need to access the application mashups developed - by other users and learn how the wiring configuration works by reading the - behaviour descriptions. +- Splitting the wiring configuration into severals behaviours helps to provide a more organised and structured diagram + as well as a way for documenting the reasons for using and connecting components in a particular way. +- Ignoring the fact that using the behaviour oriented wiring has a harder learning curve, using it eases the + development of wiring configurations as it allows you to develop them using several phases. +- This documentation is also a good starting point for novice developers and experiences developers wanting to + replicate the behaviour of a given application mashup. They only need to access the application mashups developed by + other users and learn how the wiring configuration works by reading the behaviour descriptions. ### Enabling/disabling the behaviour engine -Before using the Behaviour Oriented methodology, it must be enabled. To do so, -go to the wiring editor view and click on the *List behaviours* button. +Before using the Behaviour Oriented methodology, it must be enabled. To do so, go to the wiring editor view and click on +the _List behaviours_ button. *List behaviours* button -This will display a side panel, currently without any behaviour. Click on the -*Enable* button: +This will display a side panel, currently without any behaviour. Click on the _Enable_ button: *Enable* behaviour engine button -Once enabled, you will have a first behaviour with all the components and -connections previously added into the wiring configuration. +Once enabled, you will have a first behaviour with all the components and connections previously added into the wiring +configuration. -> *Note:* You can always go back to not use the behaviour engine by clicking on -> the *disable* button. +> _Note:_ You can always go back to not use the behaviour engine by clicking on the _disable_ button. > > *Disable* behaviour engine button > -> If you disable the behaviour engine, all components and connections will be -> squashed into a single view. +> If you disable the behaviour engine, all components and connections will be squashed into a single view. > > Take into account that this operation cannot be undone. @@ -533,157 +434,128 @@ connections previously added into the wiring configuration. General aspect of the behaviour oriented wiring user interface -This is the look of the wiring editor interface when the behaviour engine is -enabled. Each of the panels in the *Behaviours* section represents a -behaviour and displays the name and the description of the represented -behaviour. - -Notice that one of the behaviours is highlighted, the currently active behaviour. -This is because you can edit only a behaviour at a time. The name -of the active behaviour is also displayed in the footer of the wiring editor, so -you always see which is the active behaviour (i.e. including when the -behaviour list panel is hidden). Changing the active behaviour is just a matter -of clicking on the panel representing the behaviour. - -The other important thing to notice is that there are some "faded" components -inside the wiring canvas (e.g. the *Search For* widget). Background components are -faded because they do not form part of the active behaviour, although they form +This is the look of the wiring editor interface when the behaviour engine is enabled. Each of the panels in the +_Behaviours_ section represents a behaviour and displays the name and the description of the represented behaviour. + +Noticed that one of the behaviours is highlighted, this is because you can edit only a behaviour at a time, this is the +active behaviour. The name of the active behaviour is also displayed in the footer of the wiring editor, so you can know +which is the active behaviour all the time (i.e. including when the behaviour list panel is hidden). Changing the active +behaviour is just a matter of clicking on the panel representing the behaviour. + +The other important thing to notice is that there are some "faded" components inside the wiring canvas (e.g. the _Search +For_ widget). Background components are faded because they do not form part of the active behaviour, although they form part of other behaviours. #### Adding components and creating connections -You can add new components into a behaviour in the same way they are added when -the behaviour engine is disabled. That is, by draging them from the component -side panel. The only thing you have to take into account is that those -components are only added into the active behaviour. +You can add new components into a behaviour in the same way they are added when the behaviour engine is disabled. That +is, by draging them from the component side panel. The only thing you have to take into account is that those components +are only added into the active behaviour. -If you want to use a component already involved in another behaviour, you can use -the *Add* button of the background component you want to include: +If you want to use a component already involved in other behaviour, you can use the _Add_ button of the background +component you want to include: Component *Add* button -The same applies to the connections, if you create a new connection, that -connection is added only into the active behaviour. If you want to include a -connection already available on another behaviour, you can click on the *Add* -button of the background connection: +The same applies to the connections, if you create a new connection, that connection is added only into the active +behaviour. If you want to include a connection already available on other behaviour, you can click on the _Add_ button +of the background connection: Connection *Add* button -> **Note:** If a background connection implies background components, adding -> that connection will also add that background components into the active -> behaviour. +> **Note:** If a background connection implies background components, adding that connection will also add that +> background components into the active behaviour. #### Creating a new behaviour -You can create new behaviours by clicking on the *Create behaviour* button -available on the list behaviour side panel: +You can create new behaviours by clicking on the _Create behaviour_ button available on the list behaviour side panel: *Create* behaviour button *New Behaviour* dialog -If you want to edit the title and the description of a behaviour, you can open -the preferences menu and click on the *Settings* option: +If you want to edit the title and the description of a behaviour, you can open the preferences menu and click on the +_Settings_ option: Behaviour *Settings* option #### Removing behaviours -You can always remove a behaviour at any time, except when there is only one -behaviour (at least one behaviour must be present in a wiring configuration when -the behaviour engine is enabled). To do so, click on the *Remove* button of the +You can always remove a behaviour at any time, except when there is only one behaviour (at least one behaviour must be +present in a wiring configuration when the behaviour engine is enabled). To do so, click on the _Remove_ button of the behaviour you want to remove: *Remove* behaviour button -> **Note:** All the components not used on other behaviour will be removed from -> the wiring configuration. Also take into account that this operation cannot be -> undone. +> **Note:** All the components not used on other behaviour will be removed from the wiring configuration. Also take into +> account that this operation cannot be undone. #### Removing components and connections -To remove a component from a behaviour, click on the *Delete* button: +To remove a component from a behaviour, click on the _Delete_ button: *Remove* component button -Components are only completely removed from the wiring configuration when they are -not used in any of the available behaviours. +Components are only totaly removed from the wiring configuration when they are not used in any of the available +behaviours. -The same applies to connections, you can remove them from the active behaviour -using the *Delete* button: +The same applies to connections, you can remove them from the active behaviour using the _Delete_ button: *Remove* connection button -Again, connections are removed from the wiring configuration when they are removed -from all behaviours. +Again, connections are remove from the wiring configuration when the are removed from all the behaviours. #### Ordering behaviours -The main purpose of the behaviour engine is to be able to document the wiring -configuration and, in that sense, humans tend to expose the ideas using a particular -order. With that being said, the Wiring Editor allows you to change the order used in the -behaviour list, but that order will not affect the wiring engine. +The main purpose of the behaviour engine is to be able to document the wiring configuration and, in that sense, humans +tend to expose the ideas using a particular order. Said that, the Wiring Editor allows you to change the order used in +the behaviour list, but that order will not affet to the wiring engine. -To change the behaviour order, you only have to click on the *Order behaviours* -button: +To change the behaviour order, you only have to click on the _Order behaviours_ button: *Remove* connection button -Once the ordering mode is activated, you will be able to drag and drop the behaviour -boxes: +Once activated the ordering mode, you will be able to drag and drop the behaviour boxes: Ordering behaviours -Finally, click again on the *Order behaviours* button to exit the ordering mode: +Finally, click again on the _Order behaviours_ button to exit the ordering mode: Exit the ordering mode -> **Note:** Anyway, you can also exit from the behaviour ordering mode by -> closing the sidebar or by opening the seach component form inside the sidebar. - +> **Note:** Anyway, you can also exit from the behaviour ordering mode by closing the sidebar or by opening the seach +> component form inside the sidebar. -Sharing your mashups --------------------- +## Sharing your mashups -Workspaces can be made public by means of modifying their settings as -follows: +Workspaces can be made public by means of modifying their settings as Follows: -1. Click on the workspace menu button and click *Share*: +1. Click on the workspace menu button and click _Share_: *Share* option -2. You will be presented with a dialog for editing the sharing configuration of - the workspace: +2. You will be presented with a dialog for editing the sharing configuration of the workspace: Sharing settings dialog -After making a workspace public, you will be able to share the workspace -URL with other users. +After making a workspace public, you will be able to share the workspace URL with other users. ### Embedding mashups inside other web pages -All workspaces can be embedded, but take into account that access rules -are the same that applies when using the workspace directly from -WireCloud. If you don't make the workspace public, you will require -users to be logged in in WireCloud and having permission to access it. -This makes changing the sharing settings of the workspace a first step before +All workspaces can be embedded, but take into account that access rules are the same that applies when using the +workspace directly from WireCloud. If you don't make the workspace public, you will require users to be logged in +WireCloud and having enough access permission. This make changing sharing settings of the workspace a first step before embedding mashups into other web pages. -You can also obtain the code you have to copy & paste into other web -pages by following these steps: +You can also obtain the code you have to copy & paste into other web pages following those steps: -1. Click on the workspace menu button and click *Embed*: +1. Click on the workspace menu button and click _Embed_: *Embed* workspace option -1. A new window appears, showing you the code for embedding the mashup. Copy & - paste it into your HTML document. +1. A new window showing you the code for embedding the mashup. Copy & paste it into you HTML document. Embed workspace dialog -Additional sources of information ---------------------------------- +## Additional sources of information -See the [Application Mashup GE fundamentals -course](http://edu.fiware.org/course/view.php?id=53) at the FIWARE -Academy for detailed documentation on how to use WireCloud from -different perspectives (end-user, developer and administrator). Another -source of information is [the WireCloud -website](https://conwet.fi.upm.es/wirecloud/) where you can find more +See the [Application Mashup GE fundamentals course](http://edu.fiware.org/course/view.php?id=53) at the FIWARE Academy +for detailed documentation on how to use WireCloud from different perspectives (end-user, developer and administrators). +Another source of information is [the WireCloud website](https://conwet.fi.upm.es/wirecloud/) where you can find more general information and other interesting resources such as demo videos. diff --git a/docs/widgetapi/widgetapi.md b/docs/widgetapi/widgetapi.md index 9f8c3b7d7f..72c3cd95a0 100644 --- a/docs/widgetapi/widgetapi.md +++ b/docs/widgetapi/widgetapi.md @@ -1,5 +1,5 @@ -FIWARE Application Mashup - Widget API Specification -==================================================== +# FIWARE Application Mashup - Widget API Specification + Date: 26th August 2016 This version: @@ -16,7 +16,7 @@ https://github.com/Wirecloud/wirecloud/tree/develop/docs/widgetapi/ ## Editors - + Álvaro Arranz, Universidad Politécnica de Madrid +- Álvaro Arranz, Universidad Politécnica de Madrid ## Copyright @@ -24,340 +24,292 @@ Copyright © 2012-2016 by Universidad Politécnica de Madrid ## License -This specification is licensed under the [FIWARE Open Specification License (implicit patents license)](https://forge.fiware.org/plugins/mediawiki/wiki/fiware/index.php/FI-WARE_Open_Specification_Legal_Notice_%28implicit_patents_license%29). +This specification is licensed under the +[FIWARE Open Specification License (implicit patents license)](https://forge.fiware.org/plugins/mediawiki/wiki/fiware/index.php/FI-WARE_Open_Specification_Legal_Notice_%28implicit_patents_license%29). ----- +--- ## Abstract -The Application Mashup GE offers two separate APIs that cannot be combined -because of their different nature: The Widget API (the subject of this -document) is a JavaScript API, while the Application Mashup API is a -RESTful one. You can find the Application Mashup RESTful API in the -following link: +The Application Mashup GE offers two separate APIs that cannot be combined because of their different nature: The Widget +API (the subject of this document) is a JavaScript API, while the Application Mashup API is a RESTful one. You can find +the Application Mashup RESTful API in the following link: http://wirecloud.github.io/wirecloud/restapi/latest/ -The Widget API is a JavaScript API that allows widgets/operators to gain access -to the functionalities provided by the Application Mashup GE (wiring, -preferences, context information, logs, etc.). Amongst other functionalities, -this API allows the widgets/operators to gain access to remote resources (e.g. -in order to gain access to a remote REST API through the cross-domain proxy). +The Widget API is a JavaScript API that allows widgets/operators to gain access to the functionalities provided by the +Application Mashup GE (wiring, preferences, context information, logs, etc.). Amongst other functionalities, this API +allows the widgets/operators to gain access to remote resources (e.g. in order to gain access to a remote REST API +through the cross-domain proxy). -This document also show some examples that can be tested using WireCloud, the -reference implementation of the FIWARE Application Mashup GE. +This document also show some examples that can be tested using WireCloud, the reference implementation of the FIWARE +Application Mashup GE. ## Status of this document -This is a work in progress and is changing on a daily basis. You can check the latest -available version on: https://github.com/Wirecloud/wirecloud/tree/develop. -Please send your comments to wirecloud@conwet.com +This is a work in progress and is changing on a daily basis. You can check the latest available version on: +https://github.com/Wirecloud/wirecloud/tree/develop. Please send your comments to wirecloud@conwet.com -This specification is licensed under the [FIWARE Open Specification License (implicit patents license)](https://forge.fiware.org/plugins/mediawiki/wiki/fiware/index.php/FI-WARE_Open_Specification_Legal_Notice_%28implicit_patents_license%29). +This specification is licensed under the +[FIWARE Open Specification License (implicit patents license)](https://forge.fiware.org/plugins/mediawiki/wiki/fiware/index.php/FI-WARE_Open_Specification_Legal_Notice_%28implicit_patents_license%29). ----- +--- ## Widget API ### MashupPlatform.http -This module provides some methods for handling HTTP requests including support -for using the cross domain proxy. +This module provides some methods for handling HTTP requests including support for using the cross domain proxy. Currently this module is composed of two methods: -- [`buildProxyURL`](#mashupplatformhttpbuildproxyurl-method) -- [`makeRequest`](#mashupplatformhttpmakerequest-method) - +- [`buildProxyURL`](#mashupplatformhttpbuildproxyurl-method) +- [`makeRequest`](#mashupplatformhttpmakerequest-method) #### `MashupPlatform.http.buildProxyURL` method -This method builds a URL suitable for working around the cross-domain problem. -It is usually handled using the Application Mashup proxy but it also can be -handled using the access control request headers if the browser has support for -them. If all the needed requirements are meet, this function will return a URL -without using the proxy. +This method builds a URL suitable for working around the cross-domain problem. It is usually handled using the +Application Mashup proxy but it also can be handled using the access control request headers if the browser has support +for them. If all the needed requirements are meet, this function will return a URL without using the proxy. ```javascript -MashupPlatform.http.buildProxyURL(url, options) +MashupPlatform.http.buildProxyURL(url, options); ``` -* `url` (*required, string*): target URL -* `options` (*optional, object*): an object with request options (shown later) +- `url` (_required, string_): target URL +- `options` (_optional, object_): an object with request options (shown later) **Example usage:** ```javascript -var internal_url = 'http://server.intranet.com/image/a.png'; -var url = MashupPlatform.http.buildProxyURL(internal_url, {forceProxy: true}); -var img = document.createElement('img'); +var internal_url = "http://server.intranet.com/image/a.png"; +var url = MashupPlatform.http.buildProxyURL(internal_url, { forceProxy: true }); +var img = document.createElement("img"); img.src = url; ``` - #### `MashupPlatform.http.makeRequest` method -Sends an HTTP request. This method internally calls the buildProxyURL method for -working around any possible problem related with the same-origin policy followed -by browser (allowing CORS requests). +Sends an HTTP request. This method internally calls the buildProxyURL method for working around any possible problem +related with the same-origin policy followed by browser (allowing CORS requests). ```javascript -MashupPlatform.http.makeRequest(url, options) +MashupPlatform.http.makeRequest(url, options); ``` -* `url` (*required, string*): the URL to which to send the request -* `options` (*optional, object*): an object with a list of request options (shown later) +- `url` (_required, string_): the URL to which to send the request +- `options` (_optional, object_): an object with a list of request options (shown later) -This method returns a *Request* object +This method returns a _Request_ object **Example usage:** ```javascript -$('loading').show(); -var request = MashupPlatform.http.makeRequest('http://api.example.com', { +$("loading").show(); +var request = MashupPlatform.http.makeRequest("http://api.example.com", { method: "POST", - postBody: JSON.stringify({key: value}), + postBody: JSON.stringify({ key: value }), contentType: "application/json", - onSuccess: function (response) { + onSuccess: function(response) { // Everything went ok }, - onFailure: function (response) { + onFailure: function(response) { // Something went wrong }, - onComplete: function () { - $('loading').hide(); + onComplete: function() { + $("loading").hide(); } }); ``` - #### Request options: General options -- `contentType` (*string*): The Content-Type header for your request. If it is - not provided, the content-type header will be extrapolated from the value of - the `postBody` option (defaulting to `application/x-www-form-urlencoded` if - the `postBody` value is a String). Specify this option if you want to force - the value of the `Content-Type` header. -- `encoding` (*string; default `UTF-8`*): The encoding for the contents of your - request. It is best left as-is, but should weird encoding issues arise, you - may have to tweak this. -- `method` (*string; default `POST`*): The HTTP method to use for the request. -- `responseType` (*string; default: ""*): Can be set to change the response type. - The valid values for this options are: "", "arraybuffer", "blob", "document", - "json" and "text". -- `parameters` (*object*): The parameters for the request, which will be encoded - into the URL for a `GET` method, or into the request body when using the `PUT` - and `POST` methods. -- `postBody` (*`ArrayBufferView`, `Blob`, `Document`, `String`, `FormData`*): - The contents to use as request body (usually used in post and put requests, - but can be used by any request). If it is not provided, the contents of the - parameters option will be used instead. Finally, if there are not parameters, - request will not have a body. -- `requestHeaders` (*object*): A set of key-value pairs, with properties - representing header names. -- `supportsAccessControl` (*boolean; default `false`*): Indicates whether the - target server supports the [Access - Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS) - headers, and thus, you want to make a request without using the cross-domain - proxy if possible. -- `withCredentials` (*boolean; default `false`*): Indicates whether or not - cross-site `Access-Control` requests should be made using credentials such as - cookies or authorization headers. In addition, this flag is also used to - indicate when cookies are to be ignored in the response. -- `forceProxy` (*boolean; default `false`*): Sends the request through the proxy - regardless of the other options passed. -- `context` (*object; default `null`*): The value to be passed as - the this parameter to the callbacks. If context is `null` the `this` parameter - of the callbacks is left intact. - +- `contentType` (_string_): The Content-Type header for your request. If it is not provided, the content-type header + will be extrapolated from the value of the `postBody` option (defaulting to `application/x-www-form-urlencoded` if + the `postBody` value is a String). Specify this option if you want to force the value of the `Content-Type` header. +- `encoding` (_string; default `UTF-8`_): The encoding for the contents of your request. It is best left as-is, but + should weird encoding issues arise, you may have to tweak this. +- `method` (_string; default `POST`_): The HTTP method to use for the request. +- `responseType` (_string; default: ""_): Can be set to change the response type. The valid values for this options + are: "", "arraybuffer", "blob", "document", "json" and "text". +- `parameters` (_object_): The parameters for the request, which will be encoded into the URL for a `GET` method, or + into the request body when using the `PUT` and `POST` methods. +- `postBody` (_`ArrayBufferView`, `Blob`, `Document`, `String`, `FormData`_): The contents to use as request body + (usually used in post and put requests, but can be used by any request). If it is not provided, the contents of the + parameters option will be used instead. Finally, if there are not parameters, request will not have a body. +- `requestHeaders` (_object_): A set of key-value pairs, with properties representing header names. +- `supportsAccessControl` (_boolean; default `false`_): Indicates whether the target server supports the + [Access Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS) headers, and thus, you want + to make a request without using the cross-domain proxy if possible. +- `withCredentials` (_boolean; default `false`_): Indicates whether or not cross-site `Access-Control` requests should + be made using credentials such as cookies or authorization headers. In addition, this flag is also used to indicate + when cookies are to be ignored in the response. +- `forceProxy` (_boolean; default `false`_): Sends the request through the proxy regardless of the other options + passed. +- `context` (_object; default `null`_): The value to be passed as the this parameter to the callbacks. + If context is `null` the `this` parameter of the callbacks is left intact. #### Request options: Callback options -- `onAbort` (new in WireCloud 0.8.2): Invoked when the `abort()` method of the - Request object returned by `MashupPlatform.http.makeRequest()` is called -- `onSuccess`: Invoked when a request completes and its status code belongs in - the 2xy family. This is skipped if a code-specific callback is defined, and - happens before `onComplete`. Receives the response object as the first - argument -- `onFailure`: Invoked when a request completes and its status code exists but - is not in the 2xy family. This is skipped if a code-specific callback is - defined, and happens before `onComplete`. Receives the response object as the - first argument -- `onXYZ` (with XYZ representing any HTTP status code): Invoked just after the - response is complete if the status code is the exact code used in the callback - name. Prevents execution of `onSuccess` and `onFailure`. Happens - before `onComplete`. Receives the response object as the first argument -- `onComplete`: Triggered at the very end of a request's life-cycle, after the - request completes, status-specific callbacks are called, and possible - automatic behaviours are processed. Guaranteed to run regardless of what - happened during the request. Receives the response object as the first - argument -- `onException`: Triggered whenever an exception arises running any of the - `onXYZ`, `onSuccess`, `onFailure` and `onComplete` callbacks. Receives the - request as the first argument, and the exception object as the second one - +- `onAbort` (new in WireCloud 0.8.2): Invoked when the `abort()` method of the Request object returned by + `MashupPlatform.http.makeRequest()` is called +- `onSuccess`: Invoked when a request completes and its status code belongs in the 2xy family. This is skipped if a + code-specific callback is defined, and happens before `onComplete`. Receives the response object as the first + argument +- `onFailure`: Invoked when a request completes and its status code exists but is not in the 2xy family. This is + skipped if a code-specific callback is defined, and happens before `onComplete`. Receives the response object as the + first argument +- `onXYZ` (with XYZ representing any HTTP status code): Invoked just after the response is complete if the status code + is the exact code used in the callback name. Prevents execution of `onSuccess` and `onFailure`. Happens + before `onComplete`. Receives the response object as the first argument +- `onComplete`: Triggered at the very end of a request's life-cycle, after the request completes, status-specific + callbacks are called, and possible automatic behaviours are processed. Guaranteed to run regardless of what happened + during the request. Receives the response object as the first argument +- `onException`: Triggered whenever an exception arises running any of the `onXYZ`, `onSuccess`, `onFailure` and + `onComplete` callbacks. Receives the request as the first argument, and the exception object as the second one #### Request object -The request object returned by the `MashupPlatform.http.makeRequest` method -provides the following attributes: +The request object returned by the `MashupPlatform.http.makeRequest` method provides the following attributes: -- `method` (*string*): The HTTP method use by the request, such as "GET", - "POST", "PUT", "DELETE", etc. -- `url` (*string*): The final URL where the request has been sent to +- `method` (_string_): The HTTP method use by the request, such as "GET", "POST", "PUT", "DELETE", etc. +- `url` (_string_): The final URL where the request has been sent to And the following method: -- `abort()`: Aborts the request if it has already been sent - +- `abort()`: Aborts the request if it has already been sent #### Response object -The response object passed to the callbacks used with the -`MashupPlatform.http.makeRequest` method provides the following attributes: - -- `request` (*Request*): The request for the current response -- `status` (*number*): The status of the response to the request. This is the - HTTP result code -- `statusText` (*string*): The response string returned by the HTTP server. - Unlike status, this includes the entire text of the response message -- `response` (*`ArrayBuffer`, `Blob`, `Document`, *object*, `String`*): The - response entity body according to `responseType`, as an `ArrayBuffer`, `Blob` - or a `String`. This is `null` if the request is not complete, was not - successful or the `responseType` option of the requests was "" -- `responseText` (*string*): The response to the request as text, or `null` if - the request was unsuccessful or the `responseType` option of the requests was - different to "" -- `responseXML` (*Document*): The response to the request as a *Document*, or - `null` if the request was unsuccessful or cannot be parsed as XML or HTML. - The response is parsed as if it were a `text/xml` stream. This attribute is - not available if `responseType` is different to "". - +The response object passed to the callbacks used with the `MashupPlatform.http.makeRequest` method provides the +following attributes: + +- `request` (_Request_): The request for the current response +- `status` (_number_): The status of the response to the request. This is the HTTP result code +- `statusText` (_string_): The response string returned by the HTTP server. Unlike status, this includes the entire + text of the response message +- `response` (*`ArrayBuffer`, `Blob`, `Document`, *object*, `String`*): The response entity body according to + `responseType`, as an `ArrayBuffer`, `Blob` or a `String`. This is `null` if the request is not complete, was not + successful or the `responseType` option of the requests was "" +- `responseText` (_string_): The response to the request as text, or `null` if the request was unsuccessful or the + `responseType` option of the requests was different to "" +- `responseXML` (_Document_): The response to the request as a _Document_, or `null` if the request was unsuccessful + or cannot be parsed as XML or HTML. The response is parsed as if it were a `text/xml` stream. This attribute is not + available if `responseType` is different to "". ### MashupPlatform.log This module contains the following constants: -* **ERROR:** Used for indicating an Error level -* **WARN:** Used for indicating a Warning level -* **INFO:** Used for indicating an Info level - -Those constants can be used when calling to the `MashupPlatform.widget.log` and -`MashupPlatform.operator.log` methods. +- **ERROR:** Used for indicating an Error level +- **WARN:** Used for indicating a Warning level +- **INFO:** Used for indicating an Info level +Those constants can be used when calling to the `MashupPlatform.widget.log` and `MashupPlatform.operator.log` methods. ### MashupPlatform.prefs -This module provides methods for managing the preferences defined on the -mashable application component description file (`config.xml` file). +This module provides methods for managing the preferences defined on the mashable application component description file +(`config.xml` file). Currently, this module provides three methods: -- [`get`](#mashupplatformprefsget-method) -- [`registerCallback`](#mashupplatformprefsregistercallback-method) -- [`set`](#mashupplatformprefsset-method) +- [`get`](#mashupplatformprefsget-method) +- [`registerCallback`](#mashupplatformprefsregistercallback-method) +- [`set`](#mashupplatformprefsset-method) and one exception: -- [`PreferenceDoesNotExistError`](#mashupplatformprefspreferencedoesnotexisterror-exception) - +- [`PreferenceDoesNotExistError`](#mashupplatformprefspreferencedoesnotexisterror-exception) #### `MashupPlatform.prefs.get` method -This method retrieves the value of a preference. The type of the value returned -by this method depends on the type of the preference. +This method retrieves the value of a preference. The type of the value returned by this method depends on the type of +the preference. ```javascript -MashupPlatform.prefs.get(key) +MashupPlatform.prefs.get(key); ``` -- `key` (required, string): the name of the preference as defined on the - `config.xml` file. +- `key` (required, string): the name of the preference as defined on the `config.xml` file. This method can raise the following exceptions: -- `MashupPlatform.prefs.PreferenceDoesNotExistError` +- `MashupPlatform.prefs.PreferenceDoesNotExistError` **Example usage:** ```javascript -MashupPlatform.prefs.get('boolean-pref'); // true or false -MashupPlatform.prefs.get('number-prefs'); // a number value -MashupPlatform.prefs.get('text-prefs'); // a string value +MashupPlatform.prefs.get("boolean-pref"); // true or false +MashupPlatform.prefs.get("number-prefs"); // a number value +MashupPlatform.prefs.get("text-prefs"); // a string value ``` - #### `MashupPlatform.prefs.registerCallback` method This method registers a callback for listening for preference changes. ```javascript -MashupPlatform.prefs.registerCallback(callback) +MashupPlatform.prefs.registerCallback(callback); ``` -- `callback` function to be called when a change in one or more preferences is - detected. This callback will receive a key-value object with the changed - preferences and their new values. +- `callback` function to be called when a change in one or more preferences is detected. This callback will receive a + key-value object with the changed preferences and their new values. **Example usage:** ```javascript -MashupPlatform.prefs.registerCallback(function (new_values) { - if ('some-pref' in new_values) { +MashupPlatform.prefs.registerCallback(function(new_values) { + if ("some-pref" in new_values) { // some-pref has been changed // new_values['some-pref'] contains the new value } }); ``` - #### `MashupPlatform.prefs.set` method This method sets the value of a preference. ```javascript -MashupPlatform.prefs.set(key, value) +MashupPlatform.prefs.set(key, value); ``` -- `key` (*required, string*): the name of the preference as defined on the - `config.xml` file. -- `value` (*required, any*): new value for the preference. The acceptable values - for this parameter depends on the type of the preference. +- `key` (_required, string_): the name of the preference as defined on the `config.xml` file. +- `value` (_required, any_): new value for the preference. The acceptable values for this parameter depends on the + type of the preference. This method can raise the following exceptions: -- `MashupPlatform.prefs.PreferenceDoesNotExistError` +- `MashupPlatform.prefs.PreferenceDoesNotExistError` **Example usage:** ```javascript -MashupPlatform.prefs.set('boolean-pref', true); +MashupPlatform.prefs.set("boolean-pref", true); ``` - ### `MashupPlatform.prefs.PreferenceDoesNotExistError` exception This exception is raised when a preference is not found. ```javascript -MashupPlatform.prefs.PreferenceDoesNotExistError +MashupPlatform.prefs.PreferenceDoesNotExistError; ``` - ### MashupPlatform.mashup The mashup module contains one attribute: -- [`context`](#mashupplatformmashupcontext-attribute) +- [`context`](#mashupplatformmashupcontext-attribute) and the following methods: -- [`addWidget`](#mashupplatformmashupaddwidget-method) -- [`addOperator`](#mashupplatformmashupaddoperator-method) -- [`createWorkspace`](#mashupplatformmashupcreateworkspace-method) -- [`openWorkspace`](#mashupplatformmashupopenworkspace-method) -- [`removeWorkspace`](#mashupplatformmashupremoveworkspace-method) - +- [`addWidget`](#mashupplatformmashupaddwidget-method) +- [`addOperator`](#mashupplatformmashupaddoperator-method) +- [`createWorkspace`](#mashupplatformmashupcreateworkspace-method) +- [`openWorkspace`](#mashupplatformmashupopenworkspace-method) +- [`removeWorkspace`](#mashupplatformmashupremoveworkspace-method) #### `MashupPlatform.mashup.context` attribute @@ -365,317 +317,282 @@ This attribute contains the context manager of the mashup. See the [documentation about context managers](#context-managers) for more information. ```javascript -MashupPlatform.mashup.context +MashupPlatform.mashup.context; ``` **Example usage:** ```javascript -MashupPlatform.mashup.context.get('title'); +MashupPlatform.mashup.context.get("title"); ``` - #### `MashupPlatform.mashup.addWidget` method + > new in WireCloud 0.8.0 / Widget API v2 -This method allows widgets and operators to add new temporal widgets into the -current workspace. +This method allows widgets and operators to add new temporal widgets into the current workspace. -This method is only available when making use of the `DashboardManagement` -feature. +This method is only available when making use of the `DashboardManagement` feature. ```javascript -MashupPlatform.mashup.addWidget(widget_ref, options) +MashupPlatform.mashup.addWidget(widget_ref, options); ``` -- `widget_ref` (*required, string*): id (vendor/name/version) of the widget to - use. -- `options` (*optional, object*): object with extra options. +- `widget_ref` (_required, string_): id (vendor/name/version) of the widget to use. +- `options` (_optional, object_): object with extra options. Supported options: -- `title` (*string*): Title for the widget. If not provided, the default title - provided in the widget description will be used. -- `permissions` (*object*): Object with the permissions to apply to the widget. - Currently, the following permissions are available: `close`, `configure`, - `minimize`, `move`, `resize` and `upgrade`. -- `preferences` (*object*): Object with the initial configuration for the - preferences. If not provided, the default configuration of the widget is used. -- `properties` (*object*): Object with the initial configuration for the - properties. If not provided, the default configuration of the widget is used. -- `refposition` (*`ClientRect`*): Element position to use as reference for placing - the new widget. You can obtain such a object using the - [`getBoundingClientRect`][getBoundingClientRect] method. This option cannot be - used when using the `addWidget` method from an operator. -- `top` (*string, default: `0px`*): This option specifies the distance between - the top margin edge of the element and the top edge of the dashboard. This - value will be ignored if you provide a value for the `refposition` option. -- `left` (*string, default: `0px`*): This option specifies the distance between - the left margin edge of the element and the top edge of the dashboard. This - value will be ignored if you provide a value for the `refposition` option. -- `width` (*string, default: `null`*): This options specifies the width of the - widget. If not provided, the default width will be used. -- `height` (*string, default: `null`*): This options specifies the height of the - widget. If not provided, the default height will be used. - +- `title` (_string_): Title for the widget. If not provided, the default title provided in the widget description will + be used. +- `permissions` (_object_): Object with the permissions to apply to the widget. Currently, the following permissions + are available: `close`, `configure`, `minimize`, `move`, `resize` and `upgrade`. +- `preferences` (_object_): Object with the initial configuration for the preferences. If not provided, the default + configuration of the widget is used. +- `properties` (_object_): Object with the initial configuration for the properties. If not provided, the default + configuration of the widget is used. +- `refposition` (_`ClientRect`_): Element position to use as reference for placing the new widget. You can obtain such + a object using the [`getBoundingClientRect`][getboundingclientrect] method. This option cannot be used when using + the `addWidget` method from an operator. +- `top` (_string, default: `0px`_): This option specifies the distance between the top margin edge of the element and + the top edge of the dashboard. This value will be ignored if you provide a value for the `refposition` option. +- `left` (_string, default: `0px`_): This option specifies the distance between the left margin edge of the element + and the top edge of the dashboard. This value will be ignored if you provide a value for the `refposition` option. +- `width` (_string, default: `null`_): This options specifies the width of the widget. If not provided, the default + width will be used. +- `height` (_string, default: `null`_): This options specifies the height of the widget. If not provided, the default + height will be used. **Example usage:** ```javascript -var widget = MashupPlatform.mashup.addWidget('CoNWeT/kurento-one2one/1.0', { - "permissions": { - "close": false, - "configure": false +var widget = MashupPlatform.mashup.addWidget("CoNWeT/kurento-one2one/1.0", { + permissions: { + close: false, + configure: false }, - "preferences": { + preferences: { "stand-alone": { - "value": false + value: false } }, - "top": "0px", - "left": "66%" + top: "0px", + left: "66%" }); ``` -[getBoundingClientRect]: https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect - +[getboundingclientrect]: https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect #### `MashupPlatform.mashup.addOperator` method + > new in WireCloud 0.8.0 / Widget API v2 -This method allows widgets and operators to add new temporal operators into the -current workspace. +This method allows widgets and operators to add new temporal operators into the current workspace. -This method is only available when making use of the `DashboardManagement` -feature. +This method is only available when making use of the `DashboardManagement` feature. ```javascript -MashupPlatform.mashup.addOperator(operator_ref, options) +MashupPlatform.mashup.addOperator(operator_ref, options); ``` -- `operator_ref` (*required, string*): id (vendor/name/version) of the operator to use. -- `options` (*optional, object*): object with extra options. +- `operator_ref` (_required, string_): id (vendor/name/version) of the operator to use. +- `options` (_optional, object_): object with extra options. Supported options: -- `permissions` (*object*): Object with the permissions to apply to the operator. - Currently, the following permissions are available: `close`, `configure` and - `upgrade`. -- `preferences` (*object*): Object with the initial configuration for the - preferences. If not provided, the default configuration of the operator is used. +- `permissions` (_object_): Object with the permissions to apply to the operator. Currently, the following permissions + are available: `close`, `configure` and `upgrade`. +- `preferences` (_object_): Object with the initial configuration for the preferences. If not provided, the default + configuration of the operator is used. **Example usage:** ```javascript -var operator = MashupPlatform.mashup.addOperator('CoNWeT/ngsientity2poi/3.0.3', { - "preferences": { - "coordinates_attr": { - "value": "current_position" +var operator = MashupPlatform.mashup.addOperator("CoNWeT/ngsientity2poi/3.0.3", { + preferences: { + coordinates_attr: { + value: "current_position" } } }); ``` - #### `MashupPlatform.mashup.createWorkspace` method + > new in WireCloud 0.8.0 / Widget API v2 -This method allows widgets and operators to create new workspaces for the -current user. This method is asynchronous. +This method allows widgets and operators to create new workspaces for the current user. This method is asynchronous. -This method is only available when making use of the `DashboardManagement` -feature. +This method is only available when making use of the `DashboardManagement` feature. ```javascript -MashupPlatform.mashup.createWorkspace(options) +MashupPlatform.mashup.createWorkspace(options); ``` -- `options` (*required, object*): object with the options to use for creating - the workspace. At least one of the following options has to be provided: - `name`, `mashup`, `workspace`. +- `options` (_required, object_): object with the options to use for creating the workspace. At least one of the + following options has to be provided: `name`, `mashup`, `workspace`. Supported options: -- `name` (*string*): Name for the new workspace. This option is required if - neither `mashup` nor `workspace` option is used. If not provided, the name - of the mashup will be taken from the mashup or from the workspace to use - as template. -- `mashup` (*string*): id (vendor/name/version) of the mashup to use as - template for creating the new workspace. Both the `mashup` and `workspace` - attributes are optional, but should not be specified together. -- `workspace` (*string*): id (owner/name) of the workspace to use as template - for creating the new workspace. Both the `mashup` and `workspace` - attributes are optional, but should not be specified together. -- `allowrenaming` (*boolean, default `false`*): if this option is `true`, - the Application Mashup server will rename the workspace if a workspace with - the same name already exists. -- `preferences` (*object*): Object with the initial values for the workspace - preferences. If not provided, the default values will be used. -- `onSuccess` (*function*): callback to invoke if the workspace is created - successfully. -- `onFailure` (*function*): callback to invoke if some error is raised while - creating the workspace. +- `name` (_string_): Name for the new workspace. This option is required if neither `mashup` nor `workspace` option is + used. If not provided, the name of the mashup will be taken from the mashup or from the workspace to use as + template. +- `mashup` (_string_): id (vendor/name/version) of the mashup to use as template for creating the new workspace. Both + the `mashup` and `workspace` attributes are optional, but should not be specified together. +- `workspace` (_string_): id (owner/name) of the workspace to use as template for creating the new workspace. Both the + `mashup` and `workspace` attributes are optional, but should not be specified together. +- `allowrenaming` (_boolean, default `false`_): if this option is `true`, the Application Mashup server will rename + the workspace if a workspace with the same name already exists. +- `preferences` (_object_): Object with the initial values for the workspace preferences. If not provided, the default + values will be used. +- `onSuccess` (_function_): callback to invoke if the workspace is created successfully. +- `onFailure` (_function_): callback to invoke if some error is raised while creating the workspace. **Example usage:** ```javascript MashupPlatform.mashup.createWorkspace({ - name: 'New workspace', - mashup: 'CoNWeT/ckan-graph-mashup/1.0', - onSuccess: function (workspace) { + name: "New workspace", + mashup: "CoNWeT/ckan-graph-mashup/1.0", + onSuccess: function(workspace) { alert(workspace.owner + "/" + workspace.name + " created successfully"); } }); ``` - #### `MashupPlatform.mashup.openWorkspace` method + > new in WireCloud 1.0.0 / Widget API v3 This method allows widgets and operators to switch current workspace. This method is asynchronous. -This method is only available when making use of the `DashboardManagement` -feature. +This method is only available when making use of the `DashboardManagement` feature. ```javascript -MashupPlatform.mashup.openWorkspace(workspace, options) +MashupPlatform.mashup.openWorkspace(workspace, options); ``` -- `workspace` (*required, object*): Object composed of the following attributes: - - `owner` (*required, string*): Username of the workspace's owner. - - `name` (*required, string*): Name of the workspace. -- `options` (*object*): object with the options to use for opening the - workspace. +- `workspace` (_required, object_): Object composed of the following attributes: + - `owner` (_required, string_): Username of the workspace's owner. + - `name` (_required, string_): Name of the workspace. +- `options` (_object_): object with the options to use for opening the workspace. Supported options: -- `onFailure` (*function*): callback to invoke if some error is raised while - opening the workspace. +- `onFailure` (_function_): callback to invoke if some error is raised while opening the workspace. **Example usage:** ```javascript MashupPlatform.mashup.openWorkspace({ - owner: 'wirecloud', - name: 'home' + owner: "wirecloud", + name: "home" }); ``` - #### `MashupPlatform.mashup.removeWorkspace` method + > new in WireCloud 1.0.0 / Widget API v3 -This method allows widgets and operators to delete a workspace. This method is -asynchronous. +This method allows widgets and operators to delete a workspace. This method is asynchronous. -This method is only available when making use of the `DashboardManagement` -feature. +This method is only available when making use of the `DashboardManagement` feature. ```javascript -MashupPlatform.mashup.removeWorkspace(workspace, options) +MashupPlatform.mashup.removeWorkspace(workspace, options); ``` -- `workspace` (*required, object*): Object composed of the following attributes: - - `owner` (*required, string*): Username of the workspace's owner. - - `name` (*required, string*): Name of the workspace. -- `options` (*object*): object with the options to use for removing the - workspace. +- `workspace` (_required, object_): Object composed of the following attributes: + - `owner` (_required, string_): Username of the workspace's owner. + - `name` (_required, string_): Name of the workspace. +- `options` (_object_): object with the options to use for removing the workspace. Supported options: -- `onSuccess` (*function*): callback to invoke if the workspace is removed - successfully. -- `onFailure` (*function*): callback to invoke if some error is raised while - removing the workspace. +- `onSuccess` (_function_): callback to invoke if the workspace is removed successfully. +- `onFailure` (_function_): callback to invoke if some error is raised while removing the workspace. **Example usage:** ```javascript MashupPlatform.mashup.removeWorkspace({ - owner: 'user', - name: 'workspace' + owner: "user", + name: "workspace" }); ``` - ### MashupPlatform.operator -This module is only available when running inside an operator. Currently, -the Widget API provides the following attributes: - -- [`id`](#mashupplatformoperatorid-attribute) -- [`context`](#mashupplatformoperatorcontext-attribute) -- [`inputs`](#mashupplatformoperatorinputs-attribute) -- [`outputs`](#mashupplatformoperatoroutputs-attribute) +This module is only available when running inside an operator. Currently, the Widget API provides the following +attributes: +- [`id`](#mashupplatformoperatorid-attribute) +- [`context`](#mashupplatformoperatorcontext-attribute) +- [`inputs`](#mashupplatformoperatorinputs-attribute) +- [`outputs`](#mashupplatformoperatoroutputs-attribute) and three methods: -- [`createInputEndpoint`](#mashupplatformoperatorcreateinputendpoint-method) -- [`createOutputEndpoint`](#mashupplatformoperatorcreateoutputendpoint-method) -- [`log`](#mashupplatformoperatorlog-method) - +- [`createInputEndpoint`](#mashupplatformoperatorcreateinputendpoint-method) +- [`createOutputEndpoint`](#mashupplatformoperatorcreateoutputendpoint-method) +- [`log`](#mashupplatformoperatorlog-method) #### `MashupPlatform.operator.id` attribute This attribute contains the operator's id. ```javascript -MashupPlatform.operator.id +MashupPlatform.operator.id; ``` - #### `MashupPlatform.operator.context` attribute This attribute contains the context manager of the operator. See the [documentation about context managers](#context-managers) for more information. ```javascript -MashupPlatform.operator.context +MashupPlatform.operator.context; ``` **Example usage:** ```javascript -MashupPlatform.operator.context.get('version'); +MashupPlatform.operator.context.get("version"); ``` - #### `MashupPlatform.operator.inputs` attribute + > new in WireCloud 0.8.0 / Widget API v2 -A dict with the input endpoints of the operator using as key the name of the input -endpoints. +A dict with the input endpoints of the operator using as key the name of the input endpoints. ```javascript -MashupPlatform.operator.inputs +MashupPlatform.operator.inputs; ``` #### `MashupPlatform.operator.outputs` attribute + > new in WireCloud 0.8.0 / Widget API v2 -A dict with the input endpoints of the operator using as key the name of the output -endpoints. +A dict with the input endpoints of the operator using as key the name of the output endpoints. ```javascript -MashupPlatform.operator.outputs +MashupPlatform.operator.outputs; ``` - #### `MashupPlatform.operator.createInputEndpoint` method + > new in WireCloud 0.8.0 / Widget API v2 This method creates a dynamic input endpoint. -This method is only available when making use of the `DashboardManagement` -feature. +This method is only available when making use of the `DashboardManagement` feature. ```javascript MashupPlatform.operator.createInputEndpoint(callback); ``` -- `callback` (*required, function*): function that will be called when an event - arrives the input endpoint. +- `callback` (_required, function_): function that will be called when an event arrives the input endpoint. **Example usage:** @@ -686,14 +603,13 @@ MashupPlatform.operator.createInputEndpoint(function (data_string) { }); ``` - #### `MashupPlatform.operator.createOutputEndpoint` method + > new in WireCloud 0.8.0 / Widget API v2 This method creates a dynamic output endpoint. -This method is only available when making use of the `DashboardManagement` -feature. +This method is only available when making use of the `DashboardManagement` feature. ```javascript MashupPlatform.operator.createOutputEndpoint(); @@ -707,108 +623,98 @@ var endpoint = MashupPlatform.operator.createOutputEndpoint(); endpoint.pushEvent('event data'); ``` - #### `MashupPlatform.operator.log` method This method writes a message into the Application Mashup's log console. ```javascript -MashupPlatform.operator.log(msg, level) +MashupPlatform.operator.log(msg, level); ``` -- `msg` (*required, string*): is the text of the message to log. -- `level` (*optional, default: `MashupPlatform.log.ERROR`*): This optional - parameter specifies the level to use for logging the message. See - [MashupPlatform.log](#mashupplatformlog) for available log levels. +- `msg` (_required, string_): is the text of the message to log. +- `level` (_optional, default: `MashupPlatform.log.ERROR`_): This optional parameter specifies the level to use for + logging the message. See [MashupPlatform.log](#mashupplatformlog) for available log levels. **Example usage:** ```javascript -MashupPlatform.operator.log('error message description'); -MashupPlatform.operator.log('info message description', MashupPlatform.log.INFO); +MashupPlatform.operator.log("error message description"); +MashupPlatform.operator.log("info message description", MashupPlatform.log.INFO); ``` - ### MashupPlatform.widget -This module is only available when running inside a widget. Currently, -the Widget API provides the following attributes: +This module is only available when running inside a widget. Currently, the Widget API provides the following attributes: -- [`id`](#mashupplatformwidgetid-attribute) -- [`context`](#mashupplatformwidgetcontext-attribute) -- [`inputs`](#mashupplatformwidgetinputs-attribute) -- [`outputs`](#mashupplatformwidgetoutputs-attribute) +- [`id`](#mashupplatformwidgetid-attribute) +- [`context`](#mashupplatformwidgetcontext-attribute) +- [`inputs`](#mashupplatformwidgetinputs-attribute) +- [`outputs`](#mashupplatformwidgetoutputs-attribute) and the following methods: -- [`createInputEndpoint`](#mashupplatformwidgetcreateinputendpoint-method) -- [`createOutputEndpoint`](#mashupplatformwidgetcreateoutputendpoint-method) -- [`getVariable`](#mashupplatformwidgetgetvariable-method) -- [`drawAttention`](#mashupplatformwidgetdrawattention-method) -- [`log`](#mashupplatformwidgetlog-method) - +- [`createInputEndpoint`](#mashupplatformwidgetcreateinputendpoint-method) +- [`createOutputEndpoint`](#mashupplatformwidgetcreateoutputendpoint-method) +- [`getVariable`](#mashupplatformwidgetgetvariable-method) +- [`drawAttention`](#mashupplatformwidgetdrawattention-method) +- [`log`](#mashupplatformwidgetlog-method) #### `MashupPlatform.widget.id` attribute This attribute contains the widget's id. ```javascript -MashupPlatform.widget.id +MashupPlatform.widget.id; ``` - #### `MashupPlatform.widget.context` attribute This attribute contains the context manager of the widget. See the [documentation about context managers](#context-managers) for more information. ```javascript -MashupPlatform.widget.context +MashupPlatform.widget.context; ``` **Example usage:** ```javascript -MashupPlatform.widget.context.get('version'); +MashupPlatform.widget.context.get("version"); ``` - #### `MashupPlatform.widget.inputs` attribute + > new in WireCloud 0.8.0 / Widget API v2 -A dict with the input endpoints of the widget using as key the name of the input -endpoints. +A dict with the input endpoints of the widget using as key the name of the input endpoints. ```javascript -MashupPlatform.widget.inputs +MashupPlatform.widget.inputs; ``` - #### `MashupPlatform.widget.outputs` attribute + > new in WireCloud 0.8.0 / Widget API v2 -A dict with the input endpoints of the widget using as key the name of the output -endpoints. +A dict with the input endpoints of the widget using as key the name of the output endpoints. ```javascript -MashupPlatform.widget.outputs +MashupPlatform.widget.outputs; ``` - #### `MashupPlatform.widget.createInputEndpoint` method + > new in WireCloud 0.8.0 / Widget API v2 This method creates a dynamic input endpoint. -This method is only available when making use of the `DashboardManagement` -feature. +This method is only available when making use of the `DashboardManagement` feature. ```javascript MashupPlatform.widget.createInputEndpoint(callback); ``` -- `callback` (*required, function*): the function that will be called when an - event arrives the input endpoint. +- `callback` (_required, function_): the function that will be called when an event arrives the input endpoint. **Example usage:** @@ -819,14 +725,13 @@ MashupPlatform.widget.createInputEndpoint(function (data_string) { }); ``` - #### `MashupPlatform.widget.createOutputEndpoint` method + > new in WireCloud 0.8.0 / Widget API v2 This method creates a dynamic output endpoint. -This method is only available when making use of the `DashboardManagement` -feature. +This method is only available when making use of the `DashboardManagement` feature. ```javascript MashupPlatform.widget.createOutputEndpoint(); @@ -840,163 +745,148 @@ var endpoint = MashupPlatform.widget.createOutputEndpoint(); endpoint.pushEvent('event data'); ``` - #### `MashupPlatform.widget.getVariable` method Returns a widget variable by its name. ```javascript -MashupPlatform.widget.getVariable(name) +MashupPlatform.widget.getVariable(name); ``` -- `name` (*required, string*): the name of the persistent variable as defined on - the `config.xml` file. +- `name` (_required, string_): the name of the persistent variable as defined on the `config.xml` file. **Example usage:** ```javascript -var variable = MashupPlatform.widget.getVariable('persistent-var'); +var variable = MashupPlatform.widget.getVariable("persistent-var"); variable.set(JSON.stringify(data)); ``` - #### `MashupPlatform.widget.drawAttention` method -Makes the Application Mashup Engine notify that the widget needs user's -attention. +Makes the Application Mashup Engine notify that the widget needs user's attention. ```javascript -MashupPlatform.widget.drawAttention() +MashupPlatform.widget.drawAttention(); ``` - #### `MashupPlatform.widget.log` method Writes a message into the Application Mashup's log console. ```javascript -MashupPlatform.widget.log(msg, level) +MashupPlatform.widget.log(msg, level); ``` -- `msg` (*required, string*): is the text of the message to log. -- `level` (*optional, default: `MashupPlatform.log.ERROR`*): This optional - parameter specifies the level to use for logging the message. See - [MashupPlatform.log](#mashupplatform-log) for available log levels. +- `msg` (_required, string_): is the text of the message to log. +- `level` (_optional, default: `MashupPlatform.log.ERROR`_): This optional parameter specifies the level to use for + logging the message. See [MashupPlatform.log](#mashupplatform-log) for available log levels. **Example usage:** ```javascript -MashupPlatform.widget.log('error message description'); -MashupPlatform.widget.log('warning message description', MashupPlatform.log.WARN); +MashupPlatform.widget.log("error message description"); +MashupPlatform.widget.log("warning message description", MashupPlatform.log.WARN); ``` - ### MashupPlatform.wiring -This module provides some methods for handling the communication between widgets -an operators through the wiring. +This module provides some methods for handling the communication between widgets an operators through the wiring. Currently this module is composed of five methods: -- [`hasInputConnections`](#mashupplatformwiringhasinputconnections-method) -- [`hasOutputConnections`](#mashupplatformwiringhasoutputconnections-method) -- [`pushEvent`](#mashupplatformwiringpushevent-method) -- [`registerCallback`](#mashupplatformwiringregistercallback-method) -- [`registerStatusCallback`](#mashupplatformwiringregisterstatuscallback-method) +- [`hasInputConnections`](#mashupplatformwiringhasinputconnections-method) +- [`hasOutputConnections`](#mashupplatformwiringhasoutputconnections-method) +- [`pushEvent`](#mashupplatformwiringpushevent-method) +- [`registerCallback`](#mashupplatformwiringregistercallback-method) +- [`registerStatusCallback`](#mashupplatformwiringregisterstatuscallback-method) and three exceptions: -- [`EndpointDoesNotExistError`](#mashupplatformwiringendpointdoesnotexisterror-exception) -- [`EndpointTypeError`](#mashupplatformwiringendpointtypeerror-exception) -- [`EndpointValueError`](#mashupplatformwiringendpointvalueerror-exception) - +- [`EndpointDoesNotExistError`](#mashupplatformwiringendpointdoesnotexisterror-exception) +- [`EndpointTypeError`](#mashupplatformwiringendpointtypeerror-exception) +- [`EndpointValueError`](#mashupplatformwiringendpointvalueerror-exception) #### `MashupPlatform.wiring.hasInputConnections` method + > new in WireCloud 0.8.0 / Widget API v2 Sends an event through the wiring. ```javascript -MashupPlatform.wiring.hasInputConnections(inputName) +MashupPlatform.wiring.hasInputConnections(inputName); ``` -- `inputName` (*required, string*): name of the input endpoint to - query if has connections +- `inputName` (_required, string_): name of the input endpoint to query if has connections This method can raise the following exceptions: -- `MashupPlatform.wiring.EndpointDoesNotExistError` +- `MashupPlatform.wiring.EndpointDoesNotExistError` **Example usage:** ```javascript -MashupPlatform.wiring.hasInputConnections('inputendpoint'); +MashupPlatform.wiring.hasInputConnections("inputendpoint"); ``` - #### `MashupPlatform.wiring.hasOutputConnections` method + > new in WireCloud 0.8.0 / Widget API v2 Sends an event through the wiring. ```javascript -MashupPlatform.wiring.hasOutputConnections(outputName) +MashupPlatform.wiring.hasOutputConnections(outputName); ``` -- `outputName` (*required, string*): name of the output endpoint to - query if has connections +- `outputName` (_required, string_): name of the output endpoint to query if has connections This method can raise the following exceptions: -- `MashupPlatform.wiring.EndpointDoesNotExistError` +- `MashupPlatform.wiring.EndpointDoesNotExistError` **Example usage:** ```javascript -MashupPlatform.wiring.hasOutputConnections('outputendpoint'); +MashupPlatform.wiring.hasOutputConnections("outputendpoint"); ``` - #### `MashupPlatform.wiring.pushEvent` method Sends an event through the wiring. ```javascript -MashupPlatform.wiring.pushEvent(outputName, data) +MashupPlatform.wiring.pushEvent(outputName, data); ``` -- `outputName` (*required, string*): name of the output endpoint to use for - sending the event. -- `data` (*required, any*): data to send +- `outputName` (_required, string_): name of the output endpoint to use for sending the event. +- `data` (_required, any_): data to send This method can raise the following exceptions: -- `MashupPlatform.wiring.EndpointDoesNotExistError` +- `MashupPlatform.wiring.EndpointDoesNotExistError` **Example usage:** ```javascript -MashupPlatform.wiring.pushEvent('outputendpoint', 'event data'); +MashupPlatform.wiring.pushEvent("outputendpoint", "event data"); ``` - #### `MashupPlatform.wiring.registerCallback` method -Registers a callback for a given input endpoint. If the given endpoint already -has registered a callback, it will be replaced by the new one. +Registers a callback for a given input endpoint. If the given endpoint already has registered a callback, it will be +replaced by the new one. ```javascript -MashupPlatform.wiring.registerCallback(inputName, callback) +MashupPlatform.wiring.registerCallback(inputName, callback); ``` -- `inputName` (*required, string*): name of the input endpoint where the - callback function will be registered -- `callback` (*required, function*): function that will be called when an event - arrives the input endpoint +- `inputName` (_required, string_): name of the input endpoint where the callback function will be registered +- `callback` (_required, function_): function that will be called when an event arrives the input endpoint This method can raise the following exceptions: -- `MashupPlatform.wiring.EndpointDoesNotExistError` +- `MashupPlatform.wiring.EndpointDoesNotExistError` **Example usage:** @@ -1007,19 +897,18 @@ MashupPlatform.wiring.registerCallback('inputendpoint', function (data_string) { }); ``` - #### `MashupPlatform.wiring.registerStatusCallback` method + > new in WireCloud 0.8.0 / Widget API v2 -Registers a callback that will be called everytime the wiring status of the -mashup change, except by the changes made using this Widget API. +Registers a callback that will be called everytime the wiring status of the mashup change, except by the changes made +using this Widget API. ```javascript -MashupPlatform.wiring.registerStatusCallback(callback) +MashupPlatform.wiring.registerStatusCallback(callback); ``` -- `callback` (*required, function*): function that will be called everytime the - wiring configuration is changed +- `callback` (_required, function_): function that will be called everytime the wiring configuration is changed **Example usage:** @@ -1029,27 +918,26 @@ MashupPlatform.wiring.registerStatusCallback(function () { }); ``` - #### `MashupPlatform.wiring.EndpointDoesNotExistError` exception This exception is raised when an input/output endpoint is not found. ```javascript -MashupPlatform.wiring.EndpointDoesNotExistError +MashupPlatform.wiring.EndpointDoesNotExistError; ``` - #### `MashupPlatform.wiring.EndpointTypeError` exception + > new in WireCloud 0.8.0 / Widget API v2 -Widgets/operators can throw this exception if they detect that the data arriving -an input endpoint is not of the expected type. +Widgets/operators can throw this exception if they detect that the data arriving an input endpoint is not of the +expected type. ```javascript -MashupPlatform.wiring.EndpointTypeError(message) +MashupPlatform.wiring.EndpointTypeError(message); ``` -- `message` (*required, string*): message text describing the exception +- `message` (_required, string_): message text describing the exception **Example usage:** @@ -1065,18 +953,18 @@ MashupPlatform.wiring.registerCallback('inputendpoint', function (data) { }); ``` - #### `MashupPlatform.wiring.EndpointValueError` exception + > new in WireCloud 0.8.0 / Widget API v2 -Widgets/operators can throw this exception if they detect that the data arriving -an input endpoint, although has the right type, contains inappropriate values. +Widgets/operators can throw this exception if they detect that the data arriving an input endpoint, although has the +right type, contains inappropriate values. ```javascript -MashupPlatform.wiring.EndpointValueError(message) +MashupPlatform.wiring.EndpointValueError(message); ``` -- `message` (*required, string*): message text describing the exception +- `message` (_required, string_): message text describing the exception **Example usage:** @@ -1093,47 +981,47 @@ MashupPlatform.wiring.registerCallback('inputendpoint', function (data) { ``` ### Endpoint instances + > new in WireCloud 0.8.0 / Widget API v2 Endpoint instances provide one attribute: -- [`connected`](#endpointconnected-attribute) +- [`connected`](#endpointconnected-attribute) and the following methods (depending on the type of endpoint): -- [`connect`](#endpointconnect-method) -- [`disconnect`](#endpointdisconnect-method) -- [`pushEvent`](#endpointpushevent-method) +- [`connect`](#endpointconnect-method) +- [`disconnect`](#endpointdisconnect-method) +- [`pushEvent`](#endpointpushevent-method) #### `Endpoint.connected` attribute This attribute indicates if the associated endpoint has at least one connection. ```javascript -Endpoint.connected +Endpoint.connected; ``` **Example usage** + ```javascript if (MashupPlatform.widget.inputs.source.connected) { - $('#alert').hide(); + $("#alert").hide(); } else { - $('#alert').show(); + $("#alert").show(); } - ``` #### `Endpoint.connect` method -This method stablishes a connection between the endpoint associated to the -instance and the endpoint passed as parameter. +This method stablishes a connection between the endpoint associated to the instance and the endpoint passed as +parameter. ```javascript -Endpoint.connect(endpoint) +Endpoint.connect(endpoint); ``` -- `endpoint` (*required, `Endpoint`*): the input/output endpoint to connect on - the other end of the connection. +- `endpoint` (_required, `Endpoint`_): the input/output endpoint to connect on the other end of the connection. **Example usage** @@ -1146,19 +1034,18 @@ operator.outputs.poiOutput.connect(widget.inputs.poiInput); ``` #### `Endpoint.disconnect` method + > new in WireCloud 1.0 / Widget API v2 -Removes dynamic connections starting or ending in this endpoint. This method -cannot be used for disconnecting connections created by the user using the -Wiring Editor. +Removes dynamic connections starting or ending in this endpoint. This method cannot be used for disconnecting +connections created by the user using the Wiring Editor. ```javascript -Endpoint.disconnect(endpoint) +Endpoint.disconnect(endpoint); ``` -- `endpoint` (*optional, `Endpoint`*): the endpoint on the other end of the - connection to remove. If `endpoint` is `null`, all the dynamic connections - related to this endpoint will be disconnected. +- `endpoint` (_optional, `Endpoint`_): the endpoint on the other end of the connection to remove. If `endpoint` is + `null`, all the dynamic connections related to this endpoint will be disconnected. **Example usage** @@ -1173,8 +1060,6 @@ operator.outputs.poiOutput.connect(widget.inputs.poiInput); MashupPlatform.widget.outputs.entity.disconnect(operator.inputs.entityInput); operator.outputs.poiOutput.disconnect(widget.inputs.poiInput); - - ``` #### `Endpoint.pushEvent` method @@ -1184,64 +1069,58 @@ Sends an event through the wiring. Only available on output endpoints. ```javascript -Endpoint.pushEvent(data) +Endpoint.pushEvent(data); ``` -- `data` (*required, any*): data to send +- `data` (_required, any_): data to send **Example usage:** ```javascript -MashupPlatform.widget.outputs.entity.pushEvent('event data'); +MashupPlatform.widget.outputs.entity.pushEvent("event data"); ``` - ### Widget instances + > new in WireCloud 0.8.0 / Widget API v2 -Widget instances (obtained using the `MashupPlatform.mashup.addWidget` method) -provides the following attributes: +Widget instances (obtained using the `MashupPlatform.mashup.addWidget` method) provides the following attributes: -- [`inputs`](#widgetinputs-attribute) -- [`outputs`](#widgetoutputs-attribute) +- [`inputs`](#widgetinputs-attribute) +- [`outputs`](#widgetoutputs-attribute) And the following methods: -- [`addEventListener`](#widgetaddeventlistener-method) -- [`remove`](#widgetremove-method) - +- [`addEventListener`](#widgetaddeventlistener-method) +- [`remove`](#widgetremove-method) #### `Widget.inputs` attribute -A dict with the input endpoints of the widget using as key the name of the input -endpoints. +A dict with the input endpoints of the widget using as key the name of the input endpoints. ```javascript -Widget.inputs +Widget.inputs; ``` - #### `Widget.outputs` attribute -A dict with the input endpoints of the widget using as key the name of the output -endpoints. +A dict with the input endpoints of the widget using as key the name of the output endpoints. ```javascript -Widget.outputs +Widget.outputs; ``` - #### `Widget.addEventListener` method This method registers the specified listener on the `Widget` it's called on. ```javascript -Widget.addEventListener(name, handler) +Widget.addEventListener(name, handler); ``` -- `name` (*required, string*): name of the event to listen for. -- `listener` (*required, function*): function that will be called when an event, - of the indicated type, is raised by the widget. +- `name` (_required, string_): name of the event to listen for. +- `listener` (_required, function_): function that will be called when an event, of the indicated type, is raised by + the widget. **Example usage:** @@ -1251,14 +1130,13 @@ var widget = MashupPlatform.mashup.addWidget(...); widget.addEventListener("close", onWidgetClose); ``` - #### `Widget.remove` method -This method removes the widget from the workspace. Any wiring connection -involving this widget is disconnected before removing the widget. +This method removes the widget from the workspace. Any wiring connection involving this widget is disconnected before +removing the widget. ```javascript -Widget.remove() +Widget.remove(); ``` **Example usage:** @@ -1269,56 +1147,52 @@ var widget = MashupPlatform.mashup.addWidget(...); widget.remove(); ``` - ### Workspace instances + > new in WireCloud 1.0.0 / Widget API v3 -Workspace instances (obtained using the `MashupPlatform.mashup.createWorkspace` -method) provides the following attributes: +Workspace instances (obtained using the `MashupPlatform.mashup.createWorkspace` method) provides the following +attributes: -- [`name`](#workspacename-attribute) -- [`owner`](#workspaceowner-attribute) +- [`name`](#workspacename-attribute) +- [`owner`](#workspaceowner-attribute) and the following methods: -- [`open`](#workspaceopen-method) -- [`remove`](#workspaceremove-method) - +- [`open`](#workspaceopen-method) +- [`remove`](#workspaceremove-method) #### `Workspace.name` attribute A string with the name of the workspace. ```javascript -Workspace.name +Workspace.name; ``` - #### `Workspace.owner` attribute A string with the username of the workspace's owner. ```javascript -Workspace.owner +Workspace.owner; ``` - #### `Workspace.open` method + > new in WireCloud 1.0.0 / Widget API v3 This method opens the workspace, closing the current one. ```javascript -Workspace.open(options) +Workspace.open(options); ``` -- `options` (*object*): object with the options to use for opening the - workspace. +- `options` (_object_): object with the options to use for opening the workspace. Supported options: -- `onFailure` (*function*): callback to invoke if some error is raised while - opening the workspace. +- `onFailure` (_function_): callback to invoke if some error is raised while opening the workspace. **Example usage:** @@ -1331,26 +1205,22 @@ MashupPlatform.mashup.createWorkspace({ ); ``` - #### `Workspace.remove` method + > new in WireCloud 1.0.0 / Widget API v3 This method removes the workspace. ```javascript -Workspace.remove(options) +Workspace.remove(options); ``` -- `options` (*object*): object with the options to use for removing the - workspace. +- `options` (_object_): object with the options to use for removing the workspace. Supported options: -- `onSuccess` (*function*): callback to invoke if the workspace is removed - successfully. -- `onFailure` (*function*): callback to invoke if some error is raised while - removing the workspace. - +- `onSuccess` (_function_): callback to invoke if the workspace is removed successfully. +- `onFailure` (_function_): callback to invoke if some error is raised while removing the workspace. **Example usage:** @@ -1369,53 +1239,47 @@ MashupPlatform.mashup.createWorkspace({ myWorkspace.remove(); ``` - ### Operator instances + > new in WireCloud 0.8.0 / Widget API v2 -Operators instances (obtained using the `MashupPlatform.mashup.addOperator` -method) provides the following attributes: +Operators instances (obtained using the `MashupPlatform.mashup.addOperator` method) provides the following attributes: -- [`inputs`](#operatorinputs-attribute) -- [`outputs`](#operatoroutputs-attribute) +- [`inputs`](#operatorinputs-attribute) +- [`outputs`](#operatoroutputs-attribute) And the following methods: -- [`addEventListener`](#operatoraddeventlistener-method) -- [`remove`](#operatorremove-method) - +- [`addEventListener`](#operatoraddeventlistener-method) +- [`remove`](#operatorremove-method) #### `Operator.inputs` attribute -A dict with the input endpoints of the operator using as key the name of the input -endpoints. +A dict with the input endpoints of the operator using as key the name of the input endpoints. ```javascript -Operator.inputs +Operator.inputs; ``` - #### `Operator.outputs` attribute -A dict with the input endpoints of the operator using as key the name of the output -endpoints. +A dict with the input endpoints of the operator using as key the name of the output endpoints. ```javascript -Operator.outputs +Operator.outputs; ``` - #### `Operator.addEventListener` method This method registers the specified listener on the `Operator` it's called on. ```javascript -Operator.addEventListener(name, handler) +Operator.addEventListener(name, handler); ``` -- `name` (*required, string*): name of the event to listen for. -- `listener` (*required, function*): function that will be called when an event, - of the indicated type, is raised by the operator. +- `name` (_required, string_): name of the event to listen for. +- `listener` (_required, function_): function that will be called when an event, of the indicated type, is raised by + the operator. **Example usage:** @@ -1425,14 +1289,13 @@ var operator = MashupPlatform.mashup.addOperator(...); operator.addEventListener("close", onOperatorClose); ``` - #### `Operator.remove` method -This method removes the operator from the workspace. Any wiring connection -involving this operator is disconnected before removing the operator. +This method removes the operator from the workspace. Any wiring connection involving this operator is disconnected +before removing the operator. ```javascript -Operator.remove() +Operator.remove(); ``` **Example usage:** @@ -1443,21 +1306,20 @@ var operator = MashupPlatform.mashup.addOperator(...); operator.remove(); ``` - ### Context Managers Each context managers supports three methods: -* [`getAvailableContext`](#contextmanagergetavailablecontext-method) -* [`get`](#contextmanagerget-method) -* [`registerCallback`](#contextmanagerregistercallback-method) +- [`getAvailableContext`](#contextmanagergetavailablecontext-method) +- [`get`](#contextmanagerget-method) +- [`registerCallback`](#contextmanagerregistercallback-method) #### `ContextManager.getAvailableContext` method This method provides information about what concepts are available for the given level ```javascript -ContextManager.getAvailableContext() +ContextManager.getAvailableContext(); ``` **Example usage:** @@ -1471,17 +1333,17 @@ MashupPlatform.context.getAvailableContext(); Retrieves the current value for a concept ```javascript -ContextManager.get(key) +ContextManager.get(key); ``` -- `key` (*required, string*): name of the concept to query. +- `key` (_required, string_): name of the concept to query. **Example usage:** ```javascript -MashupPlatform.widget.context.get('heightInPixels'); -MashupPlatform.mashup.context.get('name'); -MashupPlatform.context.get('username'); +MashupPlatform.widget.context.get("heightInPixels"); +MashupPlatform.mashup.context.get("name"); +MashupPlatform.context.get("username"); ``` #### `ContextManager.registerCallback` method @@ -1489,17 +1351,17 @@ MashupPlatform.context.get('username'); Allows to register a callback that will be called when any of the concepts are modified ```javascript -ContextManager.registerCallback(callback) +ContextManager.registerCallback(callback); ``` -- `callback` (*required, function*): function that will be called everytime the - context information managed by the context manager change. +- `callback` (_required, function_): function that will be called everytime the context information managed by the + context manager change. **Example usage:** ```javascript -MashupPlatform.widget.context.registerCallback(function (new_values) { - if ('some-context-concept' in new_values) { +MashupPlatform.widget.context.registerCallback(function(new_values) { + if ("some-context-concept" in new_values) { // some-context-concept has been changed // new_values['some-context-concept'] contains the new value } @@ -1508,13 +1370,13 @@ MashupPlatform.widget.context.registerCallback(function (new_values) { ## Acknowledgements -The editors would like to express their gratitude to the following people who -actively contributed to this specification: Aitor Magan and Francisco de la Vega +The editors would like to express their gratitude to the following people who actively contributed to this +specification: Aitor Magan and Francisco de la Vega ## References -- [Github source](https://github.com/Wirecloud/wirecloud) -- [Application Mashup API](http://wirecloud.github.io/wirecloud/restapi/latest/) -- [FIWARE Open Specification License (implicit patents license)](https://forge.fiware.org/plugins/mediawiki/wiki/fiware/index.php/FI-WARE_Open_Specification_Legal_Notice_%28implicit_patents_license%29) -- [CSSOM Views: The getClientRects() and getBoundingClientRect() methods](http://www.w3.org/TR/cssom-view/#the-getclientrects%28%29-and-getboundingclientrect%28%29-methods) -- [Cross-Origin Resource Sharing](http://www.w3.org/TR/cors/) +- [Github source](https://github.com/Wirecloud/wirecloud) +- [Application Mashup API](http://wirecloud.github.io/wirecloud/restapi/latest/) +- [FIWARE Open Specification License (implicit patents license)](https://forge.fiware.org/plugins/mediawiki/wiki/fiware/index.php/FI-WARE_Open_Specification_Legal_Notice_%28implicit_patents_license%29) +- [CSSOM Views: The getClientRects() and getBoundingClientRect() methods](http://www.w3.org/TR/cssom-view/#the-getclientrects%28%29-and-getboundingclientrect%28%29-methods) +- [Cross-Origin Resource Sharing](http://www.w3.org/TR/cors/) diff --git a/mkdocs.yml b/mkdocs.yml index 6214506b2a..b4663ac925 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -33,7 +33,7 @@ markdown_extensions: - pymdownx.betterem - pymdownx.tilde: subscript: False - - pymdownx.superfences +# - pymdownx.superfences - pymdownx.magiclink: repo_url_shortener: True repo_url_shorthand: True @@ -41,8 +41,8 @@ markdown_extensions: user: "Wirecloud" repo: "wirecloud" - pymdownx.tasklist - - codehilite: - guess_lang: False +# - codehilite: +# guess_lang: False - toc: permalink: True separator: "-" From fb9c4006dc5b60edfecdcd8defcbcfe47ba52ebb Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Tue, 26 Mar 2019 14:53:21 +0000 Subject: [PATCH 2/4] First round of fixes --- docs/installation_guide.md | 64 +++++++++++++++++++------------------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/docs/installation_guide.md b/docs/installation_guide.md index 02020d707e..bc9b44dd0e 100644 --- a/docs/installation_guide.md +++ b/docs/installation_guide.md @@ -112,7 +112,7 @@ pip install pyOpenSSL ndg-httpsclient pyasn1 CentOS/RHEL 6 only ships python 2.6, so you have to install python 2.7 from a different repository. We recommend you to use the Software Collection respository: -```text +```bash # 1. Install a package with repository for your system: # On CentOS, install package centos-release-scl available in CentOS repository: $ sudo yum install centos-release-scl @@ -518,18 +518,15 @@ python manage.py populate Wirecloud uses [Haystack](http://haystacksearch.org/) to handle the search indexes. -Currently, [Solr][], [ElasticSearch2][] and [Whoosh][] are supported. Whoosh is enabled by default. +Currently, [Solr](http://lucene.apache.org/solr/), [ElasticSearch2](https://www.elastic.co/products/elasticsearch) and [Whoosh](https://whoosh.readthedocs.io/en/latest/) are supported. Whoosh is enabled by default. To modify the search engine configuration, it is necessary to modify the `HAYSTACK_CONNECTIONS` configuration setting in the instance `settings.py` file (e.g. `/opt/wirecloud_instance/wirecloud_instance/settings.py`). -[solr]: http://lucene.apache.org/solr/ -[elasticsearch2]: https://www.elastic.co/products/elasticsearch -[whoosh]: https://whoosh.readthedocs.io/en/latest/ ### Whoosh configuration -[Whoosh][] is a fast, featureful full-text indexing and searching library implemented in pure Python. It is very easy to +[Whoosh](https://whoosh.readthedocs.io/en/latest/) is a fast, featureful full-text indexing and searching library implemented in pure Python. It is very easy to configure and does not require to configure any service, so it is ideal for basic installations. This make this engine the default engine for using WireCloud, altough probably ElasticSearch2 or Solr are better choices if you require to provide an high availablility installation of WireCloud. @@ -550,7 +547,7 @@ be stored. ### ElasticSearch2 configuration -[ElasticSearch][] support is not installed by default, so the first thing is to install the python module required to +[ElasticSearch](https://www.elastic.co/products/elasticsearch) support is not installed by default, so the first thing is to install the python module required to connect to ElasticSearch: ```bash @@ -904,11 +901,13 @@ _OAuth2 Credentials_ section) as they are going to be used later. On the WireCloud instance: -- Install the `social-auth-app-django` module (e.g. `pip install "social-auth-app-django"`) -- Edit `settings.py`: - - Remove `wirecloud.oauth2provider` from `INSTALLED_APPS` - - Add `social_django` to `INSTALLED_APPS` - - Add `wirecloud.fiware.social_auth_backend.FIWAREOAuth2` to `AUTHENTICATION_BACKENDS`. example: +1. Install the `social-auth-app-django` module (e.g. `pip install "social-auth-app-django"`) + +2. Edit `settings.py`: + +- Remove `wirecloud.oauth2provider` from `INSTALLED_APPS` +- Add `social_django` to `INSTALLED_APPS` +- Add `wirecloud.fiware.social_auth_backend.FIWAREOAuth2` to `AUTHENTICATION_BACKENDS`. example: ```python AUTHENTICATION_BACKENDS = ( @@ -922,8 +921,9 @@ AUTHENTICATION_BACKENDS = ( > `django.contrib.auth.backends.ModelBackend` in `AUTHENTICATION_BACKENDS`, although this will require extra > configuration not documented in this guide. -- Add a `FIWARE_IDM_SERVER` setting pointing to the IdM server to use (e.g. + - Add a `FIWARE_IDM_SERVER` setting pointing to the IdM server to use (e.g. `FIWARE_IDM_SERVER = "https://account.lab.fiware.org"`) + - Add `SOCIAL_AUTH_FIWARE_KEY` and `SOCIAL_AUTH_FIWARE_SECRET` settings using the _Client ID_ and the _Client Secret_ values provided by the IdM. You should end having something like this: @@ -932,22 +932,24 @@ SOCIAL_AUTH_FIWARE_KEY = "43" SOCIAL_AUTH_FIWARE_SECRET = "a6ded8771f7438ce430dd93067a328fd282c6df8c6c793fc8225e2cf940f746e6b229158b5e3828e2716b915d2c4762a34219e1792b85e4d3cdf66d70d72840b" ``` -- Edit `urls.py`: +3. Edit `urls.py`: - - Replace the login endpoint: - - Add the following import line at the beginning of the file: - `from wirecloud.fiware import views as wc_fiware` - - Remove: `url(r'^login/?$', django_auth.login, name="login"),` - - Add: `url(r'^login/?$', wc_fiware.login, name="login"),` - - Add `social-auth-app-django` url endpoints at the end of the pattern list: - `url('', include('social_django.urls', namespace='social')),` +- Replace the login endpoint: + - Add the following import line at the beginning of the file: + `from wirecloud.fiware import views as wc_fiware` + - Remove: `url(r'^login/?$', django_auth.login, name="login"),` + - Add: `url(r'^login/?$', wc_fiware.login, name="login"),` +- Add `social-auth-app-django` url endpoints at the end of the pattern list: + `url('', include('social_django.urls', namespace='social')),` -- [Optional]: Change the `THEME_ACTIVE` setting to `wirecloud.fiwarelabtheme`. This theme is the one used by the +4. [Optional]: Change the `THEME_ACTIVE` setting to `wirecloud.fiwarelabtheme`. This theme is the one used by the FIWARE Lab's Mashup portal. -- [Optional]: Provide a [`FIWARE_PORTALS` setting](#fiware_portals). This setting is used for signing out from other + +5. [Optional]: Provide a [`FIWARE_PORTALS` setting](#fiware_portals). This setting is used for signing out from other portals at the same time the user sign out from WireCloud, providing a single sign out experience. This setting is also used for building the navigation bar. -- Run `python manage.py migrate; python manage.py collectstatic --noinput` + +6. Run `python manage.py migrate; python manage.py collectstatic --noinput` [keyrock's user and programmers guide]: https://fi-ware-idm.readthedocs.org/en/latest/user_guide/#registering-an-application @@ -959,14 +961,15 @@ WireCloud 1.0 adds experimental support for real time synchronization through we The steps for enabling this support are the following: -- Install [Django channels](https://channels.readthedocs.io/en/latest/): +1. Install [Django channels](https://channels.readthedocs.io/en/latest/): ```bash pip install channels ``` -- Add `channels` and `wirecloud.live` into the `INSTALLED_APPS` setting in the `settings.py` file. -- Configure the channels framework by configuring the `CHANNEL_LAYERS` setting. For example, you can make use of the +2. Add `channels` and `wirecloud.live` into the `INSTALLED_APPS` setting in the `settings.py` file. + +3. Configure the channels framework by configuring the `CHANNEL_LAYERS` setting. For example, you can make use of the following configuration: ```python @@ -1305,9 +1308,8 @@ If the error is similar to the following one: check that you python installation is correctly configured (using the python interpreter used for running WireCloud): ```bash -$ python -``` -```text +python + Python 2.7.6 (default, Nov 13 2013, 20:19:29) [GCC 4.2.1 Compatible Apple LLVM 5.0 (clang-500.2.79)] on darwin Type "help", "copyright", "credits" or "license" for more information. @@ -1422,9 +1424,7 @@ It should show something similar to the following: ```bash ps -ewF | grep 'apache2\|postgres' | grep -v grep -``` -```text postgres 1631 1 0 25212 9452 0 Jul03 ? 00:00:19 /usr/lib/postgresql/9.1/bin/postgres -D /var/lib/postgresql/9.1/main -c config_file=/etc/postgresql/9.1/main/postgresql.conf postgres 1702 1631 0 25208 3784 0 Jul03 ? 00:00:47 postgres: writer process postgres 1703 1631 0 25208 1452 0 Jul03 ? 00:00:39 postgres: wal writer process From 811dbf4f5fe1461995fe4068f3eb1177b0e488e7 Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Tue, 26 Mar 2019 15:12:05 +0000 Subject: [PATCH 3/4] Remove superfences and codehilite --- mkdocs.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index b4663ac925..a85f0d49d0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -33,7 +33,6 @@ markdown_extensions: - pymdownx.betterem - pymdownx.tilde: subscript: False -# - pymdownx.superfences - pymdownx.magiclink: repo_url_shortener: True repo_url_shorthand: True @@ -41,8 +40,6 @@ markdown_extensions: user: "Wirecloud" repo: "wirecloud" - pymdownx.tasklist -# - codehilite: -# guess_lang: False - toc: permalink: True separator: "-" From 5014013b25a143f7ba5501f03bd70ca2e3060c5c Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Tue, 26 Mar 2019 18:32:25 +0000 Subject: [PATCH 4/4] Remove split --- docs/installation_guide.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/installation_guide.md b/docs/installation_guide.md index bc9b44dd0e..20ed831739 100644 --- a/docs/installation_guide.md +++ b/docs/installation_guide.md @@ -498,14 +498,12 @@ following: ```bash python manage.py createsuperuser -``` -```text - Username (leave blank to use 'wirecloud'): admin - Email address: admin@myemaildomain.com - Password: ***** (admin) - Password (again): ***** (admin) - Superuser created successfully. +Username (leave blank to use 'wirecloud'): admin +Email address: admin@myemaildomain.com +Password: ***** (admin) +Password (again): ***** (admin) +Superuser created successfully. ``` WireCloud 1.0 added some predefined dashboards, so you have to create them by running the following command: