Metawidget User Guide and Reference Documentation

Metawidget is an Object/User Interface Mapping tool (OIM), so first we need an object to map from - the O in OIM. Create a class in your project called Person with the following code:

package com.myapp;

public class Person {
	private String	mName;
	private int		mAge;
	private boolean	mRetired;

	public String getName() { return mName; }
	public void setName( String name ) { mName = name; }

	public int getAge() { return mAge; }
	public void setAge( int age ) { mAge = age; }

	public boolean isRetired() { return mRetired; }
	public void setRetired( boolean retired ) { mRetired = retired; }
}

Next we need a User Interface framework - the I in OIM. Create a class in your project called Main with the following code:

package com.myapp;

import javax.swing.*;
import org.metawidget.swing.*;

public class Main {

	public static void main( String[] args ) {
		Person person = new Person();
		
		SwingMetawidget metawidget = new SwingMetawidget();
		metawidget.setToInspect( person );
		
		JFrame frame = new JFrame( "Metawidget Tutorial" );
		frame.setDefaultCloseOperation( JFrame.EXIT_ON_CLOSE );
		frame.getContentPane().add( metawidget );
		frame.setSize( 400, 250 );
		frame.setVisible( true );
	}
}

	Note
	Many IDEs include visual UI builders for dragging and dropping widgets. Metawidget integrates with these tools and Metawidgets can be dragged and dropped like any other. As we shall see, however, Metawidget widgets automatically fill themselves with child widgets at runtime, saving significant development time.

If you're using an IDE, such as NetBeans, your project should look something like pictured in Figure 1.1.

Figure 1.1. Metawidget tutorial in NetBeans IDE

Run the code. You should see the screen in Figure 1.2.

Figure 1.2. SwingMetawidget rendering of Person class

The SwingMetawidget has automatically populated itself with child widgets at runtime. It has chosen JSpinner, JTextField and JCheckBox widgets based on the types of the properties of the Person class. This is the First Goal Of Metawidget:

	First Goal Of Metawidget
	Metawidget creates UI widgets by inspecting existing architectures

By default, SwingMetawidget has laid out the JComponents using java.awt.GridBagLayout. Try resizing the window, and the JComponents will resize with it. If you've ever tried using java.awt.GridBagLayout yourself, either through code or a visual UI builder, you'll know how fiddly it can be. Having Metawidget do it for you is a real time-saver.

Clearly this is not a complete UI. There are no Save or Cancel buttons, for example, and the JComponents appear uncomfortably tight to the left, top and right edges of the JFrame. This is explained by the Second Goal Of Metawidget:

	Second Goal Of Metawidget
	Metawidget does not try to 'own' the entire UI - it focuses on creating native sub-widgets for slotting into existing UIs

You slot Metawidget alongside your standard UI components, often combining several Metawidgets on the same screen. We'll see how this works later.

Currently the name, age and retired properties are arranged alphabetically in the UI - their order does not match the way they are defined in the Person class. This is because property ordering information is not retained within Java class files (as per the Java Language Specification).

To correct this, Metawidget needs to gather additional information. There are several ways to do this (i.e. you don't have to use annotations), but the simplest for now is to use the built-in Metawidget annotation @UiComesAfter.

Annotate the Person class as shown below (lines to add are highlighted):

package com.myapp;

import org.metawidget.inspector.annotation.*;

public class Person {
	private String	mName;
	private int		mAge;
	private boolean	mRetired;

	public String getName() { return mName; }
	public void setName( String name ) { mName = name; }

	@UiComesAfter( "name" ) 
	public int getAge() { return mAge; }
	public void setAge( int age ) { mAge = age; }

	@UiComesAfter( "age" )
	public boolean isRetired() { return mRetired; }
	public void setRetired( boolean retired ) { mRetired = retired; }
}

Run the code again. This time the properties appear in the correct order:

Figure 1.3. Properties in correct order

Introducing new annotations to improve the UI is not really in the spirit of the First Goal Of Metawidget. We'd much rather improve it by gathering information from existing sources. To demonstrate, we'll need an external source of metadata. Create a file called metawidget-metadata.xml in the same folder as your Main class:

<inspection-result xmlns="http://metawidget.org/inspection-result"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	version="1.0"	
	xsi:schemaLocation="http://metawidget.org/inspection-result
		http://metawidget.org/xsd/inspection-result-1.0.xsd">

	<entity type="com.myapp.Person">
		<property name="name"/>
		<property name="age"/>
		<property name="retired"/>
	</entity>

</inspection-result>

To recognise the XML file, Metawidget needs to use a different Inspector. Metawidget comes with multiple Inspectors, each targeting different sources of information. Change the Main class to use an XmlInspector (lines to add are highlighted):

package com.myapp;

import javax.swing.*;
import org.metawidget.inspector.xml.*;
import org.metawidget.swing.*;

public class Main {

	public static void main( String[] args ) {
		Person person = new Person();
		
		SwingMetawidget metawidget = new SwingMetawidget();
		XmlInspectorConfig config = new XmlInspectorConfig();
		config.setInputStream( Main.class.getResourceAsStream( "metawidget-metadata.xml" ));
		metawidget.setInspector( new XmlInspector( config ) );
		metawidget.setToInspect( person );
		
		JFrame frame = new JFrame( "Metawidget Tutorial" );
		frame.setDefaultCloseOperation( JFrame.EXIT_ON_CLOSE );
		frame.getContentPane().add( metawidget );
		frame.setSize( 400, 250 );
		frame.setVisible( true );
	}
}

Then remove all annotations from the Person class:

package com.myapp;

public class Person {
	private String	mName;
	private int		mAge;
	private boolean	mRetired;

	public String getName() { return mName; }
	public void setName( String name ) { mName = name; }

	public int getAge() { return mAge; }
	public void setAge( int age ) { mAge = age; }

	public boolean isRetired() { return mRetired; }
	public void setRetired( boolean retired ) { mRetired = retired; }
}

Run the code again. It does not yield the correct result - the properties appear in the correct order, but the JSpinner and JCheckBox are now JTextFields! What happened?

Figure 1.4. Correct property order, but wrong JComponents

Metawidget Inspectors are very targeted in what they inspect. XmlInspector looks for metadata from XML files - but it does not look for anything else, such as JavaBean property types. Before we explicitly specified an XmlInspector, Metawidget had been implictly using two Inspectors for us, called PropertyTypeInspector and MetawidgetAnnotationInspector.

What we need is to combine the results of PropertyTypeInspector, MetawidgetAnnotationInspector and XmlInspector before returning them to SwingMetawidget. We do this using CompositeInspector:

package com.myapp;

import javax.swing.*;
import org.metawidget.inspector.annotation.*;
import org.metawidget.inspector.composite.*;
import org.metawidget.inspector.propertytype.*;
import org.metawidget.inspector.xml.*;
import org.metawidget.swing.*;

public class Main {

	public static void main( String[] args ) {
		Person person = new Person();
		
		SwingMetawidget metawidget = new SwingMetawidget();
		XmlInspectorConfig config = new XmlInspectorConfig();
		config.setInputStream( Main.class.getResourceAsStream( "metawidget-metadata.xml" ));		
		CompositeInspectorConfig inspectorConfig = new CompositeInspectorConfig().setInspectors(
			new XmlInspector( config ),
			new PropertyTypeInspector(),
			new MetawidgetAnnotationInspector() );
		metawidget.setInspector( new CompositeInspector( inspectorConfig ) );
		metawidget.setToInspect( person );
		
		JFrame frame = new JFrame( "Metawidget Tutorial" );
		frame.setDefaultCloseOperation( JFrame.EXIT_ON_CLOSE );
		frame.getContentPane().add( metawidget );
		frame.setSize( 400, 250 );
		frame.setVisible( true );
	}
}

Run the code again. This time properties appear both in the correct order and using the correct JComponent:

Figure 1.5. Using multiple inspectors

This idea of combining multiple Inspectors to inspect different characteristics of your existing architecture is very powerful. Metawidget comes with pre-written Inspectors for many different technologies - from JPA and Hibernate Validator annotations, to struts-config.xml configuration files, to Groovy and Scala properties. There is a lot of metadata already lurking in back-end systems - it just needs extracting. For example, JpaInspector understands this...

import javax.persistence.Column;

public class Person {
	@Column( nullable = false )
	public String getName() { ... };
}

...denotes name is a required property (could be rendered with an asterisk after it in the UI). Equally, PropertyTypeInspector understands that...

public class Person {
	private String mName;
	
	public String getName() {
		return mName;
	}
	
	// No setter
}

...signifies name is a read-only property (could be rendered as a label in the UI).

There are several ways to control the layout of the components. To demonstrate, Try adding the following properties to the Person class:

package com.myapp;

import org.metawidget.inspector.annotation.*;

public class Person {

	public enum Gender { Male, Female }
	
	private String	mName;
	private int		mAge;
	private boolean	mRetired;
	private Gender	mGender;
	private String	mNotes;
	private String	mEmployer;
	private String	mDepartment;
	
	public String getName() { return mName; }
	public void setName( String name ) { mName = name; }

	public int getAge() { return mAge; }
	public void setAge( int age ) { mAge = age; }

	public boolean isRetired() { return mRetired; }
	public void setRetired( boolean retired ) { mRetired = retired; }

	@UiComesAfter( "retired" ) 
	public Gender getGender() { return mGender; }
	public void setGender( Gender gender ) { mGender = gender; }

	@UiComesAfter( "gender" )
	@UiLarge
	public String getNotes() { return mNotes; }
	public void setNotes( String notes ) { mNotes = notes; }

	@UiComesAfter( "notes" )
	@UiSection( "Work" )
	public String getEmployer() { return mEmployer; }
	public void setEmployer( String employer ) { mEmployer = employer; }

	@UiComesAfter( "employer" )
	public String getDepartment() { return mDepartment; }
	public void setDepartment( String department ) { mDepartment = department; }
}

This code produces the screen in Figure 1.6. Annotations have been used to define section headings and 'large' properties (i.e. a JTextArea).

Figure 1.6. Additional properties and a section heading

	Note
	For a list of all the annotations MetawidgetAnnotationInspector recognises, see Section 4.3.7, “MetawidgetAnnotationInspector”.

By default, SwingMetawidget lays out JComponents using org.metawidget.swing.layout.GridBagLayout. You can configure this layout, or swap it for a different layout, using SwingMetawidget.setMetawidgetLayout. Modify the code to use a GridBagLayout with 2 columns:

package com.myapp;

import javax.swing.*;
import org.metawidget.inspector.annotation.*;
import org.metawidget.inspector.composite.*;
import org.metawidget.inspector.propertytype.*;
import org.metawidget.inspector.xml.*;
import org.metawidget.swing.*;
import org.metawidget.swing.layout.*;

public class Main {

	public static void main( String[] args ) {
		Person person = new Person();
		
		SwingMetawidget metawidget = new SwingMetawidget();
		XmlInspectorConfig config = new XmlInspectorConfig();
		config.setInputStream( Main.class.getResourceAsStream( "metawidget-metadata.xml" ));		
		CompositeInspectorConfig inspectorConfig = new CompositeInspectorConfig().setInspectors(
			new XmlInspector( config ),
			new PropertyTypeInspector(),
			new MetawidgetAnnotationInspector() );
		metawidget.setInspector( new CompositeInspector( inspectorConfig ) );
		GridBagLayoutConfig nestedLayoutConfig = new GridBagLayoutConfig().setNumberOfColumns( 2 ); 
		SeparatorLayoutDecoratorConfig layoutConfig = new SeparatorLayoutDecoratorConfig().setLayout(
			new org.metawidget.swing.layout.GridBagLayout( nestedLayoutConfig ));
		metawidget.setMetawidgetLayout( new SeparatorLayoutDecorator( layoutConfig ));
		metawidget.setToInspect( person );
		
		JFrame frame = new JFrame( "Metawidget Tutorial" );
		frame.setDefaultCloseOperation( JFrame.EXIT_ON_CLOSE );
		frame.getContentPane().add( metawidget );
		frame.setSize( 400, 250 );
		frame.setVisible( true );
	}
}

Run the code. The JComponents are now arranged across two columns:

Figure 1.7. A two-column layout

You may have noticed the GridBagLayout is nested inside a SeparatorLayoutDecorator. This is responsible for separating widgets in different sections using JSeparators. However there are other choices for separating widgets. Modify the code to use TabbedPaneLayoutDecorator instead:

package com.myapp;

import javax.swing.*;
import org.metawidget.inspector.annotation.*;
import org.metawidget.inspector.composite.*;
import org.metawidget.inspector.propertytype.*;
import org.metawidget.inspector.xml.*;
import org.metawidget.swing.*;
import org.metawidget.swing.layout.*;

public class Main {

	public static void main( String[] args ) {
		Person person = new Person();
		
		SwingMetawidget metawidget = new SwingMetawidget();
		XmlInspectorConfig config = new XmlInspectorConfig();
		config.setInputStream( Main.class.getResourceAsStream( "metawidget-metadata.xml" ));		
		CompositeInspectorConfig inspectorConfig = new CompositeInspectorConfig().setInspectors(
			new XmlInspector( config ),
			new PropertyTypeInspector(),
			new MetawidgetAnnotationInspector() );
		metawidget.setInspector( new CompositeInspector( inspectorConfig ) );
		GridBagLayoutConfig nestedLayoutConfig = new GridBagLayoutConfig().setNumberOfColumns( 2 ); 
		TabbedPaneLayoutDecoratorConfig layoutConfig = new TabbedPaneLayoutDecoratorConfig().setLayout(
			new org.metawidget.swing.layout.GridBagLayout( nestedLayoutConfig ));
		metawidget.setMetawidgetLayout( new TabbedPaneLayoutDecorator( layoutConfig ));
		metawidget.setToInspect( person );
		
		JFrame frame = new JFrame( "Metawidget Tutorial" );
		frame.setDefaultCloseOperation( JFrame.EXIT_ON_CLOSE );
		frame.getContentPane().add( metawidget );
		frame.setSize( 400, 250 );
		frame.setVisible( true );
	}
}

Run the code. The section heading is now a JTabbedPane:

Figure 1.8. Two-column layout with a JTabbedPane

Again, if you've ever used java.awt.GridBagLayout by hand, you'll appreciate how much easier Metawidget makes it to apply consistent layouts across all screens of your application.

There are several ways to control widget creation. One way is to drop child controls inside the SwingMetawidget. This approach works well both programmatically within code and within visual UI builders.

Modify the code to add a JComboBox to the Metawidget:

package com.myapp;

import javax.swing.*;
import org.metawidget.inspector.annotation.*;
import org.metawidget.inspector.composite.*;
import org.metawidget.inspector.propertytype.*;
import org.metawidget.inspector.xml.*;
import org.metawidget.swing.*;
import org.metawidget.swing.layout.*;

public class Main {

	public static void main( String[] args ) {
		Person person = new Person();
		
		SwingMetawidget metawidget = new SwingMetawidget();
		XmlInspectorConfig config = new XmlInspectorConfig();
		config.setInputStream( Main.class.getResourceAsStream( "metawidget-metadata.xml" ));		
		CompositeInspectorConfig inspectorConfig = new CompositeInspectorConfig().setInspectors(
			new XmlInspector( config ),
			new PropertyTypeInspector(),
			new MetawidgetAnnotationInspector() );
		metawidget.setInspector( new CompositeInspector( inspectorConfig ) );
		GridBagLayoutConfig nestedLayoutConfig = new GridBagLayoutConfig().setNumberOfColumns( 2 ); 
		TabbedPaneLayoutDecoratorConfig layoutConfig = new TabbedPaneLayoutDecoratorConfig().setLayout(
			new org.metawidget.swing.layout.GridBagLayout( nestedLayoutConfig ));
		metawidget.setMetawidgetLayout( new TabbedPaneLayoutDecorator( layoutConfig ));
		metawidget.setToInspect( person );
		JComboBox combo = new JComboBox();
		combo.setName( "retired" );
		metawidget.add( combo );
		
		JFrame frame = new JFrame( "Metawidget Tutorial" );
		frame.setDefaultCloseOperation( JFrame.EXIT_ON_CLOSE );
		frame.getContentPane().add( metawidget );
		frame.setSize( 400, 250 );
		frame.setVisible( true );
	}
}

Run the code. The JComboBox appears in place of the retired JCheckBox, because it has the same name (i.e. 'retired') as Metawidget would have given the JCheckbox:

Figure 1.9. The 'retired' property has been overridden

	Note
	The default algorithm looks for child controls with the same name, but you can plug in your own implementation if you need to. See Section 2.4.5, “OverriddenWidgetBuilder”.

To suppress a widget's creation entirely, simply supplying an empty JPanel named 'retired' will not work as Metawidget will still create an accompanying label in the left hand column. Instead, Metawidget includes special Stub widgets for this purpose:

package com.myapp;

import javax.swing.*;
import org.metawidget.inspector.annotation.*;
import org.metawidget.inspector.composite.*;
import org.metawidget.inspector.propertytype.*;
import org.metawidget.inspector.xml.*;
import org.metawidget.swing.*;

public class Main {

	public static void main( String[] args ) {
		Person person = new Person();
		
		SwingMetawidget metawidget = new SwingMetawidget();
		XmlInspectorConfig config = new XmlInspectorConfig();
		config.setInputStream( Main.class.getResourceAsStream( "metawidget-metadata.xml" ));		
		CompositeInspectorConfig inspectorConfig = new CompositeInspectorConfig().setInspectors(
			new XmlInspector( config ),
			new PropertyTypeInspector(),
			new MetawidgetAnnotationInspector() );
		metawidget.setInspector( new CompositeInspector( inspectorConfig ) );
		GridBagLayoutConfig nestedLayoutConfig = new GridBagLayoutConfig().setNumberOfColumns( 2 ); 
		TabbedPaneLayoutDecoratorConfig layoutConfig = new TabbedPaneLayoutDecoratorConfig().setLayout(
			new org.metawidget.swing.layout.GridBagLayout( nestedLayoutConfig ));
		metawidget.setMetawidgetLayout( new TabbedPaneLayoutDecorator( layoutConfig ));
		metawidget.setToInspect( person );
		metawidget.add( new Stub( "retired" ));
		
		JFrame frame = new JFrame( "Metawidget Tutorial" );
		frame.setDefaultCloseOperation( JFrame.EXIT_ON_CLOSE );
		frame.getContentPane().add( metawidget );
		frame.setSize( 400, 250 );
		frame.setVisible( true );
	}
}

Run the code. The retired property and its label will not appear:

Figure 1.10. The 'retired' property has been suppressed

Another way is to use a @UiHidden annotation on the business class:

package com.myapp;

import org.metawidget.inspector.annotation.*;

public class Person {

	public enum Gender { Male, Female }
	
	private String	mName;
	private int		mAge;
	private boolean	mRetired;
	private Gender	mGender;
	private String	mNotes;
	private String	mEmployer;
	private String	mDepartment;
	
	public String getName() { return mName; }
	public void setName( String name ) { mName = name; }

	public int getAge() { return mAge; }
	public void setAge( int age ) { mAge = age; }

	@UiHidden
	public boolean isRetired() { return mRetired; }
	public void setRetired( boolean retired ) { mRetired = retired; }

	@UiComesAfter( "retired" )
	public Gender getGender() { return mGender; }
	public void setGender( Gender gender ) { mGender = gender; }

	@UiComesAfter( "gender" )
	@UiLarge
	public String getNotes() { return mNotes; }
	public void setNotes( String notes ) { mNotes = notes; }

	@UiComesAfter( "notes" )
	@UiSection( "Work" )
	public String getEmployer() { return mEmployer; }
	public void setEmployer( String employer ) { mEmployer = employer; }

	@UiComesAfter( "employer" )
	public String getDepartment() { return mDepartment; }
	public void setDepartment( String department ) { mDepartment = department; }
}

In both cases, org.metawidget.swing.layout.GridBagLayout is smart enough to always give large JComponents like notes the full width of the JFrame.

So far we have been instantiating our Inspectors and Layouts in Java code. Whilst this approach is possible for all Inspectors and Layouts, many UI frameworks employ visual UI builders or intermediate languages (such as JSP) that make getting to the Java code cumbersome (i.e. you have to derive custom widgets).

As an alternative, Metawidget supports external XML configuration. Create a file called metawidget.xml in the same folder as your Main class:

<metawidget xmlns="http://metawidget.org"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	version="1.0"
	xsi:schemaLocation="http://metawidget.org http://metawidget.org/xsd/metawidget-1.0.xsd">

	<swingMetawidget xmlns="java:org.metawidget.swing">		
		<inspector>
			<compositeInspector xmlns="java:org.metawidget.inspector.composite"
				config="CompositeInspectorConfig">
				<inspectors>
					<array>
						<xmlInspector xmlns="java:org.metawidget.inspector.xml" config="XmlInspectorConfig">
							<inputStream>
								<resource>com/myapp/metawidget-metadata.xml</resource>
							</inputStream>
						</xmlInspector>
						<propertyTypeInspector xmlns="java:org.metawidget.inspector.propertytype"/>
						<metawidgetAnnotationInspector xmlns="java:org.metawidget.inspector.annotation" />
					</array>
				</inspectors>
			</compositeInspector>
		</inspector>
		<metawidgetLayout>
			<tabbedPaneLayoutDecorator xmlns="java:org.metawidget.swing.layout"
				config="TabbedPaneLayoutDecoratorConfig">
				<layout>
					<gridBagLayout config="GridBagLayoutConfig">
						<numberOfColumns>
							<int>2</int>
						</numberOfColumns>
					</gridBagLayout>
				</layout>
			</tabbedPaneLayoutDecorator>
		</metawidgetLayout>	
	</swingMetawidget>

</metawidget>

Now update your Main class to use this file:

package com.myapp;

import javax.swing.*;
import org.metawidget.swing.*;

public class Main {

	public static void main( String[] args ) {
		Person person = new Person();

		SwingMetawidget metawidget = new SwingMetawidget();
		metawidget.setConfig( "com/myapp/metawidget.xml" );
		metawidget.setToInspect( person );

		JFrame frame = new JFrame( "Metawidget Tutorial" );
		frame.setDefaultCloseOperation( JFrame.EXIT_ON_CLOSE );
		frame.getContentPane().add( metawidget );
		frame.setSize( 400, 250 );
		frame.setVisible( true );
	}
}

Run the code. The output is the same as before, but this time we are configuring our Metawidget via external XML.

Visual UI builders can call SwingMetawidget.setConfig from the builder, with no coding required. Other UI frameworks (e.g. JSPs, Android) have similar 'code free' approaches (e.g. setting an attribute on a JSP tag, setting an attribute in an Android layout file) to setting the XML file. We shall look at these sorts of frameworks in Part 2.

Metawidget is an Object/User Interface Mapping tool (OIM), so first we need an object to map from - the O in OIM. Create a new HTML page in your project called index.html with the following code:

<!DOCTYPE html>
<html>
	<head>
		<script type="text/javascript">
			var person = {
				name: "Homer Simpson",
				age: 40,
				retired: false
			};
		</script>
	</head>
	<body>
	</body>
</html>

Next we need a User Interface - the I in OIM. Add the following code to your HTML page (lines to add are highlighted):

<!DOCTYPE html>
<html>
	<head>
		<script src="lib/metawidget/core/metawidget-core.min.js" type="text/javascript"></script>
		<script type="text/javascript">
			var person = {
				name: "Homer Simpson",
				age: 40,
				retired: false
			};
		</script>
	</head>
	<body>
		<div id="metawidget"></div>
		<script type="text/javascript">
			var mw = new metawidget.Metawidget( document.getElementById( 'metawidget' ));
			mw.toInspect = person;
			mw.buildWidgets();
		</script>
	</body>
</html>

You will also need to copy js/lib/metawidget/core/metawidget-core.min.js from the Metawidget binary distribution into your project.

Open your HTML page in your browser. You should see the page in Figure 1.11.

Figure 1.11. Metawidget rendering of person object

Metawidget has automatically populated the div with child widgets at runtime. It has chosen text, number and checkbox inputs based on the types of the properties of the person object. This is the First Goal Of Metawidget:

	First Goal Of Metawidget
	Metawidget creates UI widgets by inspecting existing architectures

By default, Metawidget has laid out the HTML input components using a table. This may not be your preferred approach, and either way this is clearly not a complete UI. There are no Save or Cancel buttons, for example. This is explained by the Second Goal Of Metawidget:

	Second Goal Of Metawidget
	Metawidget does not try to 'own' the entire UI - it focuses on creating native sub-widgets for slotting into existing UIs

You slot Metawidget alongside your standard UI components, often combining several Metawidgets on the same screen. We'll see how this works later.

Suppose we want the name property to be a required field. Such metadata cannot be represented using standard JavaScript Object Notation (JSON) so Metawidget needs a way to gather the additional information. There are several ways to do this, but the simplest for now is to add a custom Inspector (text to add is highlighted) that returns a JSON Schema:

var mw = new metawidget.Metawidget( document.getElementById( 'metawidget' ), {
	
	inspector: function( toInspect, type, names ) {

		return {
			properties: {
				name: {
					type: "string",
					required: true
				}
			}
		};
	}
} );

Refresh the page in your browser. It does not yield the correct result - the name property appears as a required field, but the age and retired properties have disappeared! What happened?

Figure 1.12. Name is required, but other properties are missing

Metawidget Inspectors are very targeted in what they inspect. Our custom Inspector returns information about name being a required field - but it does not return anything else, such as properties from our JSON object. Before we explicitly specified a new Inspector, Metawidget had been implictly using another Inspector for us, called PropertyTypeInspector.

What we need is to combine the results of PropertyTypeInspector and our custom Inspector before returning them to the Metawidget. We do this using CompositeInspector:

var mw = new metawidget.Metawidget( document.getElementById( 'metawidget' ), {
	
	inspector: new metawidget.inspector.CompositeInspector( [ new metawidget.inspector.PropertyTypeInspector(),
		function( toInspect, type, names ) {
		
				return {
					properties: {					
						name: {
							type: "string", 
							required: true
						}
					}
				};
			}
		}
	] )
} );

