Metawidget 3.2 to 3.3 Migration Guide

The next release of Metawidget (v3.3) contains some breaking changes. We apologise for the disruption and provide this Migration Guide to help in moving from v3.2 to v3.3. All of the existing documentation and examples have already been migrated, as a reference point.

Migrate JavaScript Metawidgets to JSON Schema

The three existing JavaScript Metawidgets (AngularJS, JQueryUI and pure JavaScript) have migrated to using JSON Schema internally. This change was made because:

• JSON Schema is a lightweight, extensible standard that fits nicely with Metawidget
• Metawidget's proprietary, internal format was already close to JSON Schema
• adopting a standard has knock-on benefits - not least interoperability and documentation

Although beneficial, this migration has affected some code. First, the format returned by the existing Inspector and InspectionResultProcessor interfaces used to be an array of objects. For example:

[ { "name": "root", "_root": "true" }, { "name": "prop1", "required": "true" }, { "name": "prop2", "large": "true" } ]

Under JSON Schema this becomes an object with a properties sub-object:

{ "name": "root", properties: { "prop1": { "required": "true" }, "prop2": { "large": "true" } } }

Second, an additional parameter elementName has been added to the WidgetBuilder, WidgetProcessor and Layout interfaces:

function buildWidget( elementName, attributes, mw ) { ... }
function processWidget( widget, elementName, attributes, mw ) { ... }
function layout( widget, elementName, attributes, mw ) { ... }

This parameter can take the values entity, property or action and helps distinguish 'root' properties from child properties. It is also more consistent with the Java-based Metawidget. Third, some metadata names have been migrated to JSON Schema:

label -> title
lookup -> enum
lookupLabels -> enumTitles
minimumValue -> minimum
maximumValue -> maximum
minimumLength -> minLength
maximumLength -> maxLength

Finally, metawidget.util.combineInspectionResults no longer returns anything (it just modifies the parameters you give it).

Migrate to Vaadin 7

The Vaadin 7 API breaks compatibilty with previous versions. We have moved the existing VaadinMetawidget to a different artifactId metawidget-vaadin6 and will be starting work on a Vaadin 7-compatible Metawidget for future releases.

Feedback welcome!