Create a composite application

To create a composite application, you perform the following general steps:

1. Plan how you want to organize the application’s functionality into tiles and services.

2. Create an ADEP-Experience Services project in Flash Builder.

3. Use catalog (CXML) files to define composite application catalogs that allow you to organize your tiles and services.

4. Create tiles and services.

5. Use a composite application (AXML) file to define your application.

6. Use panels and views to create a tile layout. This layout is directly described in the application (AXML) file. It can also be saved as a template in a catalog (CXML) file and referenced from a composite application.

7. Deploy and run the composite application.

In many cases, an application requires multiple projects. These projects can be a combination of Flex application, Flex library, and non-Flex projects. Create the Flex application projects by enabling Composite Application Framework Services when you create an ADEP-Experience Services project in Flash Builder. To create the Flex library projects for use with composite applications, create a standard Flex library project. Then enable Composite Application Framework Services using the library project’s properties. Composite applications can also use projects that do not use Flex. For example, you can use generic Eclipse projects as a container for application (AXML) file or catalog (CXML) file content.

You can use Experience Services Plug-ins for Flash Builder to add templates for composite applications, catalogs, and tiles to projects. Modify these default components as needed to create your application.

Alternatively, you can use the composite application files found in the sample applications as a starting point for your own applications. Develop your own application elements to give the applications a custom appearance. For more information on the sample applications, see Sample composite applications.

For detailed application creation exercises, see Getting Started for Developers and Creating Your First ADEP Experience Services Application.

For more information on the XML structure of the elements that create applications, see Composite Application Framework XML Schema Reference.

For more information on Ant tasks that deploy composite applications to the server, see Composite Application Framework Task Reference.

For the steps to create a Flex project for ADEP-Experience Services, see Create an ADEP - Experience Services project.

The procedure for creating an Experience Services project instructs you to specify the Flex SDK. Composite application assets such as tiles can rely on various versions of the Flex SDK.

For more information on using composite application components that rely on different Flex SDKs, see Using multiple Flex SDKs in a composite application.

When Composite Application Framework Services is enabled for a project, Experience Services generates files that describe composite application functionality. It adds these GXML files to the project’s mosaic/generated folder.

Experience Services also automatically adds and updates references to tiles and other composite application components in the catalog (CXML) file that the project uses.

The catalog or GXML files that Experience Services generates and updates automatically are appropriate for most composite application projects. However, you can override or manually update these files if necessary.

You use a custom composite applications project to create Flex web or desktop (AIR client) applications that use composite application components. The custom project adds Experience Server resources to the project, and includes them in the application when you are ready to distribute it.

To create this type of project, in Flash Builder, click File > New > Flex Project for Custom Composite Applications.

A custom composite application project is similar to a standard Flex project for the Adobe Digital Enterprise Platform (ADEP) - Experience Services, with the following differences:

• The project-creation wizard automatically enables Composite Application Framework Services. Options for selecting a catalog and UX components are not available.

• The project’s mosaic/generated folder contains copies of the player-debug (for a web application) or air-debug (for a desktop application) folders from the ADEP SDK.

• Experience Services generates Client Component Framework configuration (GXML) files and adds them to the mosaic folder.

• The project’s build path libraries include additional Composite Application Framework, Client Component Framework, Experience Services Security Client libraries.

• The default MXML application file contains template code for the custom composite application user interface.

• The folder that contains the default MXML file also contains a default ActionScript class named CCAUtil.as. It contains the utility methods for event handling.

For information on creating a standard composite application project, see Create an ADEP - Experience Services project.

<s:WindowedApplication 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:fx="http://ns.adobe.com/mxml/2009"  
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:mosaic="com.adobe.mosaic.mxml.*"   
    creationComplete="handleCreationComplete(event)" 
    preinitialize="handlePreInitialize(event)" 
    height="600" 
    width="800">

You can assemble a composite application using SWF-based assets (such as tiles and services) that were compiled using different versions of the Flex SDK. This capability is helpful if you want to use a tile that relies on an earlier Flex SDK version in the same application as newer components.

To use an asset that relies on a specific Flex SDK version, add it to a Flex project with Composite Application Framework Services enabled. (Use the project wizard, project properties, or Flash Builder Preferences to select the appropriate Flex SDK.) Experience Services adjusts the project’s build path information as required.

When you update the source file for an asset with a new Flex SDK version, Experience Services updates the reference to the asset in the associated catalog (CXML) file. The reference’s flexSDKVersion property specifies the Flex SDK version.

Tiles are written in either Flex or HTML, and you can design tiles to interact with one another using the Composite Application Framework SDK. This SDK is available in both ActionScript and JavaScript.

