11 Customizing MAF AMX Application Feature Artifacts

11.1 Introduction to Customizing MAF AMX Pages and Artifacts

You can use the standard customization mechanism provided by JDeveloper and Oracle Metadata Service (MDS) to customize your existing MAF AMX application feature artifacts and metadata files, including the following:

• MAF AMX files (.amx)

• Task flow files, such as ViewController-task-flow.xml

• Page definition files (<page name>.PageDef.xml)

• Data control XML file—a package file that contains a data control structure file (that is, a package file named for a data control and prepended with persdef.). For more information, see Section 7.8, "Configuring Data Controls."

The customization changes that you make at design time are applied to your files during deployment and become visible at runtime. MAF AMX supports the static seeded customization, where the final version for a specific customization context is seeded during deployment and work statically at runtime for that customization context. For each customization context you have to deploy a separate MAF application.

11.2 Customizing MAF AMX Pages and Artifacts

You customize your MAF AMX pages and artifacts as follows:

1. Define customization layers and layer values by modifying the jdev_install/jdeveloper/jdev/CustomizationLayerValues.xml file, as Example 11-1 shows.

   Example 11-1 Defining Customization Layers

   <cust-layers xmlns="http://xmlns.oracle.com/mds/dt">
      <cust-layer name="site" id-prefix="s">
         <!-- Generated id-prefix would be "s1" and "s2"
          for values "site1" and "site2" -->
         <cust-layer-value value="headquarter"
                           display-name="Headquarter" 
                           id-prefix="1" />
         <cust-layer-value value="remoteoffices"
                           display-name="Remote Office"
                           id-prefix="2" />
      </cust-layer>
   </cust-layers>
   

   For more information, see Section 11.4, "Configuring Customization Layers."

2. Create a customization class—a POJO class that extends oracle.mds.cust.CustomizationClass. For more information, see Section 11.3, "What You May Need to Know About Customization Classes."

   Note:

   The customization class can be created with a separate Java application.

3. Enable the JDeveloper design time to access the customization as follows:

   1. Package the customization class (a .java file) as a JAR file.

   2. Add the JAR file to one of the projects of the MAF application.

      For more information, see Section 11.5.1, "How to Make Customization Classes Available to JDeveloper at Design Time."

4. Register the customization class with the MAF application's adf-config.xml file by adding that class to the cust-config section, as Example 11-2 shows.

   Example 11-2 Registering the Customization Class

   <?xml version="1.0" encoding="windows-1252" ?>
   <adf-config xmlns="http://xmlns.oracle.com/adf/config">
      <adf-mds-config xmlns="http://xmlns.oracle.com/adf/mds/config">
         <mds-config xmlns="http://xmlns.oracle.com/mds/config" version="11.1.1.000">
            <cust-config>
               <match path="/">
                  <customization-class name="customclass.SiteCC"/>
               </match>
            </cust-config>
         </mds-config>
      </adf-mds-config>
   </adf-config>
   

   For information, see Section 11.6, "Configuring the adf-config.xml File."

5. Restart JDeveloper in the Customization Developer role. For more information, see the "Working with JDeveloper Roles" section in Oracle Fusion Middleware User's Guide for Oracle JDeveloper and Section 11.7, "What You May Need to Know About the Customization Developer Role."

   Note:

   The Customization Developer role enables you to change files, but not add them.

6. Perform the required modifications to the files. Your changes are recorded by MDS in the mdssys directory of the ViewController project:

   
   

7. Deploy the application to a mobile device, emulator, or as a platform-specific application package.

   Note:

   During deployment, the current customization context is picked up and the customized content that you declared in your MAF AMX pages in the deployed application is included in the new deployment artifacts. The customized content is grouped by the deployment profile name and may extend across multiple pages within the MAF AMX application feature.

   You can deploy a customized application in the Studio Developer role or in Customization Developer role. To deploy in the Customization Developer role:

   1. Launch the application the application in the Customization Developer role.

   2. In the Customization Context window, shown in Figure 11-1, select the layer and value for which you want to implement customizations.

      Figure 11-1 Selecting a Customization Context for Deployment

      
      

   3. Select from among the deployment options (accessed by choosing Application > Deploy, and then by selecting the deployment profile). For more information, see Chapter 19, "Deploying Mobile Applications."

   4. Perform a separate deployment for each customization context.

   During deployment, the base file and the delta files are merged to create the customized version of the application at runtime. The deployed application has no MDS dependencies.

   Tip:

   You can deploy the customized application as a MAF Application Archive (.maa) file and then import it into an application to perform additional customization and upgrades. The delta files included in the .maa file are merged with the base files after deployment. For more information, see Section 4.14.7, "Upgrading a Mobile Application with Customizations."

