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 properties as query criteria. For example, embed the employee with id 100 from ExampleHR module.

<object xmlns="http://www.cmobilecom.com/af/objects" type="entity">
	<entityType>ExampleHR.EMP</entityType>
  
	<mode>VIEW</mode>
	
	<criteriaElements>
		<function name="EQ" property="nid">100</function>
	</criteriaElements>
	
	<viewConfig>
		<viewType>ENTITY</viewType>
	</viewConfig>
</object>

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>ExampleHR.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 paid order total amount grouping by customer and ordering by customer(ascending) and total amount (descending).

<object xmlns="http://www.cmobilecom.com/af/objects"
        id="queryOrders" type="entity">
	<entityType>Ecommerce.SO</entityType>
	
	<criteriaElements>
		<function name="IS_NOT_NULL" property="payment"></function>
	</criteriaElements>
	
	<searchOptions>
		<groupBy>customer</groupBy>
		<orderBy ascending="true">customer</orderBy>
		<orderBy ascending="false">total</orderBy>
	</searchOptions>
	
	<viewConfig>
		<viewType>QUERY</viewType>
		<showSearchOptions>false</showSearchOptions>
		
		<viewConfig name="queryResults">
			<viewType>ENTITY_LIST_WIDE</viewType>
		</viewConfig>
  	</viewConfig>
</object>

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>ExampleHR.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) 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.page for submitting an ExpenseClaim, if the Employee entity is not found for current user, redirect to page /createEmployee.page to create the Employee entity. Redirect back to /createExpenseClaim.page after the Employee is created.

Page: /createExpenseClaim.page


<object xmlns="http://www.cmobilecom.com/af/objects" 
	id="checkEmployee" type="entity">
	<entityType>ExampleHR.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.page">
			<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>ExampleHR.EC</entityType>
	<mode>CREATE</mode>
		
	<viewConfig>
		<viewType>ENTITY</viewType>	
	</viewConfig>
</object>

Page: /createEmployee.page

<object xmlns="http://www.cmobilecom.com/af/objects" 
	id="createEmployee" type="entity">
	<entityType>ExampleHR.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