Metawidget 0.85 to 0.9 Migration Guide

The next release of Metawidget (v0.9) continues the refactoring work of v0.85. As such, there will be some breaking changes. We apologise for this disruption and provide this Migration Guide to help in moving from v0.85 to v0.9. All of the existing documentation and examples have already been migrated, as a reference point.

LayoutDecorators

The layout interface has been changed slightly to introduce the concept of LayoutDecorators. This allows inner layouts to be 'decorated' with outer layouts.

For example, you can decorate a GridBagLayout with a TabbedPaneLayoutDecorator to add tabs around sections. Previously this functionality was 'baked in' to GridBagLayout itself, and duplicated in other places such as MigLayout. Breaking it out allows easier maintenance, plus we can beef up the decorators themselves. For example, TabbedPaneLayoutDecorator now supports configuring tab alignment.

You can also nest LayoutDecorators in interesting ways. For example...

<tabbedPaneLayoutDecorator xmlns="java:org.metawidget.swing.layout"
   config="TabbedPaneLayoutDecoratorConfig">
   <layout>
      <tabbedPaneLayoutDecorator config="TabbedPaneLayoutDecoratorConfig">
         <layout>
            <gridBagLayout />
         </layout>
      </tabbedPaneLayoutDecorator>
   </layout>
</tabbedPaneLayoutDecorator>

...gives (ie. nested tabs)...

...whereas...

<separatorLayoutDecorator xmlns="java:org.metawidget.swing.layout"
   config="SeparatorLayoutDecoratorConfig">
   <layout>
      <tabbedPaneLayoutDecorator config="TabbedPaneLayoutDecoratorConfig">
         <layout>
            <gridBagLayout />
         </layout>
      </tabbedPaneLayoutDecorator>
   </layout>
</separatorLayoutDecorator>

...gives (ie. tabs inside a separator)...

...and finally...

<tabbedPaneLayoutDecorator xmlns="java:org.metawidget.swing.layout"
   config="TabbedPaneLayoutDecoratorConfig">
   <layout>
      <separatorLayoutDecorator config="SeparatorLayoutDecoratorConfig">
         <layout>
            <gridBagLayout />
         </layout>
      </separatorLayoutDecorator>
   </layout>
/tabbedPaneLayoutDecorator>

...gives (ie. separators inside a tab)...

Another advantage of this approach is you can decorate widgets from one widget library with widgets from another: LayoutDecorators allows mixing layouts in the same way CompositeWidgetBuilder allows mixing widgets. For example, you can use JSF's SimpleLayout but decorate it with tabs using RichFaces' TabPanelLayoutDecorator:


InspectionResultProcessors

There is now a new stage in the pipeline for processing the inspection result after the Inspectors but prior to the WidgetBuilders. Existing functionality (such as sorting by comes-after) has been moved into here, but it also opens the door for custom implementations.

In particular, it allows sorting and/or including/excluding names based on a UI parameter. For example:

<m:metawidget value="#{foo}" fields="name,age,retired"/>

We don't necessarily recommend this approach (it requires hard-coding field names so won't refactor well) but it has been a common request.

OverridenWidgetBuilder

Previously widgets were overridden by adding child widgets (with appropriate names) inside the Metawidget. This mechanism has now been factored out into an OverridenWidgetBuilder so that custom implementations can be plugged in instead if desired. Alternatively, you can remove the overridden mechanism entirely.

ReadOnlyWidgetBuilder

Previously all WidgetBuilders had two code paths: one for read-only widgets and one for non-read-only (or 'active') widgets. This has been factored out into a separate ReadOnlyWidgetBuilder so that custom implementations can be plugged in instead if desired. Alternatively, you can remove the read-only mechanism entirely.