Widgets

Widgets

Widgets are high-level abstractions, pieces using which Pages are built.

From developer's view widget is a directory located in resources and called WIDGET_NAME where WIDGET_NAME is widget's unique name. It should have the following layout:

• widget.json (required, contains the most important descriptional information about widget. Example for summator widget:

{
    "description": "Description of widget \"summator\"",
    "schema": {
      "type": "object",
      "title": "Summator settings",
      "properties": {
        "title": {
          "type": "string",
          "title": "Widget title"
        },
        "a": {
          "type": "integer",
          "title": "Default value for first input"
        },
        "b": {
          "type": "integer",
          "title": "Default value for second input"
        },
        "aDisabled": {
          "type": "boolean",
          "title": "Should first field be disabled?"
        }
      }
    }
  }

• widget.html (optional)
• widget.js (optional)
• icon.png (optional small icon)
• screenshots/ (optional directory with screenshot examples)
• bower.json (not designed as for now, implementation should be delayed).

Uploading

When the widget archive is uploaded using PUT-request to address /widgets/WIDGET_NAME it should be unzipped into /resources/widgets/WIDGET_NAME. All files should be checked to be safe (there should be a whitelist of allowed file extensions: image files, text files, *.js, *.css, *.html, *.txt files and probably a few others. Java code uploading should be strictly prohibited!

After the widget was uploaded and put in it's directory gulp build task should be invoked. gulp build's logic should be extended with merging widget's widget.json into single resources/widgets/widgets.json in the following way:

• new properties are added to the widget.json's JOSN-object: nohtml: true if there is no widget.html file, widget.js if there is no main JS file, noicon: true, if there is no icon.

Example for title widget. Original

  {
    "description": "Description of widget \"title\"",
    "schema": {
      "type": "object",
      "title": "Title widget",
      "properties": {
        "title": {
          "title": "Set title",
          "type": "string"
        }
      }
    }
  }

Resulting:

  {
    "description": "Description of widget \"title\"",
    "nojs": true,
    "schema": {
      "type": "object",
      "title": "Title widget",
      "properties": {
        "title": {
          "title": "Set title",
          "type": "string"
        }
      }
    }
  }

• widget.json's JSON object is wrapped into another JSON object like this: { "WIDGET_NAME": OLD_JSON_OBJECT } Next result:

{
  "title": {
    "description": "Description of widget \"title\"",
    "nojs": true,
    "schema": {
      "type": "object",
      "title": "Title widget",
      "properties": {
        "title": {
          "title": "Set title",
          "type": "string"
        }
      }
    }
  }
}

• resulting json is merged with existing JSON-object located in widgets.json with the logic identical to (angular.merge or jQuery.extend). See resources/widgets/widgets.json for example.

All the paths are relative to src/main/webapp.