15 Setting Constraints on Application Features

15.1.1 Using Constraints to Show or Hide an Application Feature

The Constraints tab, shown in Figure 15-1, enables you to set the application feature-level constraints. For example, an application feature that uses the device's camera displays within the mobile application's navigation bar or springboard only if the MAF runtime determines that the device actually has a camera function. You can also use feature level constraints to secure an application based on user roles and privileges. Figure 15-1 illustrates creating constraints that would allow only a user with administrator privileges to access the application feature, should the
MAF runtime evaluate the constraint to true. If the runtime evaluates the constraint to false, then it prevents an end user from accessing the application feature, because it does not appear on the navigation bar or within the springboard.

Figure 15-1 Setting Application Feature-Level Constraints

15.1.2 Using Constraints to Deliver Specific Content Types

To accommodate such factors as device hardware properties or user privileges, a single application feature can have more than one type of content to deliver different versions of the user interface. By setting constraints on the content of an application feature, you designate the conditions for determining what end users can see or how application pages can be used.

Using the Content tab, shown in Figure 15-2, you can, for example, specify content that delivers one type of user interface for users who have been granted administrative privileges and a separate user interface for those who have basic user privileges. In addition, content-level constraints can accommodate the layout considerations of a device. Figure 15-2 illustrates how a sample application performs this using a constraint based on the screen width of a device to deliver AMX Mobile task flows that call pages tailored to the layout of the iPhone and the iPad. When an end user launches the sample application, the MAF runtime evaluates the constraint that is set for the Employees application feature. If the runtime ascertains that the diagonal width of the device's screen exceeds six inches, it selects the Employees_pad_taskflow.xml file, which calls the MAF AMX pages designed for the iPad. If this constraint evaluates to false (that is, the diagonal width of the screen is less than six inches), then the runtime selects the MAF taskflow that calls iPhone-specific pages, Employees_phone_taskflow.xml. In addition, the Content tab enables you to select navigation bar and springboard images that display when the runtime selects specific content. If you do not select content-specific images, then MAF instead uses the application feature-level images that are designated in the General tab.

Figure 15-2 Setting Content-Level Constraints

For more information on the sample applications, see Appendix F, "Mobile Application Framework Sample Applications."

15.2.1 How to Define the Constraints for an Application Feature

You declaratively configure the constraints for a selected application feature using the Constraints tab in the Features page, shown in Figure 15-2.

Defining the constraints for an application feature:

1. Click the Constraints tab.

2. Click Add.

3. Select a property and an appropriate operator and then enter a value. For more information on using properties, see Section 15.2.3, "About the property Attribute."

15.2.2 What Happens When You Define a Constraint

Entering the values in the Constraints tab updates the descriptor file's <adfmf:constraints> element with defined <adfmf:constraint> elements, similar to Example 15-1.

15.2.3 About the property Attribute

MAF provides a set of property attributes that reflect users, devices, and hardware properties. Using these properties in conjunction with the following operators and an appropriate value determines how an application feature can be used.

• contains

• equal

• less

• more

• not

15.2.4 About User Constraints and Access Control

After a user logs into a mobile application, the MAF runtime reconciles the user role-based constraints configured for each application feature against the user roles and privileges retrieved by the Access Control Service (ACS). MAF then presents only the application feature (or application feature content) to end users whose privileges satisfy the constraints. In addition to setting these user privilege and role constraints, you create access control for the mobile application by entering the following in the Create MAF Login Connection dialog, shown in Figure 15-3 (and described in Section 21.5.2, "How to Designate the Login Page"):

• The URL of the REST Web service that transmits a list of user roles and privileges.

• A list the user roles checked by the application feature.

• A list of privileges.

See also Section 21.4.17, "What You May Need to Know About the Access Control Service."

Figure 15-3 Configuring Retrieval of User Roles and Privileges

You control access to application features using constraints based on user.roles and user.privileges. For example, to allow only a user with the manager role to access an application feature, you must add a constraint of user.roles contains manager to the definition of the application feature.

