21 XML Layout Code

Layout code is platform-independent XML that supports expressions and embedded objects. Embedded objects include regions, pages, beans and properties. XML layout code will be bound to client platform view. XML layout code is used in border layout, form design (Entity/EntityList) and page. For example, a layout code for showing employee photos and info for each employee entity row:

	<row>
		<property width="200px">photos</property>
		<spacer width="20px"/>
		<column>
			<row>
				<property>name</property>
				<spacer width="20px"/>
				<text>#{bundle.Birthday}:</text>
				<property>birthday</property>
			</row>
			<row>
				<text>#{bundle.HiredDate}:</text>
				<property>hiredDate</property>
				<spacer width="20px"/>
				<property>type</property>
			</row>
		</column>
	</row>

Elements

Layout code consists of hierarchical XML elements and must be a well-formed XML document.

All elements can have the following attributes:
- rendered: EL boolean expression. If its value is evaluated to be false, the element and its descendants will be ignored. See EL Expressions for supported EL expressions.
- padding: element padding. Its value is of format "top right bottom left".
Container elements(row, column, grid) can have attribute "childPadding" for children and alignment attributes to align children.
If an attribute value is URL, the URL can be absolute, or relative to request contextPath if the url starting with forward slash (/), or relative to current page URL (otherwise).

Text

A Text component. Its text content can be inline, from URL or from a file.

	Hello World
	<text>Hello #{containerBean.authenticatedUser.username}: </text>
	<text url="absolute_or_relative_url" charset="UTF-8"/>
	<text file="path/foo.txt" charset="UTF-8"/>

A text can be added without <text> element.
Inline text content can contain EL expressions.
If its content is from a URL, the URL can be absolute or relative.
If its content is from a file, the file path is relative to current page file path.

Title

A Title element is a container component with a bigger font and top/bottom margin. It contains child elements as content and its attribute "size" specifies title size from 1 to 6 with "1" to be the biggest.

	<title size="1">Order Number: #{param.orderNumber}</title>

	<title size="1">
		<text>Order Number: #{param.orderNumber}</text>
	</title>

	<title size="2">
		<column>
			<text>#{instance.name}</text>
			<text>#{bundle.SalesOrder}</text>
		</column>
	</title>

Link

A link is a page navigation command and will redirect to a new URL when clicked.

	<link id="helloWorld" button="true" href="url" target="target1" browser="true">
		<column>
			<text>Hello World</text>
			<image src=""></image>
		</column>
	</link>

They have a single child element that may contain descendant elements. The attribute "href" value is page URL.

For multi-platform, the "browser" attribute indicates whether to open the new URL in default browser. If false (default), a new view will be built for the page URL, and it will be stacked on the top of current page(target is not empty) or replace current page(target is empty). In this case, the page must be a .xpg page or manageCenter.

For web, the "browser" attribute will be ignored (always true). If target is not empty, a new browser tab will be opened for the URL.

If button is true, the link will be styled as a button that has a border.

Image

Image element will render an image from src URL.

	<image src="url" title="description" width="300px" height="200px"/>

Width and height specify the image size. The title will be displayed if the image can not be retrieved, and is SEO friendly.

Grid

A grid has a fixed number of columns and unlimited number of rows. It lays out its children from left to right and top to bottom with one child in each grid cell. For example,

	<grid cols="2">
		<text>#{bundle.Name}</text>
		<property>name</property>
		<text>#{bundle.Birthday}</text>
		<property>birthday</property>
	</grid>

Attributes:

cols: specifies the number of columns.
flow: specifies how child items will be placed in the grid. Its value can be row or column. Default is row.
gap: specifies row and column gaps between child items. Its value is "row_gap column_gap". For example, "10px 5px".
colspan: specified on a child item for the number of columns to span.

Alignments:

justify-content: align grid along row-axis. Its value can be start (default), end, center, spaceBetween, spaceAround or spaceEvenly.
align-content: align grid along column-axis. Its value can be start (default), end, center, spaceBetween, spaceAround or spaceEvenly.
justify-items: align items inside each cell along row-axis. Its value can be start, end, center or stretch (default).
align-items: align items inside each cell along column-axis. Its value can be start, end, center or stretch (default).
justify-self: align items inside the cell itself along row-axis. Its value can be start, end, center or stretch (default).
align-self: align items inside the cell itself along column-axis. Its value can be start, end, center or stretch (default).