A composite application service provides information and functionality to one or more components in a composite application. A service does not reside in each component that uses it. Instead, the service is a separate component that always implements a service interface. The service interface defines the methods that are implemented in the service and that other application components can reference. This modular design allows the components that provide and consume a service to be developed and function independently.

Panels are defined in XML and organize tiles into layouts for the composite application user interface. You can define panels in either a catalog (CXML) file or directly in an application (AXML) file. You can also load, create, and add panels to your application dynamically at runtime using the Composite Application Framework APIs.

For information on creating a panel in an application (AXML) file, see Create a composite application file (AXML file).

For example, you can define a panel that places all tiles in a grid:

<!-Add to PanelClassList in a Catalog --> 
<view:PanelClass name="SimplePanel"> 
 
    <ct:Metadata> 
        <ct:Description>Panel with Tiles in a Grid</ct:Description> 
    </ct:Metadata> 
    <view:Content> 
        <view:Panel label="Simple Panel" styleName="PanelInShellStyle"> 
            <view:Layout numColumns="2" name="SmartGridLayout"/> 
            <catalog:CatalogReference name="Concepts" uri="Concepts"/> 
            <tile:TileReference label="Stock Tile" name="StockTile" catalog="Concepts" /> 
            <tile:TileReference label="Company News" name="CompanyNews" 
                                catalog="Concepts" /> 
            <tile:TileReference label="Company Financials" name="CompanyFinancials" 
                                catalog="Concepts" width="100%" height="50%"/> 
        </view:Panel> 
    </view:Content> 
</view:PanelClass>

To create a more complex layout, you can define a panel with nested panels. For example, create a panel that contains two panels. The first panel is a reference to the example panel Simple Panel. It has an initial context that displays the tiles with company data specified by the value “ADBE”. The second panel uses the same tiles, but is defined inline instead of using a reference. For the second panel, the initial context displays the tiles with company data specified by “IBM.”

<view:PanelClass name="ComplexPanel"> 
 
    <ct:Metadata> 
        <ct:Description>Panel with nested panels</ct:Description> 
    </ct:Metadata> 
    <view:Content> 
        <view:Panel label="ComplexPanel" styleName="TabbedPanelStyle"> 
            <view:Layout numColumns="2" name="StackLayout "/> 
            <catalog:CatalogReference name="Concepts" uri="Concepts"/> 
            <view:PanelReference catalog="Concepts" name="SimplePanel"> 
                <ct:Context> 
                    <ct:Data key="company" type="string" value="ADBE" /> 
                </ct:Context> 
            </view:PanelReference> 
            <view:Panel label="Inline Panel" styleName="PanelInShellStyle"> 
                <ct:Context> 
                    <ct:Data key="company" type="string" value="IBM" /> 
                </ct:Context> 
                <view:Layout numColumns="2" name="SmartGridLayout"/> 
                <catalog:CatalogReference name="Concepts" uri="Concepts"/> 
                <tile:TileReference label="Stock Tile" name="StockTile" catalog="Concepts" /> 
                <tile:TileReference label="Company News" name="CompanyNews" catalog="Concepts" /> 
                <tile:TileReference label="Company Financials" name="CompanyFinancials" catalog="Concepts" width="100%" height="50%"/> 
            </view:Panel> 
    </view:Content> 
</view:PanelClass>

For information on how tiles can access the context variable, see Tile and service communication.

For information on using Composite Application Framework APIs to create or load a panel and add it to the application, see ActionScript 3.0 Language Reference.

Views are defined in XML and organize tiles into layouts for the composite application user interface. You can define views in either the catalog (CXML) file or directly in an application (AXML) file. You can also load, create, and add views to your application dynamically at runtime using the Composite Application APIs.

A view can only contain panels and is defined similarly to panels.

<!-Add to ViewClassList in the Catalog ' 
<view:ViewClass label="View 1" name="View1"> 
    <ct:Metadata> 
        <ct:Description>View 1</ct:Description> 
        <ct:OwnedBy>designer</ct:OwnedBy> 
        <ct:CreatedBy>designer</ct:CreatedBy> 
        <ct:CreatedDate>2001-12-17T09:30:47Z</ct:CreatedDate> 
        <ct:ModifiedBy>designer</ct:ModifiedBy> 
        <ct:ModifiedDate>2001-12-17T09:30:47Z</ct:ModifiedDate> 
        <ct:Category>String</ct:Category> 
        <ct:Tag>String</ct:Tag> 
    </ct:Metadata> 
    <view:Content> 
        <view:View name="View 1" width="100%" height="100%" label="View 1"> 
            <catalog:CatalogReference name="Concepts" uri="Concepts"/> 
            <view:PanelReference catalog="Concepts" name="ComplexPanel"/> 
        </view:View> 
    </view:Content> 