The user.roles and user.privileges use the contains and not operators as follows:

• contains—If the collection of roles or privileges contains the named role or privilege, then the runtime evaluates the constraint to true. Example 15-2 shows an example of using the user.roles property with the contains operator. The application feature will appear in the mobile application if the user's roles include the role of employee.

  Example 15-2 Using the contains Operator for a User Role Collection

  <feature ...>
     ...
     <constraints>
        <constraint property="user.roles"  
                    operator="contains"
                    value="employee" />
     </constraints>
     ...
  </feature>
  

• not—If the collection of roles or privileges does not contain the named role or privilege, then the runtime evaluates the constraint to true. In Example 15-3, the application feature is not included if the user's privileges contain the manager privilege.

  Example 15-3 Using the not Operator with the user.privileges Property to Restrict Access to an Application Feature

  <feature ...>
     ...
     <constraints>
        <constraint property="user.privileges"  
                    operator="not"
                    value="manager" />
     </constraints>
     ...
  </feature>
  

15.2.5 About Hardware-Related Constraints

The hardware object references the hardware available on the device, such as the presence of a camera, the ability to provide compass heading information, or to store files. These properties use the equal operator.

• hardware.networkStatus—Indicates the state of the network at the startup of the application. This property can be modified with three attribute values: NotReachable, CarrierDataConnection, and WiFiConnection. Example 15-4 illustrates the latter value. As illustrated in this example, setting this value means that this mobile application feature only displays in the mobile application if the device hardware indicates that there is a Wi-Fi connection. In other words, if the device does not have a Wi-Fi connection when the mobile application loads, then this application feature will not display.

  Example 15-4 Defining the hardware.networkStatus Property

  <feature ...>
  ...
     <constraints>
        <constraint property="hardware.networkStatus" 
                    operator="equal" 
                    value="WiFiConnection" />
     </constraints>
  ...
  </feature>
  

  Note:

  This constraint is evaluated at startup on iOS-powered devices. If a device does not have a Wi-Fi connection at startup but subsequently attains one (for example, when a user enters a Wi-Fi hotspot), then the application feature remains unaffected and does not become available until the user stops and then restarts the mobile application.

• hardware.hasAccelerometer—Indicates whether or not the device has an accelerometer. This property is defined by a true or false value. Example 15-5 shows a true value, indicating that this application feature is only available if the hardware has an accelerometer.

  Example 15-5 Using the hardware.hasAccelerometer Property

  <feature ...>
  ...
     <constraints>
        <constraint property="hardware.hasAccelerometer"  
                    operator="equal"
                    value="true" />
  </constraints>
  ...
  </feature>
  

  Note:

  Because all iOS-based hardware have accelerometers, this property must always have a value of true for the application feature to be available on iOS-powered devices.

• hardware.hasCamera—Indicates whether or not the device has a camera. This constraint is defined using a value attribute of true or false. In Example 15-6, the value is set to true, indicating that the application feature is only available if the device includes a camera.

  Example 15-6 Using the hardware.hasCamera Property

  <feature ...>
  ...
     <constraints>
        <constraint property="hardware.hasCamera"  
                    operator="equal"
                    value="true" />
  </constraints>
  ...
  </feature>
  

  Note:

  Not all iOS-based hardware have cameras. This value is dynamically evaluated at the startup of mobile applications on an iOS-powered device. At this time, the mobile application removes the application features that do not evaluate to true.

• hardware.hasCompass—Indicates whether the device has a compass. You define this constraint with the attribute value of true or false, as shown in Example 15-7.

  Example 15-7 Using the hardware.hasCompass Property

  <feature ...>
     ...
     <constraints>
        <constraint property="hardware.hasCompass"  
                    operator="equal"
                    value="true" />
     </constraints>
     ...
  </feature>
  

  Note:

  Not every iOS-powered device has a compass. This value is dynamically evaluated at the startup of mobile applications on an iOS-powered device. At this time, the mobile application removes the application features that do not evaluate to true.