Refresh the page again. This time all properties appear and name is marked as a required field.

Figure 1.13. Using multiple inspectors

This idea of combining multiple Inspectors to inspect different characteristics of your existing architecture is very powerful. Metawidget comes with pre-written Inspectors for many different technologies and makes it easy to add your own, such as for REST services (see Section 5.5, “RestInspectionResultProcessor”). There is a lot of metadata already lurking in back-end systems - it just needs extracting.

There are several ways to control the layout of the components. To demonstrate, Try adding the following metadata for the person object:

function( toInspect, type, names ) {
		
	return {
		properties:
			name: {
				required: true
			},
			notes: {
				type: "string",
				large: true 
			},
			employer: {
				type: "string",
				section: "Work"
			},
			department: {
				type: "string"
			}
		}
	};
}

This produces the screen in Figure 1.14. Metadata has been added to define section headings and 'large' properties (i.e. a textarea).

Figure 1.14. Additional properties and a section heading

By default, Metawidget lays out components using an HTML table. You can configure this layout or swap it for a different one. Modify the code as follows:

var mw = new metawidget.Metawidget( document.getElementById( 'metawidget' ), {
	
	inspector: new metawidget.inspector.CompositeInspector( [ new metawidget.inspector.PropertyTypeInspector(),
		function( toInspect, type, names ) {
				
			return {
				properties:
					name: {
						required: true
					},
					notes: {
						type: "string",
						large: true
					},
					employer: {
						type: "string",
						section: "Work"
					},
					department: {
						type: "string"
					}
				}
			};
		} ] ),
		
	layout: new metawidget.layout.HeadingTagLayoutDecorator(
		new metawidget.layout.TableLayout( { numberOfColumns: 2 } ))
} );

Refresh the page. The components are now arranged across two columns:

Figure 1.15. A two-column layout

	Note
	Your browser may not have stretched the textarea across the full width of the table, even though the colspan has been set to 4. You can add <style>textarea { width: 100% }</style> into the head to confirm this visually

You may have noticed the TableLayout is nested inside a HeadingTagLayoutDecorator. This is responsible for separating widgets in different sections using h1 tags. However there are other choices for separating widgets. Modify the code to use a JQuery UI-based TabLayoutDecorator instead:

<!DOCTYPE html>
<html>
	<head>
		<script src="lib/metawidget/core/metawidget-core.min.js" type="text/javascript"></script>	
		<link rel="stylesheet" href="http://code.jquery.com/ui/1.9.2/themes/base/jquery-ui.css" />
		<script src="http://code.jquery.com/jquery-1.8.3.js"></script>
		<script src="http://code.jquery.com/ui/1.9.2/jquery-ui.js"></script>
		<script src="lib/metawidget/jquery-ui/metawidget-jqueryui.min.js" type="text/javascript"></script>
		<script type="text/javascript">
			var person = {
				name: "Homer Simpson",
				age: 40,
				retired: false
			};
		</script>
	</head>
	<body>
		<form>
			<div id="metawidget"></div>
		</form>
		<script type="text/javascript">
			var mw = new metawidget.Metawidget( document.getElementById( 'metawidget' ), {
				
				inspector: new metawidget.inspector.CompositeInspector( [ new metawidget.inspector.PropertyTypeInspector(),
					function( toInspect, type, names ) {
							
						return {
							properties:
								name: {
									required: true
								},
								notes: {
									type: "string",
									large: true
								},
								employer: {
									type: "string",
									section: "Work"
								},
								department: {
									type: "string"
								}
							}
						};
					} ] ),
					
				layout: new metawidget.jqueryui.layout.TabLayoutDecorator(
					new metawidget.layout.TableLayout( { numberOfColumns: 2 } ))
			} );		
			mw.toInspect = person;
			mw.buildWidgets();
		</script>
	</body>
</html>

You will also need to copy js/lib/metawidget/jquery-ui/metawidget-jqueryui.min.js from the Metawidget binary distribution into your project.

Refresh the page. The section heading is now a tab:

Figure 1.16. Two-column layout with a JQuery UI tab

Metawidget makes it easy to apply consistent layouts across all pages of your application.

There are several ways to control widget creation. One way is to add child controls inside the Metawidget:

<form>
	<div id="metawidget">
		<select id="retired">
			<option />
			<option>true</option>
			<option>false</option>
		</select>
	</div>
</form>

Refresh the page. The select box appears in place of the checkbox, because it has the same id (i.e. 'retired') as Metawidget would have given the checkbox. Notice Metawidget has still bound its value:

Figure 1.17. The 'retired' property has been overridden

	Note
	The default algorithm looks for child controls with the same id, but you can plug in your own implementation if you need to. See Section 2.4.5, “OverriddenWidgetBuilder”.

To suppress a widget's creation entirely, simply supplying an empty div with id 'retired' will not work as Metawidget will still create an accompanying label in the left hand column. Instead, Metawidget includes special stub widgets for this purpose:

<form>
	<div id="metawidget">
		<stub id="retired"></stub>
	</div>
</form>

Refresh the page. The retired property and its label will not appear:

Figure 1.18. The 'retired' property has been suppressed

Another way is to add a hidden attribute to the metadata:

function( toInspect, type, names ) {
	return {
		properties:
			name: {
				required: true
			},
			retired: {
				hidden: true
			},			
			notes: {
				type: "string",
				large: true
			},
			employer: {
				type: "string",
				section: "Work"
			},
			department: {
				type: "string"
			}
		}
	};
}

In both cases, metawidget.layout.TableLayout is smart enough to always give large components like textarea the full colspan of the table.

The Desktop Address Book is essentially a larger version of the application developed in Part 1 - it just has more domain objects and more widgets.

	Note
	If you are only interested in the JavaScript-based Metawidget, you should skip straight to Section 1.3.2, “Web Address Book”.

The application is pre-built for you in examples/swing/addressbook-swing.jar. This is a self-executing JAR. For convenience, it has MANIFEST.MF dependencies hard-coded into it, so it's best not to move it to a different folder (if you do, you'll need to manually fix up your CLASSPATH).

	Note
	There is also an SWT version of the Address Book sample in examples/swt/addressbook-swt.jar. You can mostly replace references to 'Swing' in this section with 'SWT' and follow along using SWT if preferred.

Run the code by navigating to the examples/swing folder and typing:

java -jar addressbook-swing.jar

The opening screen displays a search filter (at the top) and lists existing Address Book entries (at the bottom) as in Figure 1.19 (Swing version) and Figure 1.20 (SWT version).

Figure 1.19. Swing Desktop Address Book opening screen

Figure 1.20. SWT Desktop Address Book opening screen

The three search filter fields (Firstname, Surname and Type) are created by SwingMetawidget based on the ContactSearch business class. This includes populating the Type dropdown based on the ContactType enum. The Search, Add Personal Contact and Add Business Contact buttons are created by SwingMetawidget based on annotated action methods in the ContactDialog class. The rest of the screen - including the images, background and layout - are managed by regular Swing code and are not controlled by Metawidget: Metawidget does not try to 'own' the entire UI.

	Note
	Full source code for all the examples, such as the code for the ContactSearch, ContactType and ContactDialog classes, is included under the src/examples folder of the examples distribution.

Click Add Personal Contact. The screen displays a form for filling out Personal Contact information as in Figure 1.21.

Figure 1.21. Desktop Address Book 'Add Personal Contact' screen

All the form fields are created by SwingMetawidget based on the PersonalContact business class. This class is itself derived from the Contact business class. It includes some Metawidget annotations for dropdown values and section headings.

Note the code only has one JDialog class (ContactDialog), but is capable of supporting both PersonalContact and BusinessContact UIs. The fields in the UI change depending on the object passed to ContactDialog at runtime. This is the Third Goal Of Metawidget:

	Third Goal Of Metawidget
	Metawidget can perform inspection at runtime, detecting types and subtypes dynamically

The Address property is created as a nested SwingMetawidget. This is the default behaviour when Metawidget encounters datatypes it does not know how to represent using any other UI widget. The Communications property has been overridden with a manually specified JTable.

In addition, JTable.setCellEditor uses SwingMetawidget to render single JComponents as CellEditors. This includes automatically populating dropdown values.

Read-Only Mode

The Desktop Address Book uses Metawidget's setReadOnly(true) method to display read-only screens. Return to the main screen, and double-click on an existing contact (such as Homer Simpson). The same ContactDialog is used, but this time all the widgets are read-only labels as in Figure 1.22.

Figure 1.22. Desktop Address Book read-only mode

Click Edit. The labels are transformed into editable widgets by using Metawidget's setReadOnly(false), as in Figure 1.23.

Figure 1.23. Desktop Address Book edit mode

As there are a large number of Web application frameworks to choose from, this example comes written in nine of the most popular: AngularJS, Google Web Toolkit (GWT), Java Server Faces (JSF) 1.x and 2.x (using Facelets), Java Server Pages (JSP), JQuery Mobile, Spring Web MVC, Struts, Vaadin and Web Components. We recommend you follow along using the one most relevant to you.

Web-based applications are inherently more difficult to setup and run than desktop-based applications because they require a server (this is true even for the pure client-side, JavaScript-based versions of the Address Book as they make REST calls). For this tutorial we recommend using Apache Tomcat as it is one of the easier containers to get running (the examples are tested against Tomcat 6.0.29). Tomcat can be downloaded from http://tomcat.apache.org.

Take a fresh install of Tomcat. The Address Book application is pre-built for you in either examples/js/angular/addressbook, examples/js/jquery/mobile/addressbook, examples/js/webcomponent/addressbook, examples/java/faces/addressbook-faces.war, examples/java/gwt/addressbook-gwt.war, examples/java/jsp/addressbook-jsp.war, examples/java/spring/addressbook-spring.war, examples/java/struts/addressbook-struts.war or examples/java/vaadin/addressbook-struts.war. Alternatively you can build it yourself by changing to the src/examples folder and typing:

mvn -pl org.metawidget.examples.faces:addressbook-faces -am integration-test

(replacing faces with gwt, jsp, spring, struts or vaadin as appropriate).

	Note
	For most web environments, deploying Metawidget is as simple as adding metawidget-all.jar to WEB-INF/lib or metawidget-core.min.js to lib/metawidget. For GWT, you'll also need to include metawidget-all.jar and additional/gwt/metawidget-all-sources.jar in the CLASSPATH during your GWTCompiler step.

Copy the application into Tomcat's webapps folder, start Tomcat, and open a Web browser to http://localhost:8080/addressbook-faces. The home page displays a search filter (at the top) and lists existing Address Book entries (at the bottom) as in Figure 1.24.

Figure 1.24. Web Address Book opening screen

Figure 1.25. Web Address Book opening screen (JQuery Mobile version)

As with the Desktop Address Book, the search filter fields are created by Metawidget (this time AngularMetawidget, UIMetawidget, GwtMetawidget, HtmlMetawidgetTag, JQueryMobileMetawidget, SpringMetawidgetTag, StrutsMetawidgetTag or VaadinMetawidget) based on the ContactSearch business class:

<m:metawidget value="#{contact.search}">
	...
</m:metawidget>

Again, this includes populating the Type dropdown and localizing the text. The Search, Add Personal Contact and Add Business Contact buttons are either manually specified in the JSP page (for GWT, Spring and Struts) or created by UIMetawidget based on annotated methods in the ContactBean (for JSF).

	Note
	As with the Desktop Address Book, full source code for the examples can be found under src/examples.

The look of the Web page relies entirely on HTML and CSS technologies. The CSS classes to use are configured in metawidget.xml (or services.js for AngularJS):

<htmlMetawidget>
<parameter>
	<string>tableStyleClass</string>
	<string>table-form</string>
</parameter>
<parameter>
	<string>columnClasses</string>
	<string>table-label-column,table-component-column,table-required-column</string>
</parameter>
...

Only the layout of 'one column for the label, one column for the widget' is dictated by Metawidget, and that is again pluggable and configurable.

Click Add Personal Contact. The page displays a form for filling out Personal Contact information as in Figure 1.26.

Figure 1.26. Web Address Book 'Add Personal Contact' screen

All the form fields are created by Metawidget based on the PersonalContact business class. The section headings are the same, but have this time been rendered as HTML.

The Address property is a nested Metawidget. The Communications property has been overridden in the page with a manually specified table. UIMetawidget understands a manually-specified widget to override an automatic one if it has the same value binding as the automatic widget would have (AngularMetawidget, GwtMetawidget, SpringMetawidgetTag, StrutsMetawidgetTag and VaadinMetawidget do something similar):

<m:metawidget value="#{contact.current}">
	...		
	<h:dataTable value="#{contact.current.communications}">
		...
	</h:dataTable>						
	...							
<m:metawidget>

JSF has built-in support for executing actions on table rows. In order to use it, however, the Set returned by Contact.getCommunications must be wrapped into a DataModel. This is handled by ContactController.getCurrentCommunications, but this presents a problem: the mapping for the HtmlDataTable must be #{contact.currentCommunications}, but the mapping required to override UIMetawidget's automatic widget creation is #{contact.current.communications}.

UIMetawidget supplies UIStub for these situations. Stubs have a binding, but do nothing with it and render nothing. They can be used either to suppress widget creation entirely (a stub with an empty body) or to replace the automatic widget creation with one or more other widgets with different bindings:

<m:metawidget value="#{contact.current}">
	...		
	<m:stub value="#{contact.current.communications}">
		<h:dataTable value="#{contact.currentCommunications}">
			...
		</h:dataTable>						
	</m:stub>						
	...							
<m:metawidget>

JSP, Spring, Struts lack some component-based features found in Swing and JSF. Specifically, whilst it is possible for tags to reference their parent (using TagSupport.findAncestorWithClass), they have no way to interrogate their children. Therefore, it is not possible to directly support arbitrary child tags within HtmlMetawidget, SpringMetawidgetTag and StrutsMetawidgetTag.

Instead, we wrap the overridden Communications property in Metawidget's Stub tag. Metawidget and its Stub tags have explicit support for co-ordinating the overriding of widget creation:

<m:metawidget property="contactForm">
	...		
	<m:stub property="communications">
		<table class="data-table">
			...
		</table>
	</m:stub>						
	...							
<m:metawidget>

GwtMetawidget uses stubs around GWT widgets like FlexTable, but can use the overriding widget directly if it supports the HasName interface (e.g. TextBox, CheckBox, etc) and has a name matching the name of the domain object property.

<m:metawidget property="contactForm">
	...
	<m:stub property="communications">
		<table class="data-table">
		...
		<tr>
			<jsp:useBean id="communication"
							class="org.metawidget.example.shared.addressbook.model.Communication"/>		
			<td><mh:metawidget value="communication.type" style="width: 100%" /></td>
			<td><mh:metawidget value="communication.value" style="width: 100%" /></td>
		</tr>
		...
		</table>
	</m:stub>
	...
</m:metawidget>

Alternate Widget Libraries (JSF 1.x)

This section is specific to JSF 1.x.

Metawidget factors all widget creation into WidgetBuilders. Like Inspectors, multiple WidgetBuilders can be combined using a CompositeWidgetBuilder to support third-party component libraries. In this section we will override Metawidget's default and introduce a RichFacesWidgetBuilder alongside the standard JSF HtmlWidgetBuilder.

Go into Tomcat's webapps/addressbook-faces folder (the exploded WAR) and edit WEB-INF/metawidget.xml:

<metawidget xmlns="http://metawidget.org"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	version="1.0"
	xsi:schemaLocation="http://metawidget.org http://metawidget.org/xsd/metawidget-1.0.xsd">

<htmlMetawidget xmlns="java:org.metawidget.faces.component.html">
	...
	<inspector>		
		<compositeInspector xmlns="java:org.metawidget.inspector.composite"
								config="CompositeInspectorConfig">
			<inspectors>
			<array>
				<propertyTypeInspector xmlns="java:org.metawidget.inspector.propertytype"/>
				<metawidgetAnnotationInspector xmlns="java:org.metawidget.inspector.annotation"/>
				<facesAnnotationInspector xmlns="java:org.metawidget.inspector.faces"/>			
				<xmlInspector xmlns="java:org.metawidget.inspector.xml" config="XmlInspectorConfig"/>
			</array>
			</inspectors>
		</compositeInspector>
	</inspector>
	<widgetBuilder>
		<compositeWidgetBuilder xmlns="java:org.metawidget.widgetbuilder.composite"
			config="CompositeWidgetBuilderConfig">
			<widgetBuilders>
				<array>
					<overriddenWidgetBuilder xmlns="java:org.metawidget.faces.component.widgetbuilder"/>
					<readOnlyWidgetBuilder xmlns="java:org.metawidget.faces.component.html.widgetbuilder"/>
					<richFacesWidgetBuilder xmlns="java:org.metawidget.faces.component.html.widgetbuilder.richfaces"/>
					<htmlWidgetBuilder xmlns="java:org.metawidget.faces.component.html.widgetbuilder"/>
				</array>
			</widgetBuilders>
		</compositeWidgetBuilder>
	</widgetBuilder>
	<layout>
		<outputTextLayoutDecorator xmlns="java:org.metawidget.faces.component.html.layout"
			config="OutputTextLayoutDecoratorConfig">
			<layout>
				<simpleLayout xmlns="java:org.metawidget.faces.component.layout"/>
			</layout>
			<styleClass>
				<string>section-heading</string>
			</styleClass>
		</outputTextLayoutDecorator>
	</layout>	
</htmlMetawidget>

</metawidget>

Now restart Tomcat, refresh your Web browser and click on Homer Simpson. Notice how the Date of Birth field for Personal Contacts is now a RichFaces date picker widget, and the Number of Staff field for Business Contacts is a RichFaces slider widget.

Going futher, Metawidget's pluggable layouts make it easy to support third-party layout components. Edit WEB-INF/metawidget.xml again:

<metawidget xmlns="http://metawidget.org"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	version="1.0"
	xsi:schemaLocation="http://metawidget.org http://metawidget.org/xsd/metawidget-1.0.xsd">

<htmlMetawidget xmlns="java:org.metawidget.faces.component.html">
	...
	<inspector>		
		<compositeInspector xmlns="java:org.metawidget.inspector.composite"
								config="CompositeInspectorConfig">
			<inspectors>
			<array>
				<propertyTypeInspector xmlns="java:org.metawidget.inspector.propertytype"/>
				<metawidgetAnnotationInspector xmlns="java:org.metawidget.inspector.annotation"/>
				<facesAnnotationInspector xmlns="java:org.metawidget.inspector.faces"/>			
				<xmlInspector xmlns="java:org.metawidget.inspector.xml" config="XmlInspectorConfig"/>
			</array>
			</inspectors>
		</compositeInspector>
	</inspector>
	<widgetBuilder>
		<compositeWidgetBuilder xmlns="java:org.metawidget.widgetbuilder.composite"
			config="CompositeWidgetBuilderConfig">
			<widgetBuilders>
				<array>
					<overriddenWidgetBuilder xmlns="java:org.metawidget.faces.component.html.widgetbuilder"/>
					<readOnlyWidgetBuilder xmlns="java:org.metawidget.faces.component.html.widgetbuilder"/>
					<richFacesWidgetBuilder xmlns="java:org.metawidget.faces.component.html.widgetbuilder.richfaces"/>
					<htmlWidgetBuilder xmlns="java:org.metawidget.faces.component.html.widgetbuilder"/>
				</array>
			</widgetBuilders>
		</compositeWidgetBuilder>
	</widgetBuilder>
	<layout>
		<tabPanelLayoutDecorator xmlns="java:org.metawidget.faces.component.html.layout.richfaces"
			config="TabPanelLayoutDecoratorConfig">
			<layout>
				<simpleLayout xmlns="java:org.metawidget.faces.component.layout"/>
			</layout>
		</tabPanelLayoutDecorator>
	</layout>	