Column And Row

A column lays out its children in vertical direction. For example,

	<column>
		<title size="1">#{bundle.Name}</title>
		<bean id="login" type="login">
		</bean>
	</column>

A row lays out its children in horizontal direction. For example,

	<row>
		<text>#{bundle.Name}:</text>
		<property>name</property>
	</row>

Attributes:

wrap: specifies whether child items should wrap if necessary. Default: false.
gap: specifies row and column gaps between child items. Its value is "row_gap column_gap". For example, "10px 5px".

Alignments:

justify-content: align items along main-axis. Its value can be start (default), end, center, spaceBetween, spaceAround or spaceEvenly.
align-items: align items along cross-axis. Its value can be start (default), end, center, stretch and baseline.

For example,

	<row childPadding="0 2px" justify-content="center">
		<text>Powered by</text>
		<link href="https://platform.znize.com" target="_blank">
			<text>ZNize Platform</text>
		</link>
	</row>

	<column childPadding="0 2px" align-items="end">
		<text>Powered by</text>
		<link href="https://dev.znize.com" target="_blank">
			<text>ZNize Platform/JPA</text>
		</link>
	</column>

Container

A container element has zero or more child elements, which can be used for securing grid cell for conditionally-rendered child elements and styling.

Alignments:

justify-content: horizontal alignment. Its value can be left (default), center and right.
align-items: vertical alignment. Its value can be top (default), middle and bottom.

Nested LayoutCode

A nested layoutCode element has an EL expression as its textContent, which is resolved to XML layout code. For example,

	<layoutCode>#{bundle.RegistrationOverview}</layoutCode>

Resource bundle key "RegistrationOverview" for locale en:

	<column>
		<text>Register one account to access all the services on the cloud.</text>
		<row>
			<text>If you already have an account, </text>
			<link href="/login.xpg">Go to Login</link>
		</row>
	</column>

The nested layoutCode can be translated for different locales.

List and List Item

A list consists of list items. For example,

	<list ordered="true">
		<item>Foo Bar</item>
		<item>
			<text>Hello World!</text>
		</item>
		<item>
			<column>
				...
			</column>
		</item>
	</list>

The attribute "ordered" specifies whether the list is ordered or unordered. For an ordered list, items will be numbered starting from one. For an unordered list, each item will be prefixed with circle dot. Each list item element has one child element that may contain descendant elements.

Spacer

A spacer element adds a space in layout. For example,

	<spacer width="20px" height="30px"/>

For horizontal spacer, height is optional; For vertical spacer, width is optional.

Region

A region can be embedded in a border layout unit. For example,

	<borderLayout>
		<unit position="east">
			<column>
				<region number="5"/>
				<region number="6"/>
			</column>
		</unit>
	</borderLayout>

Two regions are embedded (vertically) in the "east" layout unit.

Bean

A bean can be embedded in a page. For example,

	<page>
		<head></head>
		<body>
			<column>
				<bean id="bean_1" type="beanType">

				</bean>
			</column>
		</body>
	</page>

See "Embedded Beans" guide for more details.

Property

A property can be embedded in entity or entityList form design layout code. For examples,

	<grid cols="2">
		<text>#{bundle.OrderId}</text>
		<property>nid</property>
		<text>#{bundle.Date}</text>
		<property>date</property>
		<container colspan="2">
			<property>orderItems</property>
		</container>
	</grid>

An embedded property can be a simple property such as "date" or a form bean property such as "orderItems" that is an EntityList bean. Property name can be set using attribute "name" or text context. Element <p> is short for <property>. So the followings are equivalent:

	<property>birthday</property>
	<property name="birthday"/>
	<p>birthday</p>
	<p name="birthday"/>

If the property is not found in the Entity/EntityList bean, it will be ignored. For example, <property>createdDate</property>, the property (createdDate) exists only after the entity is created on persistence.