</view:ViewClass>

For information on using Composite Application Framework APIs to create or load a view and add it to the application, see ActionScript 3.0 Language Reference.

Layouts control the size, position, and orientation of the contents of composite application shells, views, view managers, and panels. By default, composite application components use the layout specified in their associated Spark skin.

var layout:ILayout = mosaicApp.createLayout("SmartColumnLayout"); 
layout.setAttribute("numColumns","4"); 
layout.setAttribute("paddingTop","10"); 
layout.setAttribute("paddingBottom","10"); 
var panel:IPanel = mosaicApp.createBlankPanel(layout);

<view:Panel> 
    <view:Layout name="com.mycorp.layouts.MyLayout" /> 
    ... 
</view:Panel>

To customize the appearance of composite applications, you can define style sheet references. Compile the style sheet as a SWF file and then add it to a catalog.

<!-Add to StyleSheetClassList ' 
<view:StylesheetClass  name="MosaicSlate"> 
    <ct:Metadata> 
        <ct:Description>A set of slate grey styles and skins for Composite Application Framework applications</ct:Description> 
    </ct:Metadata> 
 
    <view:Content 
        uri="${catalogURL}/stylesheets/MosaicSlate/MosaicSlate.swf" 
        contentType="application/x-shockwave-flash" 
    /> 
</view:StylesheetClass>

After you compile a style sheet as a SWF file, Experience Services adds the style sheet to the catalog. Apply the style sheets just as you do in a Flex application.

A skin is a component that covers the visual area of another component within an application. In a composite application, a skin sets border and background colors, transparency values, and provides a default layout. Skins can vary in terms of their complexity. Some are static visual user interface components, while others are more complex, containing controls that manipulate application component behaviors.

When you create a skin, you can link it to a component or set of components to have that skin display in an application at runtime. You create the link between skin and component using the HostComponent metadata element in the MXML definition of the skin.

For example:

<s:SparkSkin  ... 
    <fx:Metadata> 
        [HostComponent("com.adobe.mosaic.core.IMosaicContainer")] 
    </fx:Metadata> 
... 
</s:SparkSkin> 

For composite application components, you associate the skin with either the IMosaicContainer interface or the IMosaicComponent interface. Associating the skin with an interface allows the skin to work with several different components, as long as each component implements the same interface.

After you declare the HostComponent metadata, your custom skin can refer to properties and methods that are linked to the specified HostComponent. The reference is made using the hostComponent property that is provided for all Spark skins.

For example, the default skin for view:View elements is TabLayoutBarSkin. Its HostComponent is the ButtonBar Flex component. TabLayoutBarSkin uses data-binding between its dataProvider attribute and hostComponent.contentList to display a set of tabs that display the contents of the hostComponent.

For more information on the IMosaicContainer and IMosaicComponent interfaces, see ActionScript 3.0 Language Reference. The ActionScript reference also has information on the TabLayoutBarSkin that is used by default view:View elements in composite applications.

By default, a composite application does not allow users to reposition tiles by dragging them. However, you can create a layout that allows users to drag and drop tiles that have title bars. When an application uses this layout, users can move tiles by clicking and holding the tile title bar and then dragging it to the new location.

To implement this feature, add an instance of the class com.adobe.mosaic.layouts.dragAndDrop.DragAndDropGroup to a skin. This class enables the feature for any layout that you add to it.

For example, the following example illustrates how the drag and drop feature is enabled in the default skin for a panel:

<dragAndDrop:DragAndDropGroup id="contentGroup"> 
    <dragAndDrop:layout> 
        <layouts:SmartGridLayout maxNumColumns="2" 
                     paddingBottom="4" 
                     paddingLeft="4" 
                     paddingRight="4" 
                     paddingTop="4"/> 
    </dragAndDrop:layout> 
</dragAndDrop:DragAndDropGroup>

You can create your own layouts and use them with almost any composite application. Ensure that you are familiar with creating Spark layouts before you try to use custom layouts.

Composite applications can use layout classes that extend spark.layouts.BaseLayout. You can also use the com.adobe.mosaic.layouts.MosaicLayoutBase class for additional functionality such as minimize and maximize capabilities.

After you create your layout, associate it with a skin. This skin can be a skin class that you already intend to use. Or, if you want to include the layout only, a simple skin class that has a contentGroup element.

<s:Group id="contentGroup"> 
    <s:layout> 
        <my:MyLayout xmlns:my="my.layouts.*" /> 
    </s:layout> 