When the customization process is complete, JDeveloper creates a metadata file for the customizations and a subpackage for storing them. The metadata file contains the customizations for the customized object, which are applied over the base metadata at runtime. JDeveloper gives the new metadata file the same name as the base file for the object, but includes an additional .xml extension, as Figure 11-2, Figure 11-3, Figure 11-4, and Figure 11-5 show.

Figure 11-2 Customization File for MAF AMX Page

Description of "Figure 11-2 Customization File for MAF AMX Page"

Figure 11-3 Customization File for Task Flow

Description of "Figure 11-3 Customization File for Task Flow"

Figure 11-4 Customization File for Page Definition

Description of "Figure 11-4 Customization File for Page Definition"

Figure 11-5 Customization File for Data Control XML File

Description of "Figure 11-5 Customization File for Data Control XML File"

For additional information about customizing web service data controls, see Section 4.14.4, "What You May Need to Know About Web Service Data Controls and Customized Application Deployments."

For information about customizing MAF application-level artifacts, see Section 4.14, "Customizing MAF Files Using Oracle Metadata Services."

11.3 What You May Need to Know About Customization Classes

A customization class evaluates the current context and returns a String result. This String result is used to locate the customization layer.

The customization class provides the following information:

• A name that represents the name of the layer.

• An IDPrefix, for objects created in the layer. When new objects are created in a customization layer, they need a unique ID. The IDPrefix is added to the autogenerated identifier for the object to create an ID for the newly added object. Each layer needs a unique IDPrefix so that objects created at different customization layers have unique IDs.

• A cache hint (CacheHint), for the layer defined by the customization class. In MAF, the cache hint defines a static customization layer and the getCacheHint method always returns ALL_USERS which means the customization is applied globally (unconditionally) for a given deployment.

Customizations can be used to tailor MAF AMX application feature to suit a specific industry domain (verticalization). Each such domain denotes a customization layer and is depicted using a customization class.

11.4 Configuring Customization Layers

To customize an application, you must specify the customization layers and their values in the CustomizationLayerValues.xml file so that they are recognized by JDeveloper.

When you open a customizable application in the Customization Developer role, JDeveloper reads the adf-config.xml file to determine the customization classes to use and their order of precedence. JDeveloper also reads the CustomizationLayerValues.xml file to determine the layer values to make available in the Customization Context window. If there are layer values defined in the CustomizationLayerValues.xml file that are not defined in the customization classes listed in the adf-config.xml file, they are not displayed in the Customization Context window.

Therefore, you can have a comprehensive list of layer values for all of your customization projects in the CustomizationLayerValues.xml file, and only those appropriate for the current application are available in the Customization Context window. Conversely, you could have a comprehensive list of customization classes for a MAF AMX application feature in the adf-config.xml file, and only the subset of layer values on which you would work in your CustomizationLayerValues.xml file.

The names of the layers and layer values that you enter in the CustomizationLayerValues.xml file must be consistent with those specified in your customization classes. Example 11-3 shows the contents of a sample CustomizationLayerValues.xml file.

<cust-layers  xmlns="http://xmlns.oracle.com/mds/dt">
   <cust-layer name="industry" id-prefix="i">
      <cust-layer-value value="financial"
                        display-name="Financial"
                        id-prefix="f"/>
      <cust-layer-value value="healthcare"
                        display-name="Healthcare"
                        id-prefix="h"/>
   </cust-layer>
   <cust-layer name="site" id-prefix="s">
      <cust-layer-value value="headquarters"
                        display-name="HQ"
                        id-prefix="hq"/>
      <cust-layer-value value="remoteoffices"
                        display-name="Remote"
                        id-prefix="rm"/>
   </cust-layer>
</cust-layers>

For each layer and layer value, you can add an id-prefix token. This helps to ensure the uniqueness of the id, so that customizations are applied accurately. When you add a new element (such as a commandButton) to a MAF AMX page during customization, JDeveloper adds the id-prefix of the layer and layer value (determined by the selected tip layer) to the autogenerated identifier for the element to create an id for the newly added element in the customization metadata file. In the preceding example, the site layer has an id-prefix of " s " and the headquarters layer value has an id-prefix of " hq ". So, when you select site/headquarters as the tip layer and add a Button component to a page, the commandButton element will have an id of " shqcb1 " in the metadata customization file.