Attributes

For a form bean property, attribute "bean" (boolean) can be used to specify whether to render the property as a regular property or its enclosed bean. default is "true". For example,

	<property bean="false">payment</property>

If the payment property has form bean (e.g., PaymentBean), the payment property will be rendered as a command link instead of an entity bean. The payment detail will be opened when the command link is clicked. Otherwise, the payment bean would be rendered in place.

App Bar

An appBar is the root element of the north layout unit of a container border layout, and contains regions and facets, which will be laid out accordingly as appBar on client native platform. For example,

	<regions>
		<region number="0">pageHeaderMenu</region>
		<region number="2">toolbar</region>
	</regions>

	<borderLayout>
		<unit position="north">
			<appBar>
				<facet name="logo" href="#{request.contextPath}/"/>
				<facet name="title"/>
				<region number="2"/>
				<region number="0"/>
			</appBar>
		</unit>
	</borderLayout>

The appBar is not regular XML layout code, and it contains contents only. It is up to client platform on how to lay out them. The appBar in the example above contains logo, title, region 2 and region 0. Region 2 and 0 are toolbar and page header menu respectively.

Facet logo and title show the logo and name of current InstanceType, which are configured in conf/system-config.xml.

	<instance-type id="myApp" name="MyApp">
		<version>1.0</version>
		<logo>/images/logo.png</logo>
	</instance-type>

The name is a key of resource bundles and will be translated for display for current locale. Logo URL is relative to request contextPath. For a site, site logo.png overrides default InstanceType logo. For example, the logo for main site:

	main/logo.png

See "Site" doc for site content directory layout.

A facet can have "href" attribute that is a page URL. When the facet is clicked, the app will navigate to the new page.

List View

The listView element is for EntityList bean to lay out entity rows in a list view (instead of table). So it is contained in entity list form design layout code. For example, The layout code for showing a list of employee entities:

	<formDesign>
		<layout>
			<column>
				<title size="1">
					<text>#{bundle.Employees}</text>
				</title>
				<listView>
					<entityRow>
						<row>
							<property>photos</property>
							<column>
								<row>
									<property>name</property>
									<property>birthday</property>
								</row>
								<row>
									<property>hiredDate</property>
									<property>type</property>
								</row>
							</column>
						</row>
					</entityRow>
				</listView>
			</column>
		</layout>
	</formDesign>

The child element of the entityRow element is the layout code for entity rows. For each entity row, the layout code and embedded properties for that row will be processed, and embedded properties are evaluated based on current entity row. For simplicity, text and/or spacer elements are omitted in the layout code.

Group

A group element is a logical grouping of child elements to apply common attributes or styling. It is a processing-time instruction and will not be mapped to a UI view component on client. Thus, its children are its parent's children. For example,

	<grid cols="2" childPadding="0 5px">
		<text>Hello World</text>

		<group rendered="#{expression}">
			<link href="url">Link One</link>
			<group>
				<button href="url">Button One</button>
			</group>
			<group childPadding="10px 10px">
				<button href="url">Button Two</button>
			</group>
		</group>
	</grid>

The "childPadding" of the Grid will apply to the Text(Hello World), the Link and the first Button. The 2nd group has the attribute "childPadding" that overrides the inherited value from the Grid, which would otherwise apply to the 2nd button. Each of the Grid's children (except groups) and the children under its groups will occupy one grid cell, and the groups will not be present on client view. For the example above, each of the Text, Link and two buttons will occupy one Grid cell.

Web

For a web element, its contents is XHTML that will be directly mapped to HTML for web browser. For example,

	<web>
		<div class="container">

		</div>
	</web>

	<web><![CDATA[
		<style>
			.container > .foo {
				background: white;
				border: 1px solid red;
			}
		</style>

		<div class="container">

		</div>
		]]>
	</web>

For a web attribute (with prefix web-) will be directly mapped to corresponding HTML attributes. For example, attribute web-class will be mapped to attribute class for HTML.

	<container web-class="ui-foo">

	</container>

web elements and attributes are not supported for multi-platform and will be ignored.

← Module Development→ EL ExpressionsFrames / No Frames