</htmlMetawidget>

</metawidget>

Restart Tomcat, refresh your Web browser and click on Homer Simpson again. Notice how the Contact Details and Other sections are laid out as tabs within a RichFaces TabPanel as in Figure 1.27.

Figure 1.27. Web Address Book using JBoss RichFaces

This demonstrates how easy it is to leverage widget libraries with Metawidget (this example cheats a bit, as we've pre-added the RichFaces JARs into WEB-INF/lib and some lines into web.xml, but you get the idea).

Alternate Widget Libraries (JSF 2.x)

This section is specific to JSF 2.x.

As in the previous section, we can override Metawidget's default and introduce an alternate WidgetBuilder alongside the standard JSF HtmlWidgetBuilder. This time we will demonstrate using PrimeFaces.

Go into Tomcat's webapps/addressbook-faces2 folder (the exploded WAR) and edit WEB-INF/metawidget.xml:

<metawidget xmlns="http://metawidget.org"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	version="1.0"
	xsi:schemaLocation="http://metawidget.org http://metawidget.org/xsd/metawidget-1.0.xsd">

<htmlMetawidget xmlns="java:org.metawidget.faces.component.html">
	...
	<inspector>		
		<compositeInspector xmlns="java:org.metawidget.inspector.composite"
								config="CompositeInspectorConfig">
			<inspectors>
			<array>
				<propertyTypeInspector xmlns="java:org.metawidget.inspector.propertytype"/>
				<metawidgetAnnotationInspector xmlns="java:org.metawidget.inspector.annotation"/>
				<facesAnnotationInspector xmlns="java:org.metawidget.inspector.faces"/>			
				<xmlInspector xmlns="java:org.metawidget.inspector.xml" config="XmlInspectorConfig"/>
			</array>
			</inspectors>
		</compositeInspector>
	</inspector>
	<widgetBuilder>
		<compositeWidgetBuilder xmlns="java:org.metawidget.widgetbuilder.composite"
			config="CompositeWidgetBuilderConfig">
			<widgetBuilders>
				<array>
					<overriddenWidgetBuilder xmlns="java:org.metawidget.faces.component.widgetbuilder"/>
					<readOnlyWidgetBuilder xmlns="java:org.metawidget.faces.component.html.widgetbuilder"/>
					<primeFacesWidgetBuilder xmlns="java:org.metawidget.faces.component.html.widgetbuilder.primefaces"/>
					<htmlWidgetBuilder xmlns="java:org.metawidget.faces.component.html.widgetbuilder"/>
				</array>
			</widgetBuilders>
		</compositeWidgetBuilder>
	</widgetBuilder>
	<layout>
		<tabViewLayoutDecorator xmlns="java:org.metawidget.faces.component.html.layout.primefaces"
			config="org.metawidget.layout.decorator.LayoutDecoratorConfig">
			<layout>
				<simpleLayout xmlns="java:org.metawidget.faces.component.layout"/>
			</layout>
		</tabViewLayoutDecorator>
	</layout>	
</htmlMetawidget>

</metawidget>

Restart Tomcat, refresh your Web browser and click on Charles Montgomery Burns. Notice how the Contact Details and Other sections are laid out as tabs within a PrimeFaces TabView and the Number of Staff field is a PrimeFaces Slider. See Figure 1.28.

Figure 1.28. Web Address Book using PrimeFaces

This demonstrates how easy it is to leverage widget libraries with Metawidget (this example cheats a bit, as we've pre-added the PrimeFaces JARs into WEB-INF/lib and some lines into web.xml, but you get the idea).

For the Mobile Address Book we use the Android platform. Like Web-based applications, mobile applications require a container to run. If you have a physical Android device you can install the Mobile Address Book by downloading and opening http://metawidget.org/examples/android/addressbook-android.apk or scanning this QR Code:

Figure 1.29. Mobile Address Book APK URL

	Note
	The Android Address Book is a native mobile application. For an example of an HTML 5 hybrid mobile application see the JQuery Mobile Address Book in the previous section.

Alternatively download the Android SDK from http://code.google.com/android/download.html (the examples are tested against Android 1.1). Then change to the installation directory (usually defined by ANDROID_HOME) and run the emulator by opening a command prompt and typing:

tools\android create avd -n my_avd -t 1

Replacing -t 1 with the Android version you're using (e.g. -t 2 for 1.5, -t 3 for 1.6, -t 4 for 2.0). Android 1.1 doesn't use AVDs, so you can skip this step. Next type:

tools\emulator -avd my_avd

The emulator may take a little while to start. Once finished, it will display the phone's desktop. The Address Book APK is pre-built for you in examples/android/addressbook-android.apk. Alternatively you can build it yourself by changing to the src/examples folder and typing:

mvn -pl org.metawidget.examples.android:addressbook-android -am integration-test

Next, open a second command prompt, change to the Android installation directory and type:

platform-tools\adb install <metawidget folder>\examples\android\addressbook-android.apk

This deploys the APK into the emulator. To run it, click the emulator's Menu button and then choose the Address Book application. The emulator displays a search filter (at the top) and lists existing Address Book entries (at the bottom) as in Figure 1.30.

Figure 1.30. Mobile Address Book opening screen

As with the Desktop and Web Address Books, the three search filter fields are created by Metawidget (this time AndroidMetawidget) based on the ContactSearch business class. Again, this includes populating the Type dropdown.

	Note
	As with the Desktop Address Book, full source code for the examples can be found under src/examples. To open it in Eclipse we recommend installing Maven Integration for Android Development Tools.

The look of the screen relies entirely on Android XML layout files, styles and themes. Only the 'one column for the label, one column for the widget' layout is dictated by Metawidget, and that is pluggable and configurable.

Choose Add Personal from the Android menu. The page displays a form for filling out Personal Contact information as in Figure 1.31.

Figure 1.31. Mobile Address Book 'Add Personal Contact' screen

UIs in Android are typically defined using XML layout files, though they can also be built programmatically. AndroidMetawidget supports both approaches. For example, the Personal Contact screen is defined in contact.xml, and contains a Metawidget defined in much the same way as in JSP (including configuring section style and overriding widget creation):

<view class="org.metawidget.android.widget.AndroidMetawidget" android:id="@+id/metawidget"
	config="@raw/metawidget">
	
	<view class="org.metawidget.android.widget.Stub" tag="communications">
			
		<ListView android:id="@id+/communications" ... />
	 			
		<Button android:id="@+id/buttonAddCommunication"
			android:text="@string/addCommunication" ... />
	
	</view>
 
</view>

Within CommunicationDialog, a Metawidget is defined programatically in much the same way as in Swing:

mMetawidget = new AndroidMetawidget( activity );
mMetawidget.setConfig( R.raw.config );				
...
mMetawidget.setToInspect( mCommunication );

This produces the dialog box in Figure 1.32.

Figure 1.32. Mobile Address Book Communications Dialog

That concludes the introductory tutorial. In summary, we have now:

The Swing Applet Address Book Example demonstrates using Metawidget in applets. The example is pre-built for you in examples/swing/applet/addressbook. Alternatively you can build it yourself by changing to the src/examples folder and typing:

mvn -pl org.metawidget.examples.swing:addressbook-swing-applet -am integration-test

To run the applet, open the index.html file in a Web browser. The code is identical to the Swing Address Book covered in Part 2 of this tutorial, except it uses org.metawidget.example.swing.applet.AddressBookApplet instead of org.metawidget.example.swing.addressbook.MainFrame.

The notable feature of the example is how the applet is packaged. Metawidget is highly modular and has no mandatory third-party JAR dependencies. The addressbook-swing-applet Maven POM uses fine-grained Metawidget dependencies (as an alternative to metawidge-all.jar) to include only those modules necessary for the applet. The resulting small download size makes Metawidget very viable for applet-based environments. See Section 9.5.1, “JAR Size”.

The Seam Booking Example demonstrates updating an existing Seam application to use Metawidget, reducing boilerplate code. The example is included as part of Seam 2.2.0.GA. It also requires you to have JBoss 5.1.0.GA, and you should be familiar with the existing Seam Booking application.

The example is located in jboss-seam-2.2.0.GA/examples/metawidget/booking. It is not pre-built. To build it, change to the examples/metawidget/booking folder in the Seam binary distribution and type:

ant

To run it, type:

cd \Applications\jboss-5.1.0.GA
bin\run

Open a Web browser to http://localhost:8080/seam-booking. The updated Metawidget Seam Booking Example looks very similar to the original, as in Figure 1.33, but uses significantly less boilerplate code.

Figure 1.33. Seam Booking with Metawidget

The files modified for adding Metawidget support are in examples/metawidget/booking. Most of the UI code in view/book.xhtml, view/confirm.xhtml and view/hotelview.xhtml has been replaced with a single Metawidget tag. Some annotations have been added to Hotel.java and Booking.java, though Metawidget also leverages the existing JPA and Hibernate Validator ones.

The Seam Groovy Booking Example demonstrates updating an existing Seam Groovy application to use Metawidget, reducing boilerplate code. The example is a more advanced version of the previous Seam section, so you should work through that first.

The example is located in jboss-seam-2.2.0.GA/examples/metawidget/groovybooking. It is not pre-built. To build it, change to the examples/metawidget/groovybooking folder in the Seam distribution and type:

ant

To run it, type:

cd \Applications\jboss-5.1.0.GA
bin\run

Open a Web browser to http://localhost:8080/jboss-seam-groovybooking. As with the previous section, the updated Metawidget Seam Groovy Booking Example looks very similar to the original, but uses significantly less boilerplate code. This time we are using Groovy to define our business classes. The biggest impact this has is in metawidget.xml, where the Inspectors have been configured to use a Groovy property style instead of a JavaBean property style.

Metawidget supports pluggable 'property styles' for JavaBean, Groovy and other property styles. Groovy properties differ from JavaBean properties in that their annotations are tied to the private field, rather than the getters and setters. The use of Groovy is configured per Inspector, as in examples/metawidget/groovybooking/resources/WEB-INF/metawidget.xml:

<propertyTypeInspector config="org.metawidget.inspector.impl.BaseObjectInspectorConfig">
	<propertyStyle>
		<groovyPropertyStyle xmlns="java:org.metawidget.inspector.impl.propertystyle.groovy"/>
	</propertyStyle>
</propertyTypeInspector>

The example demonstrates how Metawidget can significantly reduce the amount of boilerplate code in your UI layer - in some cases up to 70%. Figure 1.33 shows the book.xhtml page before and after being fitted with Metawidget. The red boxes and lines highlight the chunks of boilerplate that have been removed:

Figure 1.34. book.xhtml before and after being fitted with Metawidget

The Seam DVD Store Example demonstrates updating an existing Seam jBPM application to use Metawidget, reducing boilerplate code. The example requires you to have previously downloaded Seam 2.2.0.GA and JBoss 5.1.0.GA, and you should be familiar with the existing Seam DVD Store application.

The example is located in jboss-seam-2.2.0.GA/examples/metawidget/dvdstore. It is not pre-built. To build it, change to the examples/metawidget/dvdstore folder in the Seam distribution and type:

ant

To run it, type:

cd \Applications\jboss-5.1.0.GA
bin\run

Open a Web browser to http://localhost:8080/seam-dvdstore. As with the previous two sections, the updated Metawidget Seam DVD Store example looks very similar to the original, as in Figure 1.35, but uses significantly less boilerplate code.

Figure 1.35. Seam DVD Store with Metawidget

This time, as well as generating UIComponents for domain objects such as com.jboss.dvd.seam.Customer, Metawidget inspects jBPM pageflow files like newuser.jpdl.xml and checkout.jpdl.xml to generate the correct UICommand buttons for each screen.

ICEfaces is an AJAX component library for Java Server Faces. This example showcases how Metawidget can work with ICEfaces (1.8.2 and above) to deliver rich AJAX applications.

The example is pre-built for you in examples/faces/penguincolony-faces.war. Copy the WAR into Tomcat's webapps folder, start Tomcat, and open a Web browser to http://localhost:8080/penguincolony-faces:

Figure 1.36. ICEfaces with Metawidget

The application manages details of penguins in a colony. To begin, click the Edit link in the first row of the table: ICEfaces and Metawidget work together to pop up an AJAX form without refreshing the page. Next, clear the form's Name box and tab to the next field: an AJAX call is made and a validation error appears. Try entering a new name and tabbing again: the validation error disappears and the new name is immediately reflected in the table behind the popup box.

The remaining fields are wrapped in an ICEfaces PanelTabSet. Click on the Details tab. Here, the example makes use of the @UiAttribute annotation and FacesInspectionResultProcessor. The Java code is annotated:

@UiAction
@UiAttribute( name = InspectionResultConstants.HIDDEN, value = "#{!empty _this.condition}" )
public void addCondition() { ... }

@UiAttribute( name = InspectionResultConstants.HIDDEN, value = "#{empty _this.condition}" )
public PenguinCondition getCondition() { ...}

Clicking the Add Condition button, or checking one of the Hobbies checkboxes, triggers an AJAX call that re-evaluates the @UiAttribute annotations and dynamically reconstructs the form without requiring a page refresh. This includes removing existing buttons, creating new dropdown boxes and creating new labels.

For more details on ICEfaces support, see the section called “IceFacesWidgetBuilder” and the section called “PanelTabSetLayoutDecorator”.

There is a retrofitted version of the GatewayWarDeployment example from Adam Bien's Real World Java EE Patterns book downloadable from his Java EE Patterns and Best Practices Kenai Repository.

For more information, see this blog entry.

The Swing AppFramework Car Demo demonstrates using Metawidget with the Swing AppFramework. Metawidget can use Swing AppFramework's @Action annotation to identify actions, both amongst a domain object's properties and in external controllers, and automatically generate JButtons for them.

The application is pre-built for you in examples/swing/appframework-swing.jar or you can build it yourself by changing to the src/examples/swing/appframework folder and typing:

mvn package

	Note
	This example uses annotations, so you'll need Java SE 5 or higher

This is a self-executing JAR. For convenience, it has MANIFEST.MF dependencies hard-wired into it to lib/AppFramework.jar among others, so it's best not to move it to a different folder (if you do, you'll need to manually put those JARs on your CLASSPATH).

Run the code by navigating to the examples/swing folder and typing:

java -jar appframework-swing.jar

The opening screen displays two fields to allow you to enter the make and type of a car. You can also optionally add an owner by clicking the Add an Owner button, or save the car using the Save button.

The Add an Owner button is generated by Metawidget based on the addOwner method in the Car class (which has been annotated @org.jdesktop.application.Action). The Save button is generated based on the save method in the CarApplication class (also annotated @Action). Two different Metawidgets are used in the example: one pointed at the Car class, the other at the CarApplication class.

Metawidget supports pluggable 'action styles'. The use of Swing AppFramework is configured per Inspector, as in src/examples/swing/appframework/src/main/resources/org/metawidget/example/swing/appframework/metawidget.xml from the source distribution:

<metawidgetAnnotationInspector config="org.metawidget.inspector.impl.BaseObjectInspectorConfig">
	<actionStyle>
		<swingAppFrameworkActionStyle xmlns="java:org.metawidget.inspector.impl.actionstyle.swing">
	</actionStyle>
</metawidgetAnnotationInspector>

As a further feature, after the Add an Owner button is clicked it disappears. This is acheived by using JexlInspectionResultProcessor to introduce an expression language for Swing similar to JSP's EL. The method is annotated...

@Action( name = "add" )
@UiAttribute( name = HIDDEN, value = "${this.owner != null}" )
public void addOwner() {
	mOwner = new Owner();
	fireActionEvent( "addOwner" );
}

...such that the button gets hidden when the car has an owner.

The Scala Animal Races Example demonstrates using SwingMetawidget together with Scala and MigLayout.

The application is pre-built for you in examples/swing/animalraces-swing.jar or you can build it yourself by changing to the src/examples/swing/animalraces folder of the source distribution and typing:

mvn package

	Note
	This example uses annotations, so you'll need Java SE 5 or higher

This is a self-executing JAR. For convenience, it has MANIFEST.MF dependencies hard-wired into it to lib/scala-library.jar among others, so it's best not to move it to a different folder (if you do, you'll need to manually put those JARs on your CLASSPATH).