</s:Group>

Create a style sheet that associates the skin with a style. The skin class, and therefore the layout class, is compiled into the style sheet SWF file.

Add the style sheet to a catalog and deploy the catalog to your Experience Server. Then you can use your layout as do any other layout.

The composite application file is the central element of a composite application. It identifies all of the Composite Application Framework elements to assemble to create the application.

1. Right-click your project and then click New > Composite Application.

2. Enter a name for the application. Optionally, enter a label and description. Then click Finish.

   Experience Services creates a file that specifies the basic layout and contents of a composite application. Its filename extension is .axml.

3. In Source view, locate the catalog:CatalogReference element that is nested in the app:Shell element.

    <catalog:CatalogReference name="${catalog}" uri="${catalog}"/>

   To make it easier to create and reuse applications, the value ${catalog} is a placeholder. When you deploy a composite application, the name of the catalog replaces ${catalog}.

   For AXML files in an ADEP-Experience Services Flex project, the project properties (under Adobe > Composite Application Framework) specify the catalog. Otherwise, Flash Builder preferences (under Adobe > Composite Application Framework) specify the catalog. If the token expansion pattern does not align with your development pattern, you can replace the ${catalog} token. You can replace it with a hard-coded value.

   CatalogReference entries are scoped and you can add additional CatalogReferences. When you add additional CatalogReferences elements, specify a catalog name and the actual catalog URI. The ${catalog} placeholder is used only for a single catalog reference.

4. To create the simplest possible composite application, add a tile reference after the catalog:CatalogReference element. You can remove the view:ViewManager element or leave it commented out.

   For example:

   <app:Shell label="Sample Shell" name="SampleShell"> 
       <catalog:CatalogReference name="${catalog}" uri="${catalog}"/> 
       <tile:TileReference label="Stock Tile" name="StockTile" catalog=="${catalog}"  /> 
   </app:Shell>

5. Save the application file.

Experience Services allows you to add composite application components to Flex web or desktop applications using a custom composite application project. For example, you can create composite applications that are delivered using an AIR client instead of a browser. Composite application functionality adds the advantages of modular development and delivery capabilities to your Flex client applications.

There are two ways to add composite application components to a Flex web or desktop (AIR-based) application:

• Add references to composite application components such as tiles and services. Users can access content and functionality provided in tiles in addition to the functionality that the Flex web or desktop client provides. For example, AIR technology allows client applications to interact with and store data in the user's local environment.

• Add a reference to a composite application (AXML) file. Users can access all the content and functionality of the standard composite application via a Flex web or AIR-based client.

When you create a Flex project for a custom composite application, Experience Services generates a default MXML application file. It contains the basic MXML components for a custom application, including the namespace for Composite Application Framework MXML components.

To reference a composite application, you specify a server session, an application, and an application shell in the default MXML file. If your application references tiles and services, you specify catalogs, tiles, and services in addition to the server session and shell.

To provide composite application functionality, web and desktop applications interact with Experience Server. For information on libraries that handle user authentication for ADEP Flex applications that interact with Experience Server, see Add user authentication to an ADEP Flex client application.

Views must be children of a ViewManager element and a composite application can have only one view manager. To add views to an application, either uncomment the view manager template that Experience Services generates or create your own. Then add references to views in the catalog or define views inline. You can add the ViewManager element in any shell or panel.

For example:

<view:ViewManager height="100%" width="100%"> 
    <view:View height="100%" width="100%" label="Inline View"> 
        <view:Panel height="100%" label="Inline Panel" styleName="PanelInShellStyle" tileChrome="full" width="100%"> 
            <view:Layout name="HorizontalLayout"/>  
            <tile:TileReference catalog="${catalog}" 
                name="SampleTile" label="Sample Tile" optional="true" 
                width="100%" height="100%" /> 
        </view:Panel> 
    </view:View> 
    <catalog:CatalogReference name="Concepts" uri="Concepts"/ > 
    <view:ViewReference catalog="Concepts" name="View1"/> 
 
</view:ViewManager> 

You can define a view:ViewClass element in the catalog only. When you define a view in the application file, only the view:View element from within the view:ViewClass is allowed. For an example, see Create a view.

The composite application initializes and displays the views that you add to the AXML file. You can create additional views by saving an existing view with its associated context. You can load saved views via the API or use a special link. The application does not initialize or display saved views automatically. For more information on saved views, including the special saved view link, see Customize an application using a saved view.