• hardware.hasContacts—Indicates whether the device has an address book or contacts. You define this constraint with the attribute value of true or false, as shown in Example 15-8.

  Example 15-8 Using the hardware.hasContacts Property

  <feature ...>
     ...
     <constraints>
        <constraint property="hardware.hasContacts"  
                    operator="equal"
                    value"=true" />
        </constraints>
     ...
  </feature>
  

  Note:

  Because contacts on iOS-based hardware are accessed through Apache Cordova, the value attribute is always set to true for iOS-powered devices.

• hardware.hasFileAccess—Indicates whether the device provides file access. You define this constraint with the attribute value of true or false, as shown in Example 15-9. The application feature is only available if the runtime evaluates this constraint to true.

  Example 15-9 Using the hardware.hasFileAccess Property

  <feature ...>
     ...
     <constraints>
        <constraint property="hardware.hasFileAccess"
                    operator="equal"
                    value="true" />
     </constraints>
     ...
  </feature>
  

  Note:

  Because file access on iOS-based hardware is accessed through Apache Cordova, the value attribute is always true for iOS-powered devices.

• hardware.hasGeoLocation—Indicates whether or not the device provides geolocation services. You define this constraint with the attribute value of true or false, as shown in Example 15-10. The application feature is only available if the device supports geolocation.

  Example 15-10 Using the hardware.hasGeoLocation Property

  <feature ...>
     ...
     <constraints>
        <constraint property="hardware.hasGeoLocation"  
                    operator="equal"
                    value="true"/>
     </constraints>
     ...
  </feature>
  

  Note:

  Apache Cordova does not provide access to the gelocation service for all iOS-powered devices. Depending on the device, the application feature may not be available when the constraint is evaluated by the runtime.

• hardware.hasLocalStorage—Indicates whether the device provides local storage of files. You define this constraint with the value attribute of true or false, as shown in Example 15-11. The application feature only displays if the device supports storing files locally.

  Example 15-11 Using the hasLocalStorage Property

  <feature ...>
     ...
     <constraints>
        <constraint property="hardware.hasLocalStorage"  
                    operator="equal"
                    value="true" />
     </constraints>
     ...
  </feature>
  

  Note:

  Because Apache Cordova provides access to local file storage on all iOS hardware, the value attribute is always true for iOS-powered devices.

• hardware.hasMediaPlayer—Indicates whether or not the device has a media player. You define this constraint with the value attribute of true or false, as shown in Example 15-12. The application feature only displays if the device has a media player.

  Example 15-12 Using the hardware.hasMediaPlayer Property

  <feature ...>
     ...
     <constraints>
        <constraint property="hardware.hasMediaPlayer"  
                    operator="equal"
                    value="true" />
     </constraints>
     ...
  </feature>
  

  Note:

  For iOS-powered devices, the value attribute is always true, because Apache Cordova provides access to media players on iOS-based hardware.

• hardware.hasMediaRecorder—Indicates whether or not the device has a media recorder. You define this constraint with the value of true or false, as shown in Example 15-13. The application feature is only included if the device hardware supports a media recorder.

  Example 15-13 Using the hardware.hasMediaRecorder Property

  <feature ...>
     ...
     <constraints>
        <constraint property="hardware.hasMediaRecorder"  
                    operator="equal"
                    value="true" />
     </constraints>
     ...
  </feature>
  

  Note:

  Set this value to true for all iOS-powered devices because all iOS-based hardware have media recorders which can be accessed through Apache Cordova. Some devices, such as the Apple iTouch, do not have a microphone but can allow end users to make recordings by attaching an external microphone.

• hardware.hasTouchScreen—Indicates whether or not the hardware provides a touch screen. You define this constraint with the value attribute of true or false, as shown in Example 15-14. The application feature is only included if the device hardware supports a touch screen.

  Example 15-14 Using the hardware.hasTouchScreen Property

  <feature ...>
     ...
     <constraints>
        <constraint property="hardware.hasTouchScreen" 
                    operator="equal"
                    value="true" />
     </constraints>
     ...
  </feature>
  

  Note:

  Set the value attribute to true for iOS-powered devices, because all iOS-based hardware provides touch screens.