Run the code by navigating to the examples/swing folder and typing:

java -jar animalraces-swing.jar

The screen displays fields to allow you to change the name, speed and type of each animal as well buttons to start and stop the race.

Figure 1.37. Scala and MigLayout with Metawidget

Animal Races' whimsical User Interface demonstrates how Metawidget's goal of not 'owning' the UI allows multiple Metawidgets to be combined for unconventional UIs. There are three Metawidgets across the top (one for each animal in the race), and a fourth Metawidget for the buttons at the bottom.

The top three Metawidgets all use MigLayout. Because Metawidget does not hide the underlying UI framework, using MigLayout allows the Animal Races code to easily pad the Metawidget:

metawidget.setMetawidgetLayout( new MigLayout() );
metawidget.setToInspect( animal );
((MigLayout) metawidget.getLayout()).setLayoutConstraints( new LC().insets( "10" ));

The Animal Races code is written purely in Scala, located at src/examples/swing/animalraces/src/main/scala/org/metawidget/example/swing/animalraces/AnimalRaces.scala. It uses ScalaPropertyStyle to allow Metawidget to inspect Scala-based domain objects:

<metawidgetAnnotationInspector xmlns="java:org.metawidget.inspector.annotation"
		config="org.metawidget.inspector.impl.BaseObjectInspectorConfig">
		<propertyStyle>
			<scalaPropertyStyle xmlns="java:org.metawidget.inspector.impl.propertystyle.scala"/>
		</propertyStyle>			
	</metawidgetAnnotationInspector>

In addition, it uses BeanUtilsBindingProcessorConfig.PROPERTYSTYLE_SCALA to bind JComponents to Scala-based domain objects:

val metawidget = new SwingMetawidget()
metawidget.addWidgetProcessor( new BeanUtilsBindingProcessor()
			.setPropertyStyle( BeanUtilsBindingProcessorConfig.PROPERTYSTYLE_SCALA ))
metawidget.setToInspect( animal )

By default, GwtMetawidget uses server-side inspection of domain objects. This is because client-side JavaScript does not support reflections or annotations. However if you don't need reflections or annotations, and have your own way of retrieving inspection results, you can plug in your own Inspector and keep everything client-side. This example implements a TextAreaInspector that retrieves inspection results from a textarea and generates the UI.

The GWT Client Side example is pre-built for you in examples/gwt/clientside-gwt. Because everything is purely client side, there is no need for Tomcat or any other container: simply navigate to the example folder and open index.html in your Web browser:

Figure 1.38. Client-Side GwtMetawidget

The example shows a textarea on the left containing inspection results in inspection-result-1.0.xsd format. The result of generating this XML is shown on the right. Click the Sample #2 and Sample #3 buttons to preload different XML samples, and the Generate button to generate their UI. Alternatively, you can edit the XML by hand to add new properties and actions and click Generate.

Data binding and event binding are also implemented client side. Click the Save to save the data from the generated UI using a MapPropertyBinding (in a real application, this Map could be passed back to the server for persisting). Click the Add Tracks button to trigger an event binding.

Finally, this example showcases using third-party GWT component libraries. ExtGwtWidgetBuilder is used to render a date picker widget. For more details on ExtGWT support, see the section called “ExtGwtWidgetBuilder”.

The examples/gwt/addressbook-gwt.war (discussed in Part 2 of this tutorial) and the examples/gwt/clientside (discussed in Part 3 of this tutorial) demonstrates GWT running in GWT Web mode. Developers may prefer instead to run the examples in GWT hosted mode as in Figure 1.39.

Figure 1.39. Address Book Example running in GWT Hosted Mode

Source code for all examples can be found under the src/examples folder of the examples distribution. The code is organized into standalone Maven projects so that it can be easily imported into your favourite IDE. For example, to run the GWT Address Book example in Eclipse:

	Check your Build Path
	If Hosted Mode fails to start, right click the project and choose Properties > Java Build Path > Libraries. Check the build path does not include any GWT libraries outside of those in Maven Dependencies, and that the GWT version matches the one in src/examples/gwt/addressbook/pom.xml.

Once you have the samples running, you can quickly make changes and play around. For example:

Figure 1.40. Address Book Example using GWT TabPanel

Although Metawidget is focused on runtime UI generation, its static mode (see Section 3.4, “Static Metawidgets”) can sometimes be more appropriate. The JBoss Forge project provides a thorough, real world demonstration of static Metawidget in action. JBoss Forge uses Metawidget internally for its UI scaffolding generation.

Figure 1.41. Static Metawidget is used internally by JBoss Forge

To try using static Metawidget inside JBoss Forge:

This runs a Forge script that automates the creation of a Java EE web application. Forge makes use of static Metawidget in several places, including: for the JSF components on the Create, Retrieve, Update and Delete (CRUD) screens; for the search filter criteria; for generating Java statements inside the JSF managed bean.

Alternatively, there are Forge plugins that can generate scaffolds for different environments. For example the Spring plugin uses StaticSpringMetawidget to generate Spring scaffolds, and the AeroGear plugin uses StaticHtmlMetawidget to generate mobile scaffolds. For more information on JBoss Forge and how Metawidget relates to it, see the UI scaffolding section of the Forge documentation.

Metawidgets are not required to extend any Java base class or implement any Java interface. This is because most UI frameworks require widgets inherit one of their base classes, such as javax.swing.JComponent or javax.faces.UIComponent, and Java does not support multiple inheritance.

In addition, while all Metawidgets support roughly the same functionality, different UI frameworks have different in-built capabilities. For example, JSF has UIComponent.setRenderer for choosing different layouts for the same widget, whereas SwingMetawidget has to roll its own setMetawidgetLayout method. This diversity of capabilities means there cannot be a common 'Metawidget Java interface' either.

However, despite not extending any common base class or interface, all Metawidgets follow roughly the same design, with roughly the same method names:

For those looking to write their own Metawidget (say, for a currently unsupported platform) there is a BasePipeline class that implements the above steps 2-7 for you, see Section 2.1.4, “Implementing Your Own Metawidget”. All of the supplied Metawidgets are implemented using this class.

As much as possible, Metawidgets defer to the existing Look and Feel technology of their native UI framework. For example, HtmlMetawidget uses HTML/CSS, SwingMetawidget uses Swing Look-and-Feels, and AndroidMetawidget uses Android styles and themes.

The one visual area Metawidget does control is how the widgets it creates are laid out. Typically this is in a tabular 'one column for the label, one column for the widget' format, but this is pluggable.

Metawidgets come with different Layout classes that can arrange the widgets in different ways, and these are set on the Metawidget in a framework-specific way. For example, JSF uses <m:metawidget rendererType=""> whereas SwingMetawidget uses setMetawidgetLayout. As much as possible, the Layout classes defer back to the capabilities of the native framework. For example, Swing's GridBagLayout or Android's TableLayout.

Some Layouts may add localized labels to the widgets whereas other Layouts will leave them unadorned. Different Layouts may support different parameters (e.g. a TableLayout may support numberOfColumns). These are initialized on the Layout at construction time using an xxxLayoutConfig. Finally, some Layouts can be wrapped around other Layout to provide section headings (e.g. TabPanelLayoutDecorator).

Metawidget tries to automate much of the widget creation, but provides many hooks to customize the process:

Metawidget creates widgets native to a particular UI framework. Having to implement your own Metawidget should be far less common than having to implement your own Inspector, InspectorResultProcessor, WidgetBuilder, WidgetProcessor or Layout, but if your chosen UI framework is not supported 'out of the box' you may need to implement your own.

Metawidgets are not required to extend any base class or implement any interface. However, it is recommended developers familiarize themselves with existing Metawidgets (such as UIMetawidget) to make their API similar. Whilst there is no Metawidget base class, all the built-in Metawidgets reuse BasePipeline to ease their implementation. It provides pre-built functionality including: configuring and executing all stages of the pipeline; deciding when to use single versus compound widgets; read-only mode; and tracking maximum inspection depth.

All Inspectors must implement the Inspector interface. This is a simple interface that defines only one method:

String inspect( Object toInspect, String type, String... names );

Each Inspector must look to the type parameter and the names array. These form a path into the domain object model. For example the type may be com.myapp.Person and the names may be address and street. This would form a path into the domain model of com.myapp.Person/address/street (i.e. return information on the street property within the address property of the Person type).

Depending on the type of inspector, it may use the given toInspect to access the runtime object for the given type. For example:

metawidget.setToInspect( myPerson );	// Will be passed to Inspector

Or it may ignore the toInspect and look up information for the given type from an XML file or a database schema. This allows Metawidget to inspect types that have no corresponding Java object. For example:

metawidget.setToInspect( null );	// No setToInspect
metawidget.setPath( "Login Form" );

This could be combined with, say, an XmlInspector and a metawidget-metadata.xml:

<entity type="Login Form">
	<property name="username"/>
	<property name="password"/>
</entity>

This approach also allows Metawidget to inspect abstract classes:

metawidget.setToInspect( null );	// No setToInspect
metawidget.setPath( MyAbstractClass.class.getName() );

	Note
	In general, a non-null setToInspect is preferrable, as many binding and validation technologies (e.g. see the section called “Property Binding”) will be expecting a concrete object.

Unless explicitly specified, each Metawidget will instantiate a default Inspector. Typically this will be a CompositeInspector composed of a PropertyTypeInspector and a MetawidgetAnnotationInspector.

This default behaviour can be overridden either in code:

metawidget.setInspector( new MyInspector() );

Or via metawidget.xml (see Section 2.7, “metawidget.xml and ConfigReader”):

<swingMetawidget xmlns="java:org.metawidget.swing">
	<inspector>
		<myInspector xmlns="java:com.myapp"/>
	</inspector>
</swingMetawidget>

This allows easy plugging in of alternate inspectors. Note that overriding the default means the default is no longer instantiated. In the example above, this would mean MyInspector is used but the default Inspectors are not. This is usually not what you want, because MyInspector will be focused on a particular type of back-end metadata and will want to leave other metadata to other inspectors.

To achieve this, use CompositeInspector.

CompositeInspector composes the results of several Inspectors into one and returns a single, combined inspection result. As shown in Figure 2.2 CompositeInspector works by calling each Inspector in turn, combining the inspection result as it goes.

Figure 2.2. CompositeInspector composes multiple inspectors into one

All Inspectors are required to be immutable (see Section 2.2.5, “Immutability”). Therefore, although CompositeInspector maintains a list of Inspectors this must not be changeable. To enforce this, the list is set at instantation time using CompositeInspectorConfig. This can either be set in code:

metawidget.setInspector( new CompositeInspector( new CompositeInspectorConfig()
	.setInspectors(
		new PropertyTypeInspector(),
		new MetawidgetAnnotationInspector(),
		new MyInspector()
	)));

Or via metawidget.xml (see Section 2.7, “metawidget.xml and ConfigReader”):

<swingMetawidget xmlns="java:org.metawidget.swing">
<inspector>
	<compositeInspector xmlns="java:org.metawidget.inspector.composite" config="CompositeInspectorConfig">
		<inspectors>
			<array>
				<propertyTypeInspector xmlns="java:org.metawidget.inspector.propertytype"/>
				<metawidgetAnnotationInspector xmlns="java:org.metawidget.inspector.annotation" />
				<myInspector xmlns="java:com.myapp"/>
			</array>
		</inspectors>
	</compositeInspector>
</inspector>
</swingMetawidget>

All Metawidgets have default Inspectors. Overriding the default means the default is no longer instantiated. Usually this is not what you want, so you should consider instantiating the default along with your new Inspector (i.e. use CompositeInspector). You can see the default by looking in the Metawidget JAR for the file metawidget-xxx-default.xml (where xxx is your target platform, such as swing or struts).

For reference, the defaults are:

<compositeInspector xmlns="java:org.metawidget.inspector.composite"
		config="CompositeInspectorConfig">
		<inspectors>
			<array>
				<propertyTypeInspector />
				<metawidgetAnnotationInspector />
			</array>
		</inspectors>
	</compositeInspector>

<compositeInspector xmlns="java:org.metawidget.inspector.composite"
		config="CompositeInspectorConfig">
		<inspectors>
			<array>
				<propertyTypeInspector />
				<metawidgetAnnotationInspector />
			</array>
		</inspectors>
	</compositeInspector>

new metawidget.inspector.PropertyTypeInspector()

<compositeInspector xmlns="java:org.metawidget.inspector.composite"
		config="CompositeInspectorConfig">
		<inspectors>
			<array>
				<propertyTypeInspector />
				<metawidgetAnnotationInspector />
				<facesAnnotationInspector />
			</array>
		</inspectors>
	</compositeInspector>

<compositeInspector xmlns="java:org.metawidget.inspector.composite"
		config="CompositeInspectorConfig">
		<inspectors>
			<array>
				<propertyTypeInspector />
				<metawidgetAnnotationInspector />
				<jspAnnotationInspector />				
			</array>
		</inspectors>
	</compositeInspector>

<compositeInspector xmlns="java:org.metawidget.inspector.composite"
		config="CompositeInspectorConfig">
		<inspectors>
			<array>
				<propertyTypeInspector />
				<metawidgetAnnotationInspector />
				<springAnnotationInspector />
			</array>
		</inspectors>
	</compositeInspector>

<compositeInspector xmlns="java:org.metawidget.inspector.composite"
		config="CompositeInspectorConfig">
		<inspectors>
			<array>
				<propertyTypeInspector>
					<propertyStyle>
						<javaBeanPropertyStyle>
							<excludeBaseType>
								<pattern>^(java|javax|org\.apache\.struts)\..*$</pattern>
							</excludeBaseType>
						</javaBeanPropertyStyle>
					</propertyStyle>
				</propertyTypeInspector>				
				<metawidgetAnnotationInspector />
				<strutsAnnotationInspector />
				<commonsValidatorInspector />
			</array>
		</inspectors>
	</compositeInspector>

