Embedded Objects - Entity

An object of type entity is an EntityBackingBean that is used to show a persisted entity, create a new entity or show a query form.

Show Entity

To show an existing entity, set mode to VIEW, and add criteriaElements as query criteria. For example, embed the employee with id 100 from HR module.


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

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

		<viewConfig>
			<viewType>ENTITY</viewType>
		</viewConfig>
	</object>

entityType: the string value of a DataType(mapped to a persistence entity type in a module), required. HR.EMP is mapped to the Employee entity type of the HR module.
mode: CREATE, VIEW, EDIT or QUERY. Ignored for query view since it will always be QUERY.
criteriaElements: criteria elements for building query criteria to retrieve the entity from persistence(view or edit mode), or initialize entity for create or query mode.
viewConfig: viewType can be ENTITY or QUERY, default is ENTITY.

Query

For query, set viewType to QUERY. Example: Query full-time employees


	<object xmlns="http://www.cmobilecom.com/af/objects"
			id="queryEmployees" type="entity">
		<entityType>HR.EMP</entityType>

		<criteriaElements>
			<function name="EQ" property="type">FULL_TIME</function>
		</criteriaElements>

		<viewConfig>
			<viewType>QUERY</viewType>
			<propertiesToHide>type</propertiesToHide>
		</viewConfig>
	</object>

Query supports search options such as group by and order by properties. For example, retrieve sum(order.total) group by customer, and order by customer(ascending) and sum(order.total) (descending).


	<object xmlns="http://www.cmobilecom.com/af/objects"
			id="queryOrders" type="entity">
		<entityType>Sales.SO</entityType>

		<criteriaElements>
			<function name="IS_NOT_NULL" property="payment"></function>
		</criteriaElements>

		<searchOptions>
			<groupBy>customer</groupBy>
			<asc property="customer"/>
			<desc property="total"/>
		</searchOptions>

		<viewConfig>
			<viewType>QUERY</viewType>
			<showSearchOptions>false</showSearchOptions>

			<viewConfig name="queryResults">
				<viewType>ENTITY_LIST_WIDE</viewType>
			</viewConfig>
		</viewConfig>
	</object>

Order.total is a statistics property(SUM), and "order by total" is actually order by sum(order.total) for group-by query. Refer to Entity Backing Bean on Statistics Properties.

Create Entity

For creating entity, set viewType to ENTITY and set mode to CREATE. Example: create an ExpenseClaim entity with ExpenseClaim items initialized.


	<object xmlns="http://www.cmobilecom.com/af/objects"
			id="createExpenseClaim" type="entity">
		<entityType>HR.EC</entityType>
		<mode>CREATE</mode>

		<criteriaElements>
			<function name="EQ" property="expenseClaimItems">
				<expenseClaimItem>
					<code>00</code>
					<expense>200.00</expense>
				</expenseClaimItem>

				<expenseClaimItem>
					<code>01</code>
					<expense>300.00</expense>
				</expenseClaimItem>
			</function>
		</criteriaElements>

		<viewConfig>
			<viewType>ENTITY</viewType>
		</viewConfig>

	</object>

Entity Not Found

If the embedded object is retrieving and showing an entity, but the entity is not found by the query criteria, how to deal with it? The viewConfig parameter entity.not.found will be consulted to determine what to return.


	<viewConfig>
		<viewType>ENTITY</viewType>
		<param name="entity.not.found" value="ignore" /> 
	</viewConfig>

Parameter: entity.not.found. (default: error)

ignore: the embedded object is null (not visible) without showing any error message.
error: the embedded object is a MapEntityBean showing an error message.
redirect: redirect a URL. For example, redirect:EntityNotFound will look for the redirect with action "EntityNotFound" in the viewConfig.

Parameter: entity.not.found.msg

If present, show the specified message instead of the default message if the entity is not found. The message will be shown even if the value of the parameter entity.not.found is ignore.

Example: redirect if entity is not found

When loading page /createExpenseClaim.xpg for submitting an ExpenseClaim, if the Employee entity is not found for current user, redirect to page /createEmployee.xpg to create the Employee entity. Redirect back to /createExpenseClaim.xpg after the Employee is created.

Page: /createExpenseClaim.xpg


	<object xmlns="http://www.cmobilecom.com/af/objects"
		id="checkEmployee" type="entity">
		<entityType>HR.EMP</entityType>
		<mode>VIEW</mode>

		<criteriaElements>
			<function name="EQ" property="user">#{current_user}</function>
		</criteriaElements>

		<viewConfig>
			<viewType>ENTITY</viewType>

			<!-- entity not found: redirect to a URL -->
			<param name="entity.not.found"  value="redirect:EntityNotFound" />

			<redirect action="EntityNotFound" toURL="/createEmployee.xpg">
				<add name="redirectAfterCreate" value="#{containerBean.viewInfo.bookmarkableURL}" />
			</redirect>

		</viewConfig>

		<hidden>true</hidden>
	</object>

	<object xmlns="http://www.cmobilecom.com/af/objects"
			id="createExpenseClaim" type="entity">
		<entityType>HR.EC</entityType>
		<mode>CREATE</mode>

		<viewConfig>
			<viewType>ENTITY</viewType>
		</viewConfig>
	</object>

Page: /createEmployee.xpg


	<object xmlns="http://www.cmobilecom.com/af/objects"
			id="createEmployee" type="entity">
		<entityType>HR.EMP</entityType>
		<mode>CREATE</mode>

		<criteriaElements>
			<function name="EQ" property="user">#{current_user}</function>
		</criteriaElements>

		<viewConfig>
			<viewType>ENTITY</viewType>

			<redirect action="cmd.Create"
				enabled="#{!empty param.redirectAfterCreate}"
				toURL="#{param.redirectAfterCreate}">
			</redirect>

		</viewConfig>
	</object>

Example: User Sign Up


	<object xmlns="http://www.cmobilecom.com/af/objects"
			id="userSignUp" type="entity">
		<entityType>System.USR</entityType>
		<mode>CREATE</mode>

		<viewConfig>
			<viewType>ENTITY</viewType>
			<param name="countries" value="US,CN" />
		</viewConfig>
	</object>

Parameter: countries

a list of ISO country codes to limit the countries for selection. Multiple countries are separated by comma or space.
If the parameter is not present, default to all countries.

← Embedded Objects: Criteria Elements→ Embedded Objects: EntitiesFrames / No Frames