For each layer value, you can also add a display-name token to provide a human-readable name for the layer value. When you are working in the Customization Developer role, the value of the display-name token is shown in the Customization Context window for that layer value.

For each layer, you can optionally provide a value-set-size token that defines the size of the value set for the customization layer. This can be useful, for example, when using a design-time, application-specific CustomizationLayerValues.xml file. By setting value-set-size to no_values you can exclude runtime-only layers at design time.

<cust-layer name="runtime_only_layer" value-set-size="no_values"/>

You can define the customization layer values either globally for JDeveloper or in an application-specific file. If you use an application-specific file, it takes precedence over the global file. For more information on configuring layer values globally for JDeveloper, see Section 11.4.1, "How to Configure Layer Values Globally." For more information on configuring application-specific layer values, see Section 11.4.2.1, "Using the Studio Developer Role."

11.5 Consuming Customization Classes

After you have created your customization classes, you can use them at design time in the Customization Developer role, as well as at runtime in the application. To be consumed in an application or in JDeveloper, the classes must be packaged appropriately.

11.6 Configuring the adf-config.xml File

The application's adf-config.xml file must have an appropriate cust-config element in the mds-config section. The cust-config element allows clients to define an ordered and named list of customization classes. You use the Overview editor for the adf-config.xml file to add customization classes (see Figure 11-6).

Before you begin:

• Create your customization classes in an external project, as described in Section 11.2, "Customizing MAF AMX Pages and Artifacts."

• Create a JAR file that contains the customization classes.

• Make your classes available to JDeveloper, as described in Section 11.5.1, "How to Make Customization Classes Available to JDeveloper at Design Time."

• Launch JDeveloper using the Studio Developer role, and open the application that you want to customize.

To identify customization classes in the adf-config.xml file:

1. In the Application Resources window, expand the Descriptors > ADF META-INF nodes, and then double-click adf-config.xml.

2. In the Overview editor, select MDS navigation tab and then click the Add ( + ).

3. In the Edit Customization Class dialog, search for or navigate to the customization classes you have already created.

4. Select the appropriate classes and click OK.

5. After you have added all of the customization classes, you can use the arrow icons to arrange them in the appropriate order.

Figure 11-6 shows the Overview editor for the adf-config.xml file with two customization classes added.

Figure 11-6 adf-config.xml Overview Editor

The order of the customization-class elements defines the precedence of customization layers. For example, in the code shown in Example 11-4, the IndustryCC class is listed before the SiteCC class. This means that customizations at the industry layer are applied to the base application, and then customizations at the site layer are applied.

<adf-config xmlns="http://xmlns.oracle.com/adf/config"> 
   <adf-mds-config xmlns="http://xmlns.oracle.com/adf/mds/config"> 
      <mds-config xmlns="http://xmlns.oracle.com/mds/config" version="11.1.1.000">
         <cust-config> 
            <match path="/">
               <customization-class name="com.mycompany.IndustryCC"/>
               <customization-class name="com.mycompany.SiteCC"/>
            </match> 
         </cust-config>
      </mds-config>
   </adf-mds-config>
</adf-config>

11.7 What You May Need to Know About the Customization Developer Role

In JDeveloper, the Customization Developer role is used to customize the metadata in a project. Customization features are available only in this role. When working in a Customization Developer role, you can do the following:

• Create and update customizations.

• Select and edit the tip layer of a customized application.

• Remove existing customizations.

When you use JDeveloper in the Customization Developer role, the Source editor is read-only and the following JDeveloper features are disabled:

• Workspace migration.

• Creation, deletion, and modification of application and IDE connections. You must configure connections in Default role before opening an application in Customization Developer role.

When working with an application in the Customization Developer role, new objects cannot be created, and noncustomizable objects cannot be modified. In addition, you cannot edit noncustomizable files, such as Java classes, resource bundles, security policies, deployment descriptors, and configuration files.

You are also restricted from modifying project settings and customizing certain ADF Business Components features, including service interfaces and business event definitions. Additionally, you cannot refactor, or make changes to customizable files that would, in turn, necessitate changes in noncustomizable files.