<compositeInspector xmlns="java:org.metawidget.inspector.composite"
		config="CompositeInspectorConfig">
		<inspectors>
			<array>
				<propertyTypeInspector />
				<metawidgetAnnotationInspector />
			</array>
		</inspectors>
	</compositeInspector>

<compositeInspector xmlns="java:org.metawidget.inspector.composite"
		config="CompositeInspectorConfig">
		<inspectors>
			<array>
				<propertyTypeInspector />
				<metawidgetAnnotationInspector />
			</array>
		</inspectors>
	</compositeInspector>

All Inspectors are required to be immutable. This means you only need a single instance of an Inspector for your entire application. If you are using metawidget.xml (see Section 2.7, “metawidget.xml and ConfigReader”) then ConfigReader takes care of this for you, but if you are instantiating Inspectors in Java code you should reuse instances.

Note that immutable only means Inspectors cannot be changed once instantiated - it does not mean they cannot be configured. Many Inspectors have corresponding xxxConfig classes that allow them to be configured prior to instantation in a type-safe way. For example, a JpaInspector can be configured in code:

metawidget.setInspector( new JpaInspector( new JpaInspectorConfig().setHideIds( false )));

Or in metawidget.xml (see Section 2.7, “metawidget.xml and ConfigReader”):

<jpaInspector xmlns="java:org.metawidget.inspector.jpa" config="JpaInspectorConfig">
	<hideIds>
		<boolean>false</boolean>
	</hideIds>
</jpaInspector>

The inspection-result XML format is the 'glue' that holds everything together: the Metawidgets request it, the Inspectors provide it, and the WidgetBuilders base their choice of widgets on it.

It is a very simple format. As an example:

<inspection-result xmlns="http://metawidget.org/inspection-result" version="1.0">
	<entity type="com.myapp.Person">
		<property name="name" required="true"/>
		<property name="age" minimum-value="0"/>
	</entity>
</inspection-result>

Only a handful of XML attributes are mandatory (see inspection-result-1.0.xsd). Most, such as required and minimum-value, are provided at the discretion of the Inspector and recognised at the discretion of the WidgetBuilders, WidgetProcessors and Layouts. This loose coupling allows Inspectors to evolve independently for new types of metadata, WidgetBuilders to evolve independently with new types of widgets, and so on.

For JavaScript-based Metawidgets, inspection results are returned as JSON Schema:

{
	properties: {
		name: {
			required: true
		},
		age: {
			minimum-value: 0
		}
	}
}

Metawidget inspects a wide variety of back-end architectures. If your chosen back-end architecture is not supported 'out of the box', you may need to implement your own Inspector.

All Inspectors must implement the org.metawidget.inspector.Inspector interface:

public interface Inspector {
	String inspect( Object toInspect, String type, String... names );
}

The interface has only one method: inspect. Its parameters are:

The returned String must be an XML document conforming to inspection-result-1.0.xsd. To assist development, deploy your Inspector within ValidatingCompositeInspector to automatically validate the returned DOM during testing.

A number of convenience base classes are provided for different inspectors:

When implementing your own Inspector, try to avoid technology-specific XML attribute names. For example, FacesAnnotationInspector has an annotation @UiFacesNumberConverter. This annotation certainly has a technology-specific part to it, as it names a JSF Converter that only applies in JSF environments, so it is reasonable to name that XML attribute faces-converter-class. However, it also describes other parts of the property, such as the maximum number of integer digits. Such parts are not JSF-specific (i.e. we can source the same property from Hibernate Validator's @Digits annotation), so are better named 'neutrally' (i.e. maximum-integer-digits).

Like InspectionResultProcessors, WidgetBuilders, WidgetProcessors and Layouts, Inspectors are required to be immutable. However they will occasionally need to store some internal state, such as which PropertyStyle to use. This can be achieved in two ways:

All InspectionResultProcessors must implement the InspectionResultProcessor interface. This is a simple interface that defines only one method:

String processInspectionResult( String inspectionResult, M metawidget, Object toInspect,
                                String type, String... names );

Where M is a Metawidget type (such as SwingMetawidget or UIMetawidget).

The InspectionResultProcessor must returned the processed inspection result as XML conforming to inspection-result-1.0.xsd. The parent Metwidget then passes this to the next InspectionResultProcessor in the list as shown in Figure 2.3.

Figure 2.3. Typical InspectionResultProcessor list

In most cases the InspectionResultProcessor will modify the given inspectionResult and return a new String. This will then be passed down the list. Alternatively, the InspectionResultProcessor can return null to cancel inspection result processing entirely. No further InspectionResultProcessors or WidgetBuilders will be called, as shown in Figure 2.4.

Figure 2.4. An InspectionResultProcessor can abort the inspection result processing

Unless explicitly specified, each Metawidget will instantiate a default InspectionResultProcessor. Typically this will be a ComesAfterInspectionResultProcessor, which sorts business properties and actions according to their comes-after attribute.

This default behaviour can be overridden either in code:

metawidget.addInspectionResultProcessor( new MyInspectionResultProcessor() );

Or via metawidget.xml (see Section 2.7, “metawidget.xml and ConfigReader”):

<swingMetawidget xmlns="java:org.metawidget.swing">
	<inspectionResultProcessors>
		<array>
			<myInspectionResultProcessor xmlns="java:com.myapp"/>
		</array>
	</inspectionResultProcessors>
</swingMetawidget>

This allows easy plugging in of alternate InspectionResultProcessors.

Most Metawidgets have default InspectionResultProcessors. Overriding the default means the default is no longer instantiated. This may not be what you want, so you may want to instantiate the default along with your new InspectionResultProcessor. You can see the default by looking in the Metawidget JAR for the file metawidget-xxx-default.xml (where xxx is your target platform, such as swing or struts).

For reference, the defaults are:

<array>
	<comesAfterInspectionResultProcessor />
</array>

new metawidget.angular.inspectionresultprocessor.AngularInspectionResultProcessor(...)

<array>
	<comesAfterInspectionResultProcessor />
</array>

<array>
	<facesInspectionResultProcessor />
	<comesAfterInspectionResultProcessor />
</array>

<array>
	<jspInspectionResultProcessor />
	<comesAfterInspectionResultProcessor />
</array>

<array>
	<comesAfterInspectionResultProcessor />
</array>

<array>
	<comesAfterInspectionResultProcessor />
</array>

<array>
	<comesAfterInspectionResultProcessor />
</array>

<array>
	<comesAfterInspectionResultProcessor />
</array>

All InspectionResultProcessors are required to be immutable. This means you only need a single instance of an InspectionResultProcessor for your entire application. If you are using metawidget.xml then ConfigReader takes care of this for you, but if you are instantiating InspectionResultProcessors in Java code you should reuse instances.

Here is an example of a custom InspectionResultProcessor that chooses, and sorts, domain object properties based on a JComponent client property. It extends the code from the tutorial (see Section 1.1, “Part 1 (Java version) - The First Metawidget Application”).

package com.myapp;
			
import static org.metawidget.inspector.InspectionResultConstants.*;

import javax.swing.*;
import org.metawidget.swing.*;
import org.metawidget.inspectionresultprocessor.iface.*;
import org.metawidget.util.*;
import org.w3c.dom.*;

public class Main {

	public static void main( String[] args ) {
		Person person = new Person();

		SwingMetawidget metawidget = new SwingMetawidget();
		metawidget.addInspectionResultProcessor( new IncludingInspectionResultProcessor() );
		metawidget.putClientProperty( "include", new String[]{ "retired", "age" } );
		metawidget.setToInspect( person );

		JFrame frame = new JFrame( "Metawidget Tutorial" );
		frame.setDefaultCloseOperation( JFrame.EXIT_ON_CLOSE );
		frame.getContentPane().add( metawidget );
		frame.setSize( 400, 250 );
		frame.setVisible( true );
	}
	
	static class IncludingInspectionResultProcessor
		implements InspectionResultProcessor<SwingMetawidget> {
		
		public String processInspectionResult( String inspectionResult, SwingMetawidget metawidget,
		                                       Object toInspect, String type, String... names ) {
		
			String[] includes = (String[]) metawidget.getClientProperty( "include" );
			Document document = XmlUtils.documentFromString( inspectionResult );
			Element entity = (Element) document.getDocumentElement().getFirstChild();			
			int propertiesToCleanup = entity.getChildNodes().getLength();

			// Pull out the names in order

			for( String include : includes ) {
			
				Element property = XmlUtils.getChildWithAttributeValue( entity, NAME, include );

				if ( property == null )
					continue;

				entity.appendChild( property );
				propertiesToCleanup--;
			}

			// Remove the rest

			for( int loop = 0; loop < propertiesToCleanup; loop++ ) {
				entity.removeChild( entity.getFirstChild() );
			}

			return XmlUtils.documentToString( document, false );
		}
	}
}

	Note
	We don't necessarily recommend this approach, as it requires hard-coding business property names into your UI screens and won't refactor well. See Chapter 9, How To's for other approaches.

Like Inspectors, WidgetBuilders, WidgetProcessors and Layouts, InspectionResultProcessors are required to be immutable. However they will occasionally need to store some internal state, such as which sort order to use. This can be achieved in two ways:

All WidgetBuilders must implement the WidgetBuilder interface. This is a simple interface that defines only one method:

W buildWidget( String elementName, Map<String, String> attributes, M metawidget )

Where W is a widget type (such as JComponent or UIComponent) and M is a Metawidget type (such as SwingMetawidget or UIMetawidget).

Each WidgetBuilder must look to the elementName (which is typically just 'property' or 'action' from the inspection-result) and to the various attributes (as parsed from the inspection-result) and instantiate an appropriate widget. WidgetBuilders can use the given metawidget to help them if needed (e.g. to access a UI context with which to instantiate widgets). Typically the WidgetBuilders do not need to configure the widget beyond simply instantiating it: the job of setting ids, attaching validators, configuring bindings and so forth is done by the WidgetProcessors (see Section 2.5, “WidgetProcessors”).

Unless explicitly specified, each Metawidget will instantiate default WidgetBuilders to match the target platform. For example, SwingMetawidget will by default instantiate an OverriddenWidgetBuilder, WidgetBuilder and SwingWidgetBuilder.

This default behaviour can be overridden either in code:

metawidget.setWidgetBuilder( new MyWidgetBuilder() );

Or via metawidget.xml (see Section 2.7, “metawidget.xml and ConfigReader”):

<swingMetawidget xmlns="java:org.metawidget.swing">
	<widgetBuilder>
		<myWidgetBuilder xmlns="java:com.myapp"/>
	</widgetBuilder>
</swingMetawidget>

This allows easy plugging in of third-party widget libraries. Note that overriding the default means the default is no longer instantiated. In the example above, this would mean MyWidgetBuilder is used but OverriddenWidgetBuilder, ReadOnlyWidgetBuilder and SwingWidgetBuilder are not. This is usually not what you want, because MyWidgetBuilder will be focused on a particular third party library and will want to leave widget overriding to OverriddenWidgetBuilder, read-only widgets (i.e. labels) to ReadOnlyWidgetBuilder and standard widgets to SwingWidgetBuilder.

To achieve this, use CompositeWidgetBuilder.

The WidgetBuilder interface only has a single method. This allows it to take advantage of future Java language features such as:

final Object someObject = ...;

metawidget.setWidgetBuilder(
	#(String name, Map<String, String> attr, SwingMetawidget m)
	{ ... } );

However for those needing more control over the WidgetBuilder lifecycle there is an extended interface AdvancedWidgetBuilder. This interface defines two additional methods:

void onStartBuild( M metawidget );
				
void onEndBuild( M metawidget );

The first method, onStartBuild, is called at the start of the widget building process. WidgetBuilders may wish to act on this event to initialize themselves ready for processing. However it is acceptable to do nothing.

The last method, onEndBuild, is called at the end of the widget building process, after all widgets have been built and added to the Layout. WidgetBuilders may wish to act on this event to clean themselves up following processing. However it is acceptable to do nothing.

CompositeWidgetBuilder combines the widget libraries of several WidgetBuilders. It defers widget building to an internal list of WidgetBuilders, in order, and goes with the first one that returns non-null (see figure Figure 2.5).

Figure 2.5. CompositeWidgetBuilder composes multiple WidgetBuilders into one

In this way WidgetBuilders for third party UI component libraries (that provide specialized components) can be listed first, and WidgetBuilders for the platform's standard components can be listed last (as a 'fallback' choice).

CompositeWidgetBuilder can be instantiated either in code:

metawidget.setWidgetBuilder( new CompositeWidetBuilder( new CompositeWidgetBuilderConfig()
	.setWidgetBuilders(
		new OverriddenWidgetBuilder(), new ReadOnlyWidgetBuilder(),
		new MyWidgetBuilder(), new SwingWidgetBuilder()
	)));

Or via metawidget.xml (see Section 2.7, “metawidget.xml and ConfigReader”):

<swingMetawidget xmlns="java:org.metawidget.swing">
	<widgetBuilder>
		<compositeWidgetBuilder
			xmlns="java:org.metawidget.widgetbuilder.composite"
			config="CompositeWidgetBuilderConfig">
			<widgetBuilders>
				<array>
					<overriddenWidgetBuilder xmlns="java:org.metawidget.swing.widgetbuilder"/>
					<readOnlyWidgetBuilder xmlns="java:org.metawidget.swing.widgetbuilder"/>
					<myWidgetBuilder xmlns="java:com.myapp"/>
					<swingWidgetBuilder xmlns="java:org.metawidget.swing.widgetbuilder"/>
				</array>
			</widgetBuilders>
		</compositeWidgetBuilder>
	</widgetBuilder>
</swingMetawidget>

The first WidgetBuilder in the CompositeWidgetBuilder chain should generally be an OverriddenWidgetBuilder. This looks for existing child widgets that override default generation. What consitutes an 'overridden widget' varies from platform to platform. For example, for Swing any child widget with the same name will be taken as the override (see Section 1.1.8, “Controlling Widget Creation”). Android uses the tag attribute, JSF uses the value binding, and so on. For details on the OverriddenWidgetBuilder for your platform see Chapter 6, WidgetBuilders.

You can also choose to plug-in your own WidgetBuilder that detects 'overridden widgets' based on your own criteria. Here is an example of a custom WidgetBuilder that excludes widgets based on a JComponent client property. It extends the code from the tutorial (see Section 1.1, “Part 1 (Java version) - The First Metawidget Application”).

package com.myapp;
			
import static org.metawidget.inspector.InspectionResultConstants.*;

import java.util.*;

import javax.swing.*;
import org.metawidget.swing.*;
import org.metawidget.swing.widgetbuilder.*;
import org.metawidget.widgetbuilder.composite.*;
import org.metawidget.widgetbuilder.iface.*;
import org.metawidget.util.*;

public class Main {

	public static void main( String[] args ) {
		Person person = new Person();

		SwingMetawidget metawidget = new SwingMetawidget();
		metawidget.setWidgetBuilder( new CompositeWidgetBuilder<JComponent, SwingMetawidget>(
			new CompositeWidgetBuilderConfig<JComponent, SwingMetawidget>().setWidgetBuilders(
				new ExcludingWidgetBuilder(),
				new SwingWidgetBuilder() ) ) );
		metawidget.putClientProperty( "exclude", new String[]{ "age", "retired" } );
		metawidget.setToInspect( person );

		JFrame frame = new JFrame( "Metawidget Tutorial" );
		frame.setDefaultCloseOperation( JFrame.EXIT_ON_CLOSE );
		frame.getContentPane().add( metawidget );
		frame.setSize( 400, 250 );
		frame.setVisible( true );
	}
	
	static class ExcludingWidgetBuilder
		implements WidgetBuilder<JComponent, SwingMetawidget> {
		public JComponent buildWidget( String elementName, Map<String, String> attributes,
										SwingMetawidget metawidget ) {
			String[] exclude = (String[]) metawidget.getClientProperty( "exclude" );

			if ( ArrayUtils.contains( exclude, attributes.get( NAME )))
				return new Stub();

			return null;
		}
	}
}

	Note
	We don't necessarily recommend this approach, as it requires hard-coding business property names into your UI screens and won't refactor well.

	Note
	Although you could adapt this approach to only include (instead of exclude) certain properties, you could not adapt it to include properties in the order specified in the client property. This is because WidgetBuilders only operate on single widgets at a time. Instead, see Section 2.3, “Inspection Result Processors”

The second WidgetBuilder in the CompositeWidgetBuilder chain should generally be a ReadOnlyWidgetBuilder. This builds standard platform widgets for properties with read-only="true" or no-setter="true" (i.e. labels).

The exception to this rule would be if you wanted to add a custom WidgetBuilder for a widget library that had its own read-only components, or if you wanted to customise the read-only handling. Here is an example of a custom WidgetBuilder that returns non-editable JTextFields (instead of JLabels) for read-only properties. It extends the code from the tutorial (see Section 1.1, “Part 1 (Java version) - The First Metawidget Application”).

package com.myapp;
			
import static org.metawidget.inspector.InspectionResultConstants.*;

import java.util.*;

import javax.swing.*;
import org.metawidget.swing.*;
import org.metawidget.swing.widgetbuilder.*;
import org.metawidget.widgetbuilder.composite.*;
import org.metawidget.widgetbuilder.iface.*;
import org.metawidget.util.*;

public class Main {

	public static void main( String[] args ) {
		Person person = new Person();

		SwingMetawidget metawidget = new SwingMetawidget();
		metawidget.setWidgetBuilder( new CompositeWidgetBuilder<JComponent, SwingMetawidget>(
			new CompositeWidgetBuilderConfig<JComponent, SwingMetawidget>().setWidgetBuilders(
				new ReadOnlyTextFieldWidgetBuilder(),
				new SwingWidgetBuilder() ) ) );
		metawidget.setToInspect( person );

		JFrame frame = new JFrame( "Metawidget Tutorial" );
		frame.setDefaultCloseOperation( JFrame.EXIT_ON_CLOSE );
		frame.getContentPane().add( metawidget );
		frame.setSize( 400, 250 );
		frame.setVisible( true );
	}
	
	static class ReadOnlyTextFieldWidgetBuilder
		implements WidgetBuilder<JComponent, SwingMetawidget> {
		public JComponent buildWidget( String elementName, Map<String, String> attributes,
										SwingMetawidget metawidget ) {
			if ( !WidgetBuilderUtils.isReadOnly( attributes ) )
				return null;

			if ( TRUE.equals( attributes.get( HIDDEN )))
				return null;

			Class<?> clazz = ClassUtils.niceForName( attributes.get( TYPE ) );

			if ( String.class.equals( clazz ) || clazz.isPrimitive() ) {
				JTextField textField = new JTextField();
				textField.setEditable( false );

				return textField;
			}

			return null;
		}
	}
}

All Metawidgets have default WidgetBuilders. Overriding the default means the default is no longer instantiated. Usually this is not what you want, so you should consider instantiating the default along with your new WidgetBuilder (i.e. use CompositeWidgetBuilder). You can see the default by looking in the Metawidget JAR for the file metawidget-xxx-default.xml (where xxx is your target platform, such as swing or struts).

For reference, the defaults are:

<compositeWidgetBuilder config="CompositeWidgetBuilderConfig">
	<widgetBuilders>
		<array>
			<overriddenWidgetBuilder />
			<readOnlyWidgetBuilder />
			<androidWidgetBuilder />
		</array>
	</widgetBuilders>
</compositeWidgetBuilder>

new metawidget.widgetbuilder.CompositeWidgetBuilder( [
	new metawidget.widgetbuilder.OverriddenWidgetBuilder(),
	new metawidget.widgetbuilder.ReadOnlyWidgetBuilder(),
	new metawidget.widgetbuilder.HtmlWidgetBuilder()
] )

new metawidget.widgetbuilder.CompositeWidgetBuilder( [
	new metawidget.widgetbuilder.OverriddenWidgetBuilder(),
	new metawidget.jqueryui.widgetbuilder.JQueryUIWidgetBuilder(),	
	new metawidget.widgetbuilder.ReadOnlyWidgetBuilder(),
	new metawidget.widgetbuilder.HtmlWidgetBuilder()
] )

<compositeWidgetBuilder config="CompositeWidgetBuilderConfig">
	<widgetBuilders>
		<array>
			<overriddenWidgetBuilder />
			<readOnlyWidgetBuilder />
			<htmlWidgetBuilder />
		</array>
	</widgetBuilders>
</compositeWidgetBuilder>

<compositeWidgetBuilder config="CompositeWidgetBuilderConfig">
	<widgetBuilders>
		<array>
			<overriddenWidgetBuilder />
			<readOnlyWidgetBuilder />
			<htmlWidgetBuilder />
		</array>
	</widgetBuilders>
</compositeWidgetBuilder>

<compositeWidgetBuilder config="CompositeWidgetBuilderConfig">
	<widgetBuilders>
		<array>
			<overriddenWidgetBuilder />
			<readOnlyWidgetBuilder />
			<springWidgetBuilder />
		</array>
	</widgetBuilders>
</compositeWidgetBuilder>

<compositeWidgetBuilder config="CompositeWidgetBuilderConfig">
	<widgetBuilders>
		<array>
			<overriddenWidgetBuilder />
			<readOnlyWidgetBuilder />
			<strutsWidgetBuilder />
		</array>
	</widgetBuilders>
</compositeWidgetBuilder>

<compositeWidgetBuilder config="CompositeWidgetBuilderConfig">
	<widgetBuilders>
		<array>
			<overriddenWidgetBuilder />
			<readOnlyWidgetBuilder />
			<swingWidgetBuilder />
		</array>
	</widgetBuilders>
</compositeWidgetBuilder>

<compositeWidgetBuilder config="CompositeWidgetBuilderConfig">
	<widgetBuilders>
		<array>
			<overriddenWidgetBuilder />
			<readOnlyWidgetBuilder />
			<swtWidgetBuilder />
		</array>
	</widgetBuilders>
</compositeWidgetBuilder>

<compositeWidgetBuilder config="CompositeWidgetBuilderConfig">
	<widgetBuilders>
		<array>
			<overriddenWidgetBuilder />
			<readOnlyWidgetBuilder />
			<vaadinWidgetBuilder />
		</array>
	</widgetBuilders>
</compositeWidgetBuilder>

All WidgetBuilders are required to be immutable. This means you only need a single instance of a WidgetBuilder for your entire application. If you are using metawidget.xml then ConfigReader takes care of this for you, but if you are instantiating WidgetBuilders in Java code you should reuse instances.

Note that immutable only means WidgetBuilders cannot be changed once instantiated - it does not mean they cannot be configured. Many WidgetBuilders have corresponding xxxConfig classes that allow them to be configured prior to instantation in a type-safe way. For example, a HtmlWidgetBuilder can be configured in code:

metawidget.setWidgetBuilder( new HtmlWidgetBuilder( new HtmlWidgetBuilderConfig()
			.setDataTableStyleClass( "data-table" )));

Or in metawidget.xml (see Section 2.7, “metawidget.xml and ConfigReader”):

<htmlWidgetBuilder xmlns="java:org.metawidget.faces.component.html.widgetbuilder"
	config="HtmlWidgetBuilderConfig">
	<dataTableStyleClass>
		<string>data-table</string>
	</dataTableStyleClass>
</htmlWidgetBuilder>

The pluggable nature of WidgetBuilders makes it easy to add your own. Because CompositeWidgetBuilder can be used to chain WidgetBuilders together, you only need worry about supporting your particular widgets. You can simply return null for all other types of property and rely on another WidgetBuilder further down the chain to instantiate one of the usual widgets. For example, RichFacesWidgetBuilder only instantiates the RichFaces components, and returns null for everything else.

Here is an example of a custom WidgetBuilder that uses two JRadioButtons, instead of the usual JCheckBox, to represent boolean properties. It extends the code from the tutorial (see Section 1.1, “Part 1 (Java version) - The First Metawidget Application”).

package com.myapp;
			
import static org.metawidget.inspector.InspectionResultConstants.*;

import java.awt.*;
import java.util.*;
import javax.swing.*;
import org.metawidget.swing.*;
import org.metawidget.swing.widgetbuilder.*;
import org.metawidget.widgetbuilder.composite.*;
import org.metawidget.widgetbuilder.iface.*;

public class Main {

	public static void main( String[] args ) {
		Person person = new Person();

		SwingMetawidget metawidget = new SwingMetawidget();
		metawidget.setWidgetBuilder( new CompositeWidgetBuilder<JComponent, SwingMetawidget>(
			new CompositeWidgetBuilderConfig<JComponent, SwingMetawidget>().setWidgetBuilders(
				new JRadioButtonWidgetBuilder(),
				new SwingWidgetBuilder() ) ) );
		metawidget.setToInspect( person );

		JFrame frame = new JFrame( "Metawidget Tutorial" );
		frame.setDefaultCloseOperation( JFrame.EXIT_ON_CLOSE );
		frame.getContentPane().add( metawidget );
		frame.setSize( 400, 250 );
		frame.setVisible( true );
	}
	
	static class JRadioButtonWidgetBuilder
		implements WidgetBuilder<JComponent, SwingMetawidget> {

		public JComponent buildWidget( String elementName, Map<String, String> attributes,
			SwingMetawidget metawidget ) {
			
			if ( !"boolean".equals( attributes.get( TYPE ) ) )
				return null;

			JRadioButton trueButton = new JRadioButton( "True" );
			JRadioButton falseButton = new JRadioButton( "False" );
			JPanel panel = new JPanel();
			panel.setLayout( new GridLayout( 2, 1 ) );
			panel.add( trueButton );
			panel.add( falseButton );

			ButtonGroup buttonGroup = new ButtonGroup();
			buttonGroup.add( trueButton );
			buttonGroup.add( falseButton );

			return panel;
		}
	}
}

Like Inspectors, InspectionResultProcessors, WidgetProcessors and Layouts, WidgetBuilders are required to be immutable. However they will occasionally need to store some internal state, such as which CSS styls to use. This can be achieved in two ways:

	Config classes must override equals and hashCode
	If you want your configurable WidgetBuilder to be cacheable and reusable by ConfigReader and metawidget.xml, the xxxWidgetBuilderConfig class must override equals and hashCode.

Generate an XML Schema

If you intend your WidgetBuilder to be configurable via metawidget.xml, consider defining an XML Schema for it. This is optional, but allows users to validate their use of your WidgetBuilder in their metawidget.xml at development time. There is an Ant task, org.metawidget.config.XmlSchemaGeneratorTask, provided in the source distribution that can help with this by auto-generating the schema. All the existing Metawidget schemas are generated using this Ant task.

All WidgetProcessors must implement the WidgetProcessor interface. This is a simple interface that defines only one method:

W processWidget( W widget, String elementName, Map<String, String> attributes, M metawidget );

Where W is a widget type (such as JComponent or UIComponent) and M is a Metawidget type (such as SwingMetawidget or UIMetawidget).

processWidget is called for each widget built by the WidgetBuilders. WidgetProcessors can modify the given widget according to the given elementName (which is typically just 'property' or 'action' from the inspection-result) and the various attributes (as parsed from the inspection-result). They can use the given metawidget to help them if needed (e.g. to access a UI context with which to create validators).

The processWidget method must return the processed widget. This is typically the same as the given widget. The parent Metawidget then passes this to the next WidgetProcessor in the list as shown in Figure 2.6.

Figure 2.6. Typical WidgetProcessor list

In most cases the WidgetProcessor will simply be modifying the given widget (adding validators, changing styles and so on). However it can decide to swap the widget out by returning a different widget entirely. This new widget will then be passed down the list as shown in Figure 2.7. For an example use of this capability, see HiddenFieldProcessor.

Figure 2.7. WidgetProcessors can substitute widgets

Alternatively, the WidgetProcessor can decide to exclude the widget entirely by returning null. Subsequent WidgetProcessors will not be called, as shown in Figure 2.8, and no widget will be added to the Layout.

Figure 2.8. WidgetProcessors can exclude widgets

Some Metawidgets will instantiate default WidgetProcessors. This default behaviour can be overridden either in code:

metawidget.addWidgetProcessor( new MyWidgetProcessor() );

Or via metawidget.xml (see Section 2.7, “metawidget.xml and ConfigReader”):

<swingMetawidget xmlns="java:org.metawidget.swing">
	<widgetProcessors>
		<array>
			<myWidgetProcessor xmlns="java:com.myapp"/>
		</array>
	</widgetProcessors>
</swingMetawidget>

This allows easy plugging in of alternate WidgetProcessors. Note that overriding the default means the default is no longer instantiated. In the example above, this would mean MyWidgetProcessor is used but the default WidgetProcessors are not.

The list of WidgetProcessors is maintained by the parent Metawidget, and is changeable (this is different to say, CompositeInspector or CompositeWidgetBuilder whose lists are immutable). This capability is designed to allow easy attaching of event handlers, and scenarios such as inner classes that have connections to their parent class:

final Object someObject = ...;
				
metawidget.addWidgetProcessor( new WidgetProcessor<JComponent, SwingMetawidget>() {
	JComponent processWidget( JComponent widget, String elementName, Map<String, String> attributes,
											SwingMetawidget metawidget ) {

		...decide whether to attach event handler...
		
		widget.add( new AbstractAction() {
			public void actionPerformed( ActionEvent e ) {
				someObject.doSomething();
			}
		}	
	}
}

The WidgetProcessor interface only has a single method. This allows it to take advantage of future Java language features such as:

final Object someObject = ...;

metawidget.addWidgetProcessor(
	#(JComponent w, String name, Map<String, String> attr, SwingMetawidget m)
	{ w.add( #(ActionEvent e) { someObject.doSomething() } ) } );

However for those needing more control over the WidgetProcessor lifecycle there is an extended interface AdvancedWidgetProcessor. This interface defines two additional methods:

void onStartBuild( M metawidget );
				
void onEndBuild( M metawidget );

Figure 2.9. onStartBuild and onEndBuild are called once, processWidget is called for each widget

The first method, onStartBuild, is called at the start of the widget building process, before the WidgetBuilder is called. WidgetProcessors may wish to act on this event to initialize themselves ready for processing. However it is acceptable to do nothing.

The last method, onEndBuild, is called at the end of the widget building process, after all widgets have been built and added to the Layout. WidgetProcessors may wish to act on this event to clean themselves up following processing. However it is acceptable to do nothing.

Some Metawidgets have default WidgetProcessors. Overriding the default means the default is no longer instantiated. This may not be what you want, so you may want to instantiate the default along with your new WidgetProcessor. You can see the default by looking in the Metawidget JAR for the file metawidget-xxx-default.xml (where xxx is your target platform, such as swing or struts).

For reference, the defaults are:

<array>
	<simpleBindingProcessor />
	<reflectionBindingProcessor />
	<disabledAttributeProcessor />
</array>

[
	new metawidget.widgetprocessor.IdProcessor(),
	new metawidget.widgetprocessor.PlaceholderAttributeProcessor(),
	new metawidget.widgetprocessor.DisabledAttributeProcessor(),
	new metawidget.angular.widgetprocessor.AngularWidgetProcessor(...)
]

[
	new metawidget.widgetprocessor.IdProcessor(),
	new metawidget.widgetprocessor.RequiredAttributeProcessor(),
	new metawidget.widgetprocessor.PlaceholderAttributeProcessor(),
	new metawidget.widgetprocessor.DisabledAttributeProcessor(),
	new metawidget.widgetprocessor.SimpleBindingProcessor()
]

[
	new metawidget.widgetprocessor.IdProcessor(),
	new metawidget.widgetprocessor.RequiredAttributeProcessor(),
	new metawidget.widgetprocessor.PlaceholderAttributeProcessor(),
	new metawidget.widgetprocessor.DisabledAttributeProcessor(),
	new metawidget.jqueryui.widgetprocessor.JQueryUIBindingProcessor(),	
	new metawidget.widgetprocessor.SimpleBindingProcessor()
]

<array>
	<requiredAttributeProcessor />
	<immediateAttributeProcessor />
	<standardBindingProcessor />
	<readableIdProcessor />
	<labelProcessor />
	<standardValidatorProcessor />
	<standardConverterProcessor />
	<cssStyleProcessor />							
</array>

<array>
	<pathProcessor />
	<cssStyleProcessor />							
</array>

<array>
	<nameProcessor />
	<cssStyleProcessor />							
</array>

<array>
	<reflectionBindingProcessor />
</array>

<array>
	<reflectionBindingProcessor />
</array>

<array>
	<simpleBindingProcessor />
	<reflectionBindingProcessor />
	<captionProcessor />
	<requiredProcessor />
	<minimumMaximumValidatorProcessor />
</array>

All WidgetProcessors are required to be immutable. This means you only need a single instance of a WidgetProcessor for your entire application. If you are using metawidget.xml then ConfigReader takes care of this for you, but if you are instantiating WidgetProcessors in Java code you should reuse instances.

Although individual WidgetProcessors are immutable, the List they are contained in can be changed. Methods such as addWidgetProcessor allows clients to dynamically add WidgetProcessors at runtime. This is useful for adding event handlers (see Section 2.5.1, “Interface”).

Note that immutable only means WidgetProcessors cannot be changed once instantiated - it does not mean they cannot be configured. Many WidgetProcessors have corresponding xxxConfig classes that allow them to be configured prior to instantation in a type-safe way. For example, a BeansBindingProcessor can be configured in code:

metawidget.addWidgetProcessor( new BeansBindingProcessor( new BeansBindingProcessorConfig()
			.setUpdateStrategy( UpdateStrategy.READ_WRITE )));

Or in metawidget.xml (see Section 2.7, “metawidget.xml and ConfigReader”):

<beansBindingProcessor xmlns="java:org.metawidget.swing.widgetprocessor.binding.beansbinding"
	config="BeansBindingProcessorConfig">
	<updateStrategy>
		<enum>READ_WRITE</enum>
	</updateStrategy>
</beansBindingProcessor>

Here is an example of a custom WidgetProcessor to add tooltips to JComponents. It extends the code from the tutorial (see Section 1.1, “Part 1 (Java version) - The First Metawidget Application”).

package com.myapp;
	
import static org.metawidget.inspector.InspectionResultConstants.*;
import java.util.*;
import javax.swing.*;
import org.metawidget.swing.*;
import org.metawidget.widgetprocessor.iface.*;

public class Main {

	public static void main( String[] args ) {
		Person person = new Person();

		SwingMetawidget metawidget = new SwingMetawidget();
		metawidget.addWidgetProcessor( new TooltipProcessor() );
		metawidget.setToInspect( person );

		JFrame frame = new JFrame( "Metawidget Tutorial" );
		frame.setDefaultCloseOperation( JFrame.EXIT_ON_CLOSE );
		frame.getContentPane().add( metawidget );
		frame.setSize( 400, 250 );
		frame.setVisible( true );
	}

	static class TooltipProcessor
		implements WidgetProcessor<JComponent, SwingMetawidget> {
		
		public JComponent processWidget( JComponent widget, String elementName,
										 Map<String, String> attributes, SwingMetawidget metawidget ) {
			widget.setToolTipText( attributes.get( NAME ) );
			return widget;
		}
	}
}

Like Inspectors, InspectionResultProcessors, WidgetBuilders and Layouts, WidgetProcessors are required to be immutable. However they will generally need to store some internal state, such as tracking the prefix for the tooltip. This can be achieved in two ways:

All Layouts must implement the Layout interface. This is a simple interface that defines only one method:

void layoutWidget(W widget,String elementName,Map<String,String> attributes,C container,M metawidget);

Where W is a widget type (such as JComponent or UIComponent) and M is a Metawidget type (such as SwingMetawidget or UIMetawidget).

Where W is a widget type (i.e. Control, JComponent etc), C is widget container type (i.e. Composite, JComponent etc) and M is a Metawidget type (i.e. SwtMetawidget, SwingMetawidget etc). Don't be put off by having so many parameterized types! Metawidget needs them so that it can present a consistent API across many architectures. However this complication doesn't impact your own custom plugins because you're able to substitute concrete, platform-specific values for each parameter (i.e. Control, Composite, SwtMetawidget ).

layoutWidget is called for each widget. Layouts should add the given widget as a child of the given container, according to the given elementName (which is typically just 'property' or 'action' from the inspection-result) and the various attributes (as parsed from the inspection-result). They can use the given metawidget to access additional services if needed (such as state saving beween invocations, see Section 2.6.7, “Implementing Your Own Layout”).

layoutWidget is called 'in-place'

layoutWidget is called immediately after WidgetBuilder.buildWidget and WidgetProcessor.processWidget, and before the next widget is generated. An alternate design would be to 'collect' all widgets generated by buildWidget and processWidget, then iterate over them separately for the layout. If you prefer this approach, you can simulate it by having layoutWidget do nothing but 'remember' each widget, then iterate over them in endContainerLayout (see Section 2.6.2, “Advanced Interface”). However not all UI frameworks allow this approach, because they do not suport widgets being instantiated independent of a layout, nor moved between layouts (e.g. SWT).

The Layout interface only has a single method. However for those needing more control over the Layout lifecycle there is an extended interface AdvancedLayout. This interface defines four additional methods:

void onStartBuild(M metawidget);
				
void startContainerLayout(W container, M metawidget);
				
void endContainerLayout(W container, M metawidget);

void onEndBuild(M metawidget);

Figure 2.10. startContainerLayout and endContainerLayout are called for each container, layoutWidget is called for each widget

The first method, onStartBuild, is called at the start of the widget building process, before the WidgetBuilder is called. Layouts may wish to act on this event to initialize themselves ready for processing, or to perform 'outermost-container-only' processing, such as adding toolbar facets. However it is acceptable to do nothing.

The second method, startContainerLayout, is called to initialize the given container. It is acceptable to do nothing.

The third method, endContainerLayout, is called to finish the given container. It is acceptable to do nothing.

The last method, onEndBuild, is called at the end of the widget building process, after all widgets have been built and added to the Layout. Layouts may wish to act on this event to clean themselves up following processing, or to perform 'outermost-container-only' processing, such as adding status bar facets. However it is acceptable to do nothing.

LayoutDecorator allows you to combine multiple Layouts together in a heirarchy. Conceptually, this is similar to CompositeInspector or CompositeWidgetBuilder, but Layouts are fundamentally different in that most are 'end points' that cannot sensibly be composed into sequential lists (i.e. what should happen if you try to combine a GridBagLayout with a FlowLayout?).

Rather, Layouts must be combined heirarchically, with an 'outer' Layout delegating to a single 'inner' Layout. LayoutDecorator is an abstract class that can be extended in order to decorate other Layouts. For example, GridBagLayout can be decorated using TabbedPaneLayoutDecorator to add tabbed section functionality.

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

A LayoutDecorator can also decorate another LayoutDecorator to provide fine-grained control over nested sections. For example, the domain object...

public class Person {
	@UiSection( { "Person", "Name" } )
	public String firstname;
	
	public String surname;
	
	@UiSection( { "Person", "Contact Detail" } )
	public String telephone;
}

...could be rendered using nested TabbedPaneLayoutDecorators...

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

...as shown in Figure 2.11.

Figure 2.11. Nested TabbedPaneLayoutDecorators

Alternatively, it could use a TabbedPaneLayoutDecorator nested within a SeparatorLayoutDecorator...

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

...as shown in Figure 2.12.

Figure 2.12. TabbedPaneLayoutDecorator within a SeparatorLayoutDecorator

Or the opposite - a SeparatorLayoutDecorator nested within a TabbedPaneLayoutDecorator...

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

...as shown in Figure 2.13.

Figure 2.13. SeparatorLayoutDecorator within a TabbedPaneLayoutDecorator

Unless explicitly specified, each Metawidget will instantiate a default Layout. This default behaviour can be overridden either in code:

metawidget.setLayout( new MyLayout() );

Or via metawidget.xml (see Section 2.7, “metawidget.xml and ConfigReader”):

<swingMetawidget xmlns="java:org.metawidget.swing">
	<layout>
		<myLayout xmlns="java:com.myapp"/>
	</layout>
</swingMetawidget>

This allows easy plugging in of alternate Layouts.

All Metawidgets have default Layouts. You can see the default by looking in the Metawidget JAR for the file metawidget-xxx-default.xml (where xxx is your target platform, such as swing or struts).

For reference, the defaults are:

<textViewLayoutDecorator config="TextViewLayoutDecoratorConfig">
	<layout>
		<tableLayout />
	</layout>
</textViewLayoutDecorator>

new metawidget.layout.HeadingTagLayoutDecorator(
	new metawidget.layout.TableLayout()
)

<outputTextLayoutDecorator config="OutputTextLayoutDecoratorConfig">
		<layout>
			<simpleLayout/>
		</layout>
	</outputTextLayoutDecorator>

<headingTagLayoutDecorator config="HeadingTagLayoutDecoratorConfig">
	<layout>
		<htmlTableLayout/>
	</layout>
</headingTagLayoutDecorator>

<headingTagLayoutDecorator config="HeadingTagLayoutDecoratorConfig">
	<layout>
		<springTableLayout/>
	</layout>
</headingTagLayoutDecorator>

<headingTagLayoutDecorator config="HeadingTagLayoutDecoratorConfig">
	<layout>
		<htmlTableLayout/>
	</layout>
</headingTagLayoutDecorator>

<separatorLayoutDecorator config="SeparatorLayoutDecoratorConfig">
	<layout>
		<gridBagLayout/>
	</layout>
</separatorLayoutDecorator>

<separatorLayoutDecorator config="SeparatorLayoutDecoratorConfig">
	<layout>
		<gridLayout/>
	</layout>
</separatorLayoutDecorator>

<headingTagLayoutDecorator config="HeadingTagLayoutDecoratorConfig">
	<layout>
		<formLayout/>
	</layout>
</separatorLayoutDecorator>

All Layouts are required to be immutable. This means you only need a single instance of a Layout for your entire application. If you are using metawidget.xml then ConfigReader takes care of this for you, but if you are instantiating Layouts in Java code you should reuse instances.

Note that immutable only means Layouts cannot be changed once instantiated - it does not mean they cannot be configured. Many Layouts have corresponding xxxConfig classes that allow them to be configured prior to instantation in a type-safe way. For example, an HtmlTableLayout can be configured in code:

metawidget.setLayout( new HtmlTableLayout( new HtmlTableLayoutConfig().setNumberOfColumns( 2 ));

Or in metawidget.xml (see Section 2.7, “metawidget.xml and ConfigReader”):

<htmlTableLayout xmlns="java:org.metawidget.jsp.tagext.html.layout"
	config="HtmlTableLayoutConfig">
	<numberOfColumns>
		<int>2</int>
	</numberOfColumns>
</htmlTableLayout>

Here is an example of a custom Layout that arranges components in a bulleted HTML list. It could be useful for, say, arranging action elements that were represented by HTML anchor tags:

package com.myapp;

import java.util.*;
import javax.servlet.jsp.*;
import javax.servlet.jsp.tagext.*;
import org.metawidget.jsp.*;
import org.metawidget.jsp.tagext.*;
import org.metawidget.layout.iface.*;

public class HtmlListLayout
	implements AdvancedLayout<Tag, MetawidgetTag> {
	
	public void onStartBuild( MetawidgetTag metawidgetTag ) {}

	public void startContainerLayout( Tag containerTag, MetawidgetTag metawidgetTag ) {
		try {
			JspWriter writer = metawidgetTag.getPageContext().getOut();
			writer.write( "<ul>" );
		} catch ( Exception e ) {
			throw LayoutException.newException( e );
		}
	}

	public void layoutChild( Tag tag, String elementName, Map<String, String> attributes,
		Tag containerTag, MetawidgetTag metawidgetTag ) {
		try {
			JspWriter writer = metawidgetTag.getPageContext().getOut();
			writer.write( "<li>" );
			writer.write( JspUtils.writeTag( metawidgetTag.getPageContext(), tag, containerTag, null ) );
			writer.write( "</li>" );
		} catch ( Exception e ) {
			throw LayoutException.newException( e );
		}
	}

	public void endContainerLayout( Tag containerTag, MetawidgetTag metawidgetTag ) {
		try {
			JspWriter writer = metawidgetTag.getPageContext().getOut();
			writer.write( "</ul>" );
		} catch ( Exception e ) {
			throw LayoutException.newException( e );
		}
	}
	
	public void onEndBuild( MetawidgetTag metawidgetTag ) {}	
}

Like Inspectors, InspectionResultProcessors, WidgetBuilders and WidgetProcessors, Layouts are required to be immutable. However they will generally need to store some internal state, such as tracking the current row in a table layout. This can be achieved in two ways:

ConfigReader can construct new instances of objects. The XML element name is the Java class name and the XML namespace (xmlns) is the Java package. The following example constructs an org.metawidget.swing.SwingMetawidget.

<metawidget xmlns="http://metawidget.org"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation="http://metawidget.org http://metawidget.org/xsd/metawidget-1.0.xsd">

	<swingMetawidget xmlns="java:org.metawidget.swing"/>
	
</metawidget>			

Using the XML namespace to denote the Java package allows the (optional) plugging in of XML Schema validation on a per-package basis. For example: