7.4 Form Design

Form Design XML
Supported Expressions
Enable Form Designs
Import/Export
Select/Configure Form Design
Form Design for Embedded Objects

Form design is used to customize entity view(content and layout) including views of nested entity and entity list beans.

Form Design XML

Form design is an XML file with viewConfig, layoutCode and css stylesheet. layoutCode is a HTML code with embedded #{expression}. For example, a form design for ExpenseClaim of the example HR module:


<formDesign entityType="EC" id="1001" name="#{bundle.FormDesign.ExpenseClaimStandard}">

	<viewConfig>
		<viewConfig name="expenseClaimItems">
			<viewType>ENTITY_LIST_NARROW</viewType>
			<pageable>false</pageable>
		</viewConfig>
	</viewConfig>

	<layout><![CDATA[<div class="ui-form-design">

		<h1>#{bundle.ExpenseClaim}</h1>

		<div class="ui-grid ui-grid-2 ui-grid-name-value">
			<div>#{bundle.Id}:</div>
			<div>#{nid}</div>

			<div>#{bundle.Summary}:</div>
			<div>#{summary}</div>

			<div>#{bundle.Employee}:</div>
			<div>#{employee}</div>

			<div class="ui-grid-colspan-2">#{OBJECT:expenseClaimItems}</div>

			<div>#{bundle.Approver}:</div>
			<div>#{approver}</div>

			<div>#{bundle.ApprovedDate}:</div>
			<div>#{approvedDate}</div>

			<div>#{bundle.Creator}:</div>
			<div>#{creator}</div>

			<div>#{bundle.CreatedDate}:</div>
			<div>#{createdDate}</div>
		</div>

	</div>]]></layout>
	<style><![CDATA[
		.ui-form-design h1 {
			text-align: center;
		}
	]]></style>
</formDesign>

Form bean (nested bean) viewConfig name is its property name. The list of expense claim items is not pageable (one page) in the example above. All the expressions #{expression} in layout code will be resolved when the view is rendered.

Supported Expressions

Resource bundle: The expression #{bundle.Name} will be resolved using the resource bundle of current locale.
Properties: #{propertyName} will be resolved to its EntityProperty. If the property is not enabled for editing, the view component will be in read-only mode, or rendered as text.
Form bean properties: #{OBJECT:formBeanPropertyName} will be resolved to its EntityFormBeanProperty. For example, #{OBJECT:expenseClaimItems} will be resolved to the expenseClaimItems property whose form bean is the EntityListBackingBean of its ExpenseClaimItem entities. (form beans are nested beans).

Enable Form Designs

To enable form designs for entity types in a module, define FormDesignDescriptor(s) in module implementation class. For example, to enable form designs for ExpenseClaim of the example HR module:


	@Override
	public Map<Class, FormDesignDescriptor> getFormDesignDescriptorMap() {
		Map<Class, FormDesignDescriptor> formDesignViewConfigDescriptorMap = new LinkedHashMap<Class, FormDesignDescriptor>();
		
		// ExpenseClaim, use default FormDesign implementation
		ViewConfigDescriptor ecViewConfigDescriptor = new ViewConfigDescriptor(
			ExpenseClaim.PROPERTY_EXPENSE_CLAIM_ITEMS, ViewType.ENTITY_LIST_NARROW,
			null, true
		);
		formDesignViewConfigDescriptorMap.put(ExpenseClaim.class, 
			new FormDesignDescriptor(null, new ViewConfigDescriptor[]{ecViewConfigDescriptor}));
		
		return formDesignViewConfigDescriptorMap;
	}

To add a menu node for managing Form Designs of a module, call getFormDesignTypeDescriptor(viewConfig) to get the TypeDescriptor for FormDesign, and then add it to the module menu. For example,


public class HrMenuNodeFactory extends ModuleMenuNodeFactory {

	@Override
	protected void createSubMenu() throws SystemException {
		MenuViewConfig viewConfig = this.viewConfig.clone();

		MenuNode settingsMenuNode = addSettingsMenuNode(rootMenuNode);

		TypeDescriptor[] settingTypes = new TypeDescriptor[] {
			getFormDesignTypeDescriptor(viewConfig)
		};
		addTypedMenuNodes(this, settingsMenuNode, settingTypes);
	}
}

Import/Export

If a module provides form designs for an entity type, they will automatically be available and do not need to import them. To make changes to a form design provided by a module, first import the form design and then make changes. It will overshadow the one provided by the module by using the same form id.

Import form designs from system (provided by module), click "Import/System" under the "Form Designs" menu node. For example,

	Settings > Form Designs > Import/System.

Form designs can be exported to external files, and imported from external files.

Select/Configure Form Design

Form Designs including those provided by module and created(or imported) by user are available for customizing entity view. By default, the FormDesign marked with "default" will be used. If user selects a FormDesign for an entity view, the selection will be remembered for all entities of the same type.

When setting a Form Design programmatically in ViewConfig, it can be an existing FormDesign or a new FormDesign object. For example,

Create a lazy loading FormDesign by setting its formId and partiallyInitialized.


	EntityViewConfig viewConfig = new EntityViewConfig(ViewType.ENTITY);
	
	FormDesign formDesign = TypeMapping.newImplementationInstance(FormDesign.class);
	DataType entityType = TypeMapping.getInstance().getDataTypeExactly(ExpenseClaim.class);
	formDesign.setEntityType(entityType);
	formDesign.setFormId("1001");
	formDesign.setPartiallyInitialized(true);
	
	viewConfig.setFormDesign(formDesign);

Create a new FormDesign object with layout code for Employee.


	EntityViewConfig viewConfig = new EntityViewConfig(ViewType.ENTITY);
	FormDesign formDesign = TypeMapping.newImplementationInstance(FormDesign.class);
	formDesign.setLayout("#{photos}<br/>#{name} #{department}");
	formDesign.setDecoded(true);
	viewConfig.setFormDesign(formDesign);

Form Design for Embedded Objects

For an embedded object, use viewConfig XML to configure a Form Design to render an entity. For example, use ExpenseClaim form design 0001.


<object xmlns="http://www.cmobilecom.com/af/objects" type="entity">
	<entityType>ExampleHR.EC</entityType>
	<mode>VIEW</mode>

	<criteriaElements>
		<function name="EQ" property="nid">100</function>
	</criteriaElements>

	<viewConfig>
		<viewType>ENTITY</viewType>
		
		<formDesign type="System.FD">
			<entityType>ExampleHR.EC</entityType>
			<formId>0001</formId>
		</formDesign>
		
	</viewConfig>
</object>

type and entityType are optional. FormDesign type is default to System.FD (the FormDesign implementation in System module), and entityType will be obtained from its EntityBackingBean.


	<viewConfig>
		<viewType>ENTITY</viewType>
		
		<formDesign >
			<formId>0001</formId>
		</formDesign>
		
	</viewConfig>

Create a new FormDesign with layout code and optional style sheet. For example,


	<viewConfig>
		<viewType>ENTITY</viewType>
		
		<formDesign>
			<layout><![CDATA[#{photos}<br/>#{name} #{department}]]></layout>
			<style>...</style>
		</formDesign>
		
	</viewConfig>

← Property Annotations→ Entity Form SupportFrames / No Frames