Panels can be children of a shell, view, or another panel. In the example for Add a view to an application, the first view includes a panel that was added inline. Like the view:ViewClass element, you can define a view:PanelClass element in a catalog only. When you add panels to the application file, define them inline or create a PanelReference element. For example:

<app:Shell label="Sample Shell" name="SampleShell"> 
    <view:Panel label="ComplexPanel" styleName="TabbedPanelStyle"> 
        <view:Layout numColumns="2" name="StackLayout"/> 
        <catalog:CatalogReference name="Concepts" uri="Concepts"/> 
        <view:PanelReference catalog="Concepts" name="SimplePanel"> 
            <ct:Context> 
                <ct:Data key="company" type="string" value="ADBE" /> 
            </ct:Context> 
        </view:PanelReference> 
        <view:Panel label="Inline Panel" styleName="PanelInShellStyle"> 
            <ct:Context> 
                <ct:Data key="company" type="string" value="IBM" /> 
            </ct:Context> 
            <view:Layout numColumns="2" name="SmartGridLayout"/> 
            <catalog:CatalogReference name="Concepts" uri="Concepts"/> 
            <tile:TileReference label="Stock Tile" name="StockTile" catalog="Concepts" /> 
            <tile:TileReference label="Company News" name="CompanyNews" catalog="Concepts" /> 
            <tile:TileReference label="Company Financials" name="CompanyFinancials" catalog="Concepts" width="100%" height="50%"/> 
        </view:Panel> 
    </view:Panel> 
</app:Shell>

In this example, context is defined in both the catalog (CXML) file and application (AXML) file. For each key/value pair, the context that is defined in the application overrides the one in the catalog.

Tiles can be children of a shell or panel. You define tiles in a catalog and reference them in an application file using a TileReference element. You cannot define tiles in an application file. Ensure that you include a CatalogReference element that specifies the tile’s catalog in the application file.

<catalog:CatalogReference name="Concepts" uri="Concepts"/> 
<tile:TileReference label="Stock Tile" name="StockTile" catalog="Concepts" width="300" height="400" > 
    <ct:Context> 
        <ct:Data key="tileCompany" type="string" value="ADBE" /> 
    </ct:Context> 
</tile:TileReference> 
<tile:TileReference label="Company News" name="CompanyNews" catalog="Concepts" width="300" height="400" />

In this example, the tile references specify attributes and context, which override any settings for the tile specified in the catalog.

To configure an application to load a service when the application is run, add a reference to a service in the application file. A catalog stores the service definition.

For information on creating a service and adding it to a catalog, see Create a service.

To add a service to the application file, add a tile:ServiceReference element. Include library and name properties with values that specify the service implementation library.

<catalog:CatalogReference name="${catalog}" uri="${catalog}"/> 
<tile:ServiceReference catalog="PropertiesCatalog" library="PropertiesService" name="PropertiesService" />

After you add the ServiceReference element to the application AXML, add the [Consume] metadata tag to the tile or service that uses the service.

For information on using a service in a tile, see Tile and service communication.

Experience Services allows you to add composite application components to an HTML page. For example, you can create HTML-based applications that include composite application tiles. Composite application functionality adds the advantages of modular development and delivery capabilities to your HTML client applications.

The JavaScript APIs that add composite application functionality to HTML pages are included in the Composite Application Framework SDK. For example, you can use the APIs to load a catalog, load one or more tiles, and load any services that the tiles use.

You can reference the JavaScript APIs from any HTML page that can access the Composite Application SDK. However, when create your HTML page in Flash Builder with Experience Services Plug-ins, you can use Flash Builder to debug any tiles you add to the page.

For information about the JavaScript APIs, see Composite Application Framework for HTML JavaScript API Reference.

The Composite Application Framework samples include an HTML client application that uses tiles and a service. For more information on samples, see Sample composite applications.

Composite applications use skins to define styles. You can use the styles that Composite Application provides or write custom skins.

When Experience Services generates composite application (AXML), composite application catalog (CXML), and Client Component Framework (GXML) files, it includes special tokens. These tokens are placeholders that Experience Services replaces with current values before it deploys assets to the server.

${project}

Experience Services replaces this token with the name of the Flash Builder project name. For example, SalesDesktop.

${catalog}

Experience Services replaces this token with the URI of the catalog associated with the project. Use the Flash Builder project properties to either specify a catalog for the project or configure the project to use the default workspace catalog.

<property name="myToken" value="myValue"/> 
<include location="child.gxml"/>

<constructorArg index="0" value="${myToken}" />

The JavaScript APIs that add composite application functionality to HTML pages are included in the Composite Application Framework SDK. For example, you can use the APIs to load a catalog, load one or more tiles, and load any services that the tiles use.