• hardware.screen.width—Indicates the width of the screen for the device in its current orientation. Enter a numerical value that reflects the screen's width in terms of logical device pixels (such as such as 320 in Example 15-15), not physical device pixels, which represent the actual pixels that appear on a device. The value depends on the orientation of the device.

  Example 15-15 Using the hardware.screen.width Property

  <feature ...>
     ...
     <constraints>
        <constraint property="hardware.screen.width" 
                    operator="equal"
                    value="320" />
     </constraints>
     ...
  </feature>
  

  Note:

  This value is evaluated at the startup of the mobile application when the runtime evaluates constraints and dismisses application features with constraints that do not evaluate to true. If a user rotates the device after the mobile application starts, MAF's runtime does not re-evaluate this constraint because the set of application features is fixed after the mobile application starts.

• hardware.screen.height—Indicates the height of screen for the device in its current position. Enter a numerical value that reflects the screen's height in terms of logical pixels, such as 320 or 480, as shown in Example 15-16. The value depends on the orientation of the device.

  Example 15-16 Using the hardware screen.height Property

  <feature ...>
     ...
     <constraints>
        <constraint property="hardware.screen.height"
                    operator="equal"
                    value="480" />
     </constraints>
     ...
  </feature>
  

  Note:

  When the mobile application starts, the MAF runtime evaluates the screen height value for this constraint as part of the process of dismissing application features with constraints that do not evaluate to true. If a user changes the orientation of the device after the mobile application starts, the runtime does not re-evaluate this constraint, because the set of application features is fixed after the mobile application starts.

• hardware.screen.availableWidth—Indicates the available width of the device's screen in its current orientation. Enter a numerical value that reflects the screen's width in terms of logical pixels, such as 320 or 480, as shown in Example 15-17. The value depends on the orientation of the device.

  Example 15-17 Using the hardware.screen.availableWidth Property

  <feature ...>
     ...
     <constraints>
        <constraint property="hardware.screen.availableWidth"  
                    operator="equal"
                    value"320" />
     </constraints>
     ...
  </feature>
  

• hardware.screen.availableHeight—Indicates the available height of the screen for the device in its current position. Enter a numerical value that reflects the screen's width in terms of logical pixels, such as 320 or 480, as shown in Example 15-18. The value depends on the orientation of the device.

  Example 15-18 Using the hardware.screen.availableHeight Property

  <feature ...>
     ...
     <constraints>
        <constraint property="hardware.screen.availableHeight"  
                    operator="equal"
                    value"480" />
     </constraints>
     ...
  </feature>
  

15.2.6 Creating Dynamic Constraints on Application Features and Content

In addition to displaying or hiding an application feature or user interface content based on the static constraints that are defined by the name, operator, and value attributes, you can enable a mobile application to render its application features and content dynamically by defining constraints with EL expressions. The dynamic evaluation of constraints based on EL expressions enables you to write expressions that can call your own bean logic, write complex EL expressions, or even write logic-accessing application preferences. Defining constraints as EL expressions provides flexibility in that the MAF runtime may initially hide an application feature if it evaluates an EL expression as false, but may display it at a later point when it evaluates the same EL expression as true. The <adfmf:constraintExpression> element enables you to define constraints on an application feature using EL expressions, as illustrated by the deferred method expression in Example 15-19.

<adfmf:constraints>
   <adfmf:constraint id="c1" property="hardware.screen.dpi" operator="more" value="120"/>
   <adfmf:constraint id="c2" property="device.model" operator="equal" value="iPad"/>
   <adfmf:constraintExpression id="c3" value="#{myBean.checkConstraint}"/>
</adfmf:constraints>

As also illustrated by Example 15-19, you can nest this element among the static constraints defined within the <adfmf:constraints> element of the maf-feature.xml file. For more information, see Oracle Fusion Middleware Tag Reference for Oracle Mobile Application Framework.