Create a composite application

Overview of creating a composite application using Experience Services in Flash Builder

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.

Create an ADEP-Experience Services project

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.

ADEP - Experience Services project composite application configuration files

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.

Automatically generated GXML files

When Composite Application Framework Services is enabled for a project, Experience Services generates a GXML file for each of the following elements in the project:

  • In a library project, any source file that contains the [Tile] metadata tag.

  • In a library project, any source file that contains a service implementation class that uses the [Expose] metadata tag.

  • For an application project, any source file that contains both a [Tile] and [Consume] metadata tag. (Any source file that contains a [Consume] metadata tag is required to have a [Tile] metadata tag as well.)

When you change any of these source files, Experience Services updates the corresponding GXML file.

GXML files and catalog deployment

When you deploy a catalog to Experience Server, Experience Services identifies all files that the catalog references. Then it places these files and the catalog (CXML) file in a ZIP file. The process is the same whether you use a command to deploy the catalog or run or debug an application, which automatically deploys the associated catalog.

Experience Services uses the following methods to determine which files to include in the ZIP file:

  • Checks for references to interfaces, services, style sheets, and tiles and adds their SWF files to the ZIP file. Experience Services checks for the SWF file in all projects that use the catalog.

  • For references to any service, and for some references to tiles, checks the GXML file specified for the component to determine the name of the SWF file to include.

  • Experience Services checks for the SWF file in the output folder of projects. In some cases, it also checks subfolders of the output folder (for example, when the project uses modules).

  • Adds any other files in the output folder that are not SWC, SWF, ZIP, AXML or CXML files. Experience Services places these files with the corresponding SWF file in the catalog.

Updates to catalog (CXML) files

Experience Services automatically adds or updates references to tiles, interfaces, and services in a catalog (CXML) file.

Experience Services adds a reference to a catalog when a source file contains the [Tile], [Expose], or [Consume] metadata tag. It updates the CXML file whenever a parameter that uses one of these tags changes or the project is rebuilt.

Experience Services never removes entires from a CXML file. When you delete a tile from a project, delete the reference to the tile in the CXML file. If you don’t delete the reference, warning messages are displayed when you deploy an application.

When you change a reference in a CXML file manually and the source for the reference changes, any automatic updates overwrite your change. However, if you change the URI of the reference to point to a GXML file, Experience Services does not overwrite the change. Experience Services checks whether the value of the URI is the same as the one that it would have generated automatically. If it is not the same, it does not update the reference. Any changes that are required need to be done manually.

Overriding GXML files

To override files in the mosaic/generated folder, you add identically named files in the mosaic folder.

Experience Services creates and updates files in the mosaic/generated folder of an ADEP-Experience Services project. However, it never changes files located in the mosaic folder itself.

When there are identically named files in the mosaic folder, Experience Services automatically references those files instead of the ones in the mosaic/generated folder. Do not edit the files in the mosaic/generated folder.

In most cases, you do not need to override the GXML files that Experience Services generates and updates automatically. However, custom files are necessary in the following cases:

  • Your service constructor has complex objects or arrays as arguments to its constructor. To avoid problems, create a copy of the GXML file in the project’s mosaic/generated folder and add it to the mosaic folder. Then edit the GXML file to provide the appropriate arguments.

  • You require a GXML file for a type of tile that Experience Services does not generate a GXML file for. For an example, see Add composite application components to an HTML page. Create a GXML manually and add it to the project’s mosaic directory. Edit the reference to the tile in the appropriate catalog (CXML) file to specify the GXML file that you created.

Create a Custom Composite Applications project

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.

Client Component Framework configuration files

The Client Component Framework configuration file for a custom composite application project is gravity-flex-di-swf11-debug.gxml.

For AIR clients, Experience Services configures your project’s application descriptor file ([application name]-app.xml) to specify MosaicCustomBootstrap.swf (the Composite Application Framework configuration file) as the main SWF file for the application. In turn, the Composite Application Framework configuration file loads the Client Component Framework configuration file.

For web applications, Experience Services configures the HTML template file (index.template.html).

Experience Services configures the Client Component Framework configuration file to load both the Client Component Framework trace logger (gravity_trace_logger-debug.swf) and the project’s SWF file ([application name].swf).

Composite Framework Application library and namespace

You add Composite Application Framework applications, tiles, and other components to Flex and AIR client application using MXML components.

The mosaic-mxml.swc file, which is part of the Composite Application Framework SDK, provides the Composite Framework Application MXML components. Experience Services adds mosaic-mxml.swc to the Flex build path of a custom composite application project by default. To allow you to use the MXML components in the application, the composite application MXML namespace is included in the project’s application file.

For example:

<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">

Default MXML application file

The default MXML application file for a custom composite application project contains MXML components that create the following elements:

  • A server session

  • User authentication

  • An identifier for the composite application components or composite application used in the Flex application

  • A reference to a composite application on Experience Server

  • References to a tile and service on Experience Server

Edit the components as required to create your application.

For information on adding composite application MXML components to the default file, see Add composite applications or tiles to Flex or AIR applications.

Using multiple Flex SDKs in a composite application

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.

Flex SDKs supported by Composite Application Framework

You can add a component to a composite application if the Experience Server supports its associated Flex SDK version. Experience Server supports the Flex SDKs that the Composite Application Framework SDK provides. The Composite Application Framework SDK is part of the Experience Services SDK that you install.

To view the versions of the Flex SDK that Experience Server supports:

  1. Log in to Experience Server as an administrator. The default URL for the server is http://localhost:4502/.

  2. Click CRXDE Lite.

  3. Navigate to the /content/mosaic/viewer/flex_sdks/ folder. Each version of the Flex SDK that the Experience Server supports has its own folder.

You can use Package Manager to install other versions of the Flex SDK. The format for the package names is mosaic-flex[version number]-pkg.zip-[build number]. For example, mosaic-flex4.6.0-pkg-2.238.zip.

Flex SDK versions for composite application style sheets

Experience Server compiles the user interface for the Composite Application Framework client runtime using the most recent version of the Flex SDK in the installed mosaic package (mosaic-pkg-[build number].zip). The built-in style sheet that is applied to the client runtime user interface is also compiled using this version of Flex SDK. If you apply a different style sheet to the runtime user interface, ensure that you compile it using the same Flex SDK version that Experience Server uses to compile the runtime.

For tiles with a user interface, ensure that same Flex SDK compiler is used for the tile and any style sheet that you apply to it.

Create a composite application catalog

About composite application catalogs

Structure and content

A composite application catalog is a descriptor (CXML) file plus content.

The descriptor lists the catalog components in the current archive and includes settings and metadata for them. The components in the descriptor also have URIs that indicate where they can be found at runtime. These URIs provide the location of content embedded in the catalog or at external locations.

Catalog components include tiles, style sheets, panels, views, interfaces, and services. A catalog can also include additional assets such as images, data, or HTML that are not associated with a specific component.

A catalog can contain references to other catalogs.

Deployed catalogs

To use a catalog in a composite application, you first deploy it to Experience Server. During deployment, Experience Services creates an archive (ZIP) file that contains the CXML descriptor and the content that the descriptor references. You can create the same ZIP file using an automated process such as Ant or Maven.

Experience Services uploads the catalog archive file to Experience Server. The server uses the information in the CXML descriptor to populate the Experience Server node structure at /content/mosaic/catalogs/[catalog name].

For more information about catalogs on Experience Server, see Deployed catalogs.

Client runtime and catalogs

When a composite application runs on a client, the application resolves catalog references on the server and retrieves the catalog descriptor for the client. The permissions of the logged-in user determine the contents of the retrieved catalog. You can use permissions to tune a server to deliver a version of the catalog descriptor that is both specific to the user and optimizes performance. The client runtime retrieves the content for any component in any retrieved catalog only when it encounters the component in the application.

Deployed catalogs

When you deploy a composite application or catalog for the first time, Experience Services creates corresponding nodes and properties on Experience Server. Deploying applications creates a single node tree. Deploying catalogs creates a set of node trees that are organized under the catalog node by component. Catalog components can include tiles, style sheets, and panels.

To view catalog component node trees, explore the node /content/mosaic/catalogs/[catalog name].

When you deploy a catalog that exists on Experience Server, any corresponding catalog component node is replaced with an updated catalog component. Node trees are deleted and replaced, not updated or modified.

Catalog component node trees on Experience Server include any additional content files that are found in the component folder of a catalog archive. Experience Services manages the component description and any content that is specific to the component as a single entity. When you deploy a catalog that contains a new version of the component, all the content of the catalog component node tree is deleted and replaced.

For example, you deploy a catalog that defines a tile named WelcomeTile. The archive of the deployed catalog has an images folder that contains the file WelcomeImage.png. Experience Services adds WelcomeImage.png to Experience Server at the following location:

/content/mosaic/catalogs/tiles/WelcomeTile/images/WelcomeImage.png

If you deploy a catalog in which the WelcomeTile component description does not include WelcomeImage.png, WelcomeImage.png is deleted from Experience Server and not replaced.

Create a catalog

  1. Right-click your Flex project for ADEP-Experience Services and then click New > Composite Application Catalog.

    If you do not see the Composite Application Catalog option, click Window > Reset Perspective to refresh the menus.

    You can create your catalogs in a project that is different from the application’s project.

  2. Enter a name, label, and description for the catalog. For example, for name, enter PropertiesCatalog.

    To use this catalog for the project, ensure Update the ‘[project name]’ Project's Properties to Use This Catalog is selected.

  3. Click Finish.

    Experience Services creates the catalog (CXML) file, which is a catalog template that you use to store your Composite Application Framework elements.

Create a tile

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.

Create a Flex-based tile

Types of Flex-based tiles

There are three types of Flex-based tiles. The type you use depends on your situation:

  • UIComponent: Any extension of spark.components.SkinnableComponent (for example, <s:Button>). You create UIComponent tiles in Flex library projects, not standard Flex projects. However, at runtime, the behavior of UIComponent tiles is almost identical to Module tiles. Because they have several advantages over the other types of tiles, it is recommended that you use UIComponent tiles whenever possible.

    UIComponent tiles are useful if you have a pre-existing Flex component that you want to use as a tile. UIComponent tiles produce both SWC and SWF files as output. Therefore, you can use them as both a component in a statically linked Flex application and as a tile.

    You can also use the "bundle" attribute of the Tile metadata tag to combine multiple UIComponent tiles into a single, loadable file. Using this annotation can reduce application startup time, especially over slow networks.

  • Module: An extension of a spark module <s:Module>. An application can have multiple instances of a module tile but loads the tile classes only once.

    Module tiles allow you to avoid the memory issues that you can occur when you use application tiles. However, UIComponent tiles allow you to avoid those memory issues and also provide additional advantages.

  • Application: An extension of a Spark application <s:Application>. An Application tile is a convenient way to convert an existing Flex application to a tile. However, in general, using application tiles is not recommended. When there are multiple instances of an application tile in a single application, each instance loads independently. These tile instances do not share any resources, which can result in large runtime memory footprints.

The StockService sample uses both UIComponent and Module tiles. For information on samples, see Sample composite applications.

For more information on the differences between these types of tiles, see How Composite Application Framework loads.

For more information on the benefits of constructing modular applications, see “Modular applications overview” in Using Flex 4.5.

Tile references in catalogs

When you create a tile using Experience Services, Experience Services automatically adds the tile to the catalog that is associated with the project. The name and label attributes are set to the package.name specified for the tile when you create it. You can open the CXML file to view the entry for the new tile or edit the label attribute. For example:

<tile:TileClass fitContent="true" height="300" 
    label="com.adobe.mosaic.docs.StockGraph" 
    name="com.adobe.mosaic.docs.StockGraph" width="600"> 
    <ct:Metadata> 
        <ct:Description/> 
    </ct:Metadata> 
 
    <tile:Content contentType="application/x-shockwave-flash" 
        flexSDKVersion="4.5.0" loadAs="module" 
        uri="${catalogURL}/tiles/com.adobe.mosaic.docs.StockGraph/com.adode.mosaic.docs.StockGraph.swf"/> 
</tile:TileClass>

Create a UIComponent tile

  1. For a new or existing Flex library project, enable Composite Application Framework Services, if it is not already enabled:

    1. Right-click the library project and then click Properties.

    2. Expand Adobe and then click Experience Services.

    3. Select Enable Experience Services and then Select Composite Application Services. Click OK.

  2. If your library project is new, add an MXML or ActionScript skinnable component that is derived from spark.components.SkinnableComponent. Add content to your tile as required.

  3. Annotate the component class with [Tile].

    For example, to annotate a component MyButtonTile.mxml:

    <?xml version="1.0" encoding="utf-8"?> 
    <s:Button xmlns:fx="http://ns.adobe.com/mxml/2009" 
                    xmlns:s="library://ns.adobe.com/flex/spark" 
                    xmlns:mx="library://ns.adobe.com/flex/mx" label="UIComponent Tile"> 
           <fx:Declarations> 
                  <!-- Place non-visual elements (e.g., services, value objects) here --> 
           </fx:Declarations> 
           <fx:Metadata> 
                  [Tile] 
           </fx:Metadata> 
    </s:Button>
  4. Save the file.

Create a module or application tile

  1. Right-click your Flex project for ADEP-Experience Services and then click New > Composite Application Tile.

    If you do not see the Composite Application Tile option in the menu, click Window > Reset Perspective to refresh the menus.

  2. Enter a name for the tile. Optionally, enter a package name for the tile. Then click Finish to accept the default tile values.

    By default, Experience Services creates the tile as a module tile. To create an application tile (<s:Application>), deselect Module Tile.

    The new MXML tile includes the [Tile] metadata tag in the <fx:Metadata> element. This annotation indicates to Composite Application Framework that the module is a tile and to include the tile framework functionality.

    To convert an existing Flex application to a tile, you can simply add [Tile] to the <fx:Metadata> section of the application file. In addition, ensure that Composite Application Framework Services is enabled for the project and it has a catalog assigned to it. Experience Services automatically updates the catalog with the new tile.

  3. Add content to your tile.

    You add content to help you confirm that your tile is deployed. It can be any visible element. For example, switch to Design mode and add a Button control from the Components tab:

        <fx:Metadata> 
            // This module is a Composite Application Framework Tile 
            [Tile] 
        </fx:Metadata> 
        <s:Button x="100" y="100" label="Button"/>
  4. Save the file.

Create an HTML tile

HTML tiles display HTML content found at a specified URL. HTML tiles can be written specifically for a composite application and take advantage of the Composite Application Framework’s JavaScript SDK for inter-tile communication. Or an HTML tile can simply point to any available web page. For example, an HTML tile that points to www.adobe.com displays the website in the tile at runtime.

Like Flex-based tiles, you define HTML tiles in the catalog in a TileClass element. The TileClass element describes the location, size, label, and metadata associated with the tile. The difference between an HTML tile and a Flex-based tile is the tile:Content element. For an HTML tile, the contentType is text/html. For a Flex-based tile, the value of contentType is application/x-shockwave-flash.

In either case, the uri attribute indicates the location from which the specified content is retrieved at runtime. Experience Services does not deploy the HTML in Flash Builder. Ensure that the HTML is available at the specified URL.

URL references that launch Flash applications cannot be referenced as HTML tiles.

Note: You can configure the URL in an HTML tile to redirect browsers to a different URL. If you redirect it, the destination URL is not displayed in the tile. Instead, the browser navigates away from the composite application and displays the content of the destination URL only. This behavior is due to the browser’s design.
  1. In the Catalogs project, open the default catalog (Default.cxml).

  2. Ensure that you are in Source mode.

  3. In the tile:TileClassList element, add a tile:TileClass element for an HTML tile. HTML tiles are defined in catalog files directly.

    <!-Add to TileClassList --> 
    <tile:TileClass fitContent="true" height="400" 
        label=" Sample HTML Tile" name="AdobeHome" width="600"> 
        <ct:Metadata> 
            <ct:Description>Simple HTML tile</ct:Description> 
        </ct:Metadata> 
        <tile:Content contentType="text/html" uri="http://www.adobe.com"/> 
    </tile:TileClass>
  4. Save the catalog.

For information on creating an HTML Tile that displays a dynamically generated URL, see Use a context to create the URL for an HTML tile

Modify tile attributes

You can manually update the catalog (CXML) to set schema attributes. For a description of these attributes, see Composite Application Framework XML Schema Reference.

For example, set the Context value attribute to default to the value ADBE:

<tile:TileClass fitContent="true" height="300" 
    label="com.adobe.mosaic.docs.StockGraph" 
    name="com.adobe.mosaic.docs.StockGraph" width="600"> 
    <ct:Metadata> 
        <ct:Description/> 
    </ct:Metadata> 
    <ct:Context> 
        <ct:Data key="stock" type="string" value="ADBE" /> 
    </ct:Context> 
    <tile:Content contentType="application/x-shockwave-flash" 
        flexSDKVersion="4.5.0" loadAs="module" 
        uri="${catalogURL}/tiles/com.adobe.mosaic.docs.StockGraph/com.adode.mosaic.docs.StockGraph.swf"/> 
</tile:TileClass>

For more information on annotations that are available for tiles and adding communication to services or other tiles, see Tile and service communication.

Create a service

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.

Limitations on classes used in a service interface library

Services represent a concrete implementation of an interface. Services are headless and, therefore, do not provide a user interface. For example, do not include or extend the UIComponent ActionScript class or use the Alert class.

Flex classes and their data types are not allowed in the interface because of compatibility issues. The APIs for any two versions of the Flex SDK are not guaranteed to be compatible. This limitation applies to both major releases and update releases. Using a design pattern that is independent of the Flex SDK allows tiles that are created using different Flex SDKs to interact.

Adding Flex SDK references to the interface can create problems in the interface bundle. The runtime reports these problems as a coercion error, which is difficult to diagnose. To avoid these problems, avoid references to the Flex SDK.

However, the restriction on data types used by interfaces in the library does not apply to IList and PropertyChangeEvent. These two classes allow composite application service implementation libraries to use server-side services such as Data Services and still return serializable data across the interface.

For example, Data Services uses ArrayCollection, which you cannot use in a composite application service class interface. However, you can easily cast ArrayCollection as IList for return across the interface.

Although you can’t refer to the Flex SDK in interfaces, this restriction does not apply to implementation libraries. You can use Flex classes and data types in the implementation library if the service implementation does not provide a user interface.

For a complete list of the core ActionScript classes and global functions, see the top-level information in ActionScript 3.0 Language Reference.

Design pattern for composite application services

A service has provider and consumer components that work with a common set of service capabilities. These capabilities are defined in an interface component. To allow the consumer to access the functionality that the service provides, you add a reference to the interface.

The implementation of the service exists independently from the component that provides the service. Therefore, you can use a temporary implementation of the service to develop a tile or other consumer component. This mechanism allows you to do your work in a stable development environment.

The design pattern provides similar advantages when you develop a service. You can create automated tests for all aspects of the service without the full-featured interface that the producing component provides. When development is complete, full production versions of the provider and consumer replace the versions that were used for development and testing.

Creating projects for composite application services

Create two Flex projects to use a service from a tile:

  • A library project that provides the interface that tiles and other resources use to interact with the service. It is the interface project.

  • A library project that implements the interface. It provides the actual functions associated with the service and can contain more than one implementation of the service. It is the service project.

In addition, you create library or application projects that use the service (the consumer).

Create an interface library for a service

Create the interface library project

  1. In Flash Builder, click File > New > Flex Library Project.

  2. Enter a name for the project. For example, name it PropertiesInterfaceLibrary.

  3. Click Finish to accept the default values for the library.

  4. In the Package Explorer, right-click the interface library project, and then click Properties.

  5. Expand Adobe and then click Experience Services.

  6. On the General tab, first select Enable Experience Services. Then select Composite Application Services.

  7. Click Apply, and then click Yes to confirm the changes.

  8. Click Composite Application Framework, select Use Project Settings, and then use the Name list to select a catalog.

    Use a catalog that you have created. For example, PropertiesCatalog. Or use the default catalog.

  9. Click OK to close the Properties dialog box.

Create the service interface

  1. In the Package Explorer, right-click the src folder for the library and then click New > ActionScript Interface.

  2. For Package, enter com.adobe.aep.samples.services.properties. For Name, enter IPropertiesService. Click Finish.

  3. Open the new ActionScript Class file in Source view.

    By default, the file contains a public interface definition.

    package com.adobe.aep.samples.services.properties 
    { 
        public interface IPropertiesService 
        { 
             
        } 
    }
  4. Add the [Expose] metadata tag before the interface definition to specify that the exposed service is a service interface library. Flash Builder compiles all interfaces in the library into a SWC file with the name of the project.

        [Expose]  
        public interface IPropertiesService 
        { 
             
        }
  5. For example, add a function that accepts the setName parameter and type the parameter to the String class. Type the result to the Array class.

        [Expose] 
        public interface IPropertiesService 
        { 
            function getPropertySet(setName:String):Array; 
     
        }
  6. Save the IPropertiesService.as file.

Create a service implementation library

Note: When you create composite application service classes, do not reference any class that is derived from UIComponent. This restriction includes any use of the Alert class.

Create the project for the implementation library

  1. In Flash Builder, click File > New > Flex Library Project.

  2. Enter a name for the implementation library. For example, PropertiesService. Click Next.

  3. If you are creating an implementation library that references a set of classes that are not standard to Composite Application Framework, edit the Build Path configuration. For example, a library that uses the Flex SDK remoting classes to interact with Data Services.

    On the Build Paths page, on the Library Path tab, for Framework Linkage, select Merged Into Code.

    The Merged Into Code option configures the library path to merge the required code into the SWC file for the library.

  4. Click Finish.

  5. In the Package Explorer, right-click the implementation library project, and then click Properties.

  6. Expand Adobe and then click Experience Services.

  7. On the General tab, first select Enable Experience Services. Then select Composite Application Services.

  8. Click Apply, and then click Yes to confirm the changes.

  9. Click Composite Application Framework, select Use Project Settings, and then use the Name list to select the catalog. For example, PropertiesCatalog.

  10. Click Flex Library Build Path.

  11. Click Add Project and select PropertiesInterfaceLibrary.

    This project is the service interface library that you created. It contains the IPropertiesService interface class that this library implements.

  12. Click OK.

Create the service implementation class

  1. In the Package Explorer, right-click the src folder for the PropertiesService library and then click New > ActionScript Class.

  2. For Package, enter com.adobe.aep.samples.services.properties.impl and for Name, enter PropertiesService. Click Finish.

  3. Open the new ActionScript Class file in Source view.

    By default, the file contains a public class definition and its constructor.

    package com.adobe.aep.samples.services.properties.impl 
    { 
        public class PropertiesService 
        { 
            public function PropertiesService() 
            { 
            } 
        } 
    }
  4. Before the class definition, import the IPropertiesService class.

    package com.adobe.aep.samples.services.properties.impl 
    {  
        import com.adobe.aep.samples.services.properties.IPropertiesService;  
     
        public class PropertiesService implements IPropertiesService 
        { 
    ... 
    }

    IPropertiesService is the interface that this library implements. It is located in the PropertiesInterfaceLibrary project that you created.

  5. Add the following additional elements before the class definition:

    • An [Expose] metadata tag to specify that the exposed service is a service implementation library.

    • A library parameter that specifies the name of the library to implement. For example, PropertiesInterfaceLibrary.

    • A scope parameter that determines whether a new instance of the service is created for each object that requests it. If the value is prototype, a new instance is created.

      For this example, the value is singleton, which constrains the service to a single instance.

        [Expose(library="PropertiesInterfaceLibrary", scope="singleton")]  
        public class PropertiesService implements IPropertiesService 
        { 
            public function PropertiesService() 
     
        }
  6. Add elements that provide some implementation for the PropertiesService.

For more information about using service-related annotations, see Using composite application annotations (Tile, Application, ContextBind, Expose, Consume, SecurityManager).

Custom services using Client Component Framework

When you create a service and use the [Expose] metadata tag, Experience Services generates a Client Component Framework (GXML) file in the “mosaic/generated” folder. This automatic behavior allows you to quickly create services with little or no knowledge of Client Component Framework. However, in some cases, you need a configuration that is different from the one that Experience Services creates automatically. To change the configuration, first copy the generated GXML file from the "mosaic/generated" folder and paste it in the "mosaic" folder (one level up). Flash Builder does not update files in this folder. It also gives them priority over files with the same name in the "mosaic/generated" folder when it builds and uploads a catalog. After it is relocated to the mosaic folder, you can edit that file and still perform any tasks or operations that Client Component Framework supports. An example of this configuration is provided in the Getting Started sample named MultipleStockServices, which is installed as part of the samples package.

Create a panel

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.

Create a view

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.

Use application layouts

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.

Use view:Layout to specify a layout

To choose a different layout, you can add a view:Layout element to the appropriate parent element in the composite application definition. The name attribute of the view:Layout element specifies which layout to use.

Layouts can be children of view:Panel, view:View, view:ViewManager, and app:Shell elements. You can also nest container elements, such as view:Panel, with different layouts to create the application structure that you want.

The default skin for the ViewManager element provides a tab bar, which is designed to use StackLayout. Adding a layout child element to ViewManager makes the tab bar either confusing to use or not work at all. To remove the tab bar and StackLayout, create a custom skin, a custom layout, or both to modify how the views are displayed.

Use the Composite Application Framework SDK to specify a layout

Alternatively, you can add a layout to a composite application component using the Composite Application Framework SDK and Layout API.

For example, the following excerpt from a Flex-based tile creates a layout based on SmartColumnLayout. It modifies some of the layout’s attributes and then creates a blank panel that uses the layout:

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

For setAttribute, both parameters are always a string.

Layouts used with composite applications

Composite applications use both layouts that are unique to Composite Application Framework and Spark layouts. Composite Application Framework provides the following layouts for use with an application:

Layout

Description

FlowLayout

Arranges components in columns and rows, left to right and top to bottom. Each row can have a different number of components, depending on their size.

FlowLayout ignores a component’s x and y attributes and preserves its width and height attributes. It places components in the order in which they were created.

SmartColumnLayout

Arranges components into columns of equal width. It adjusts the width of components to fit the column and preserves the component height.

SmartColumnLayout ignores a component’s x and y attributes. It places components either in the order in which they were created or using the column or row index values that you specify.

SmartGridLayout

Arranges components in a grid that fills the maximum available space.

SmartGridLayout adds columns as required and adds additional rows when the number of columns is greater than the value of maxNumColumns. Similarly, it adds rows as required and adds columns when the number of rows is greater than the maxNumRows value.

If your application uses a single tile, SmartGridLayout resizes it to fit the full display area. (TileLayout preserves the size of the component so it does not fill the display area.)

SmartGridLayout ignores a component’s x, y, width, and height attributes. It places components either in the order in which they were created or using column or row index values that you specify.

Default layout for view:Panel elements.

SmartRowLayout

Arranges components into rows of equal height. It adjusts the height of components to fit the row and preserves the component width.

SmartRowLayout ignores a component’s x and y attributes. It places components either in the order in which they were created or using column or row index values that you specify.

StackLayout

Resizes and positions a single component so that it fills the maximum available space.

In most cases, you use this layout with a Spark ButtonBar control to display a button or tab for each component in the layout. When the user selects a button or tab, the corresponding component is displayed and all other components are hidden.

StackLayout places components in the order in which they were created.

Default layout for view:ViewManager and view:View elements.

In addition, you can use the following Spark layouts in the same way that you use the layouts that are specific to composite applications. That is, when you reference these Spark layouts in a composite application, you can use their short name:

Layout

Description

BasicLayout

Places components at the specified location. Do not use for HTML tiles because these tiles do not work properly if they overlap.

BasicLayout preserves a component’s x, y, top, left, bottom, right, width, and height attributes.

Default layout for app:Shell elements.

HorizontalLayout

Arranges components in a single row, from left to right.

HorizontalLayout ignores a component’s x and y attributes and preserves its width and height attributes. It places components in the order in which they were created.

TileLayout

Arranges elements in columns and rows where each component is the same size as the tile’s largest component. The grid is organized left to right and top to bottom. Change the tile layout direction using the orientation property.

This layout is useful if you have a single tile but do not want it to use all the available space. (SmartGridLayout resizes a single component to fill the display area completely.)

TileLayout ignores a component’s x, y, width, and height attributes.

VerticalLayout

Arranges components in a single column, top to bottom.

VerticalLayout ignores a component’s x and y attributes and preserves its width and height attributes. It places components in the order in which they were created.

You can reference any other Spark layouts, or custom layouts, by using the fully qualified package and class name.

For example, a reference to a custom package uses the following format:

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

Layout attributes

Each layout has a set of attributes that determine its behavior. These attributes are the properties of the layout class. For example, for SmartGridLayout, maxNumColumns determines the number of columns that the layout creates before it creates new rows. For TileLayout, orientation determines the direction in which the layout places components in the grid.

For detailed information on composite application and Spark layouts and their properties, see ActionScript 3.0 Language Reference.

To set these attributes using the Composite Application Framework SDK, set them when you create the layout and assign it to a new view or panel. The composite application runtime ignores any changes made to these attributes that are made during runtime.

Create a style sheet reference

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.

Create a custom skin

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.

Drag and drop tiles

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>

Add a custom layout

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.

Create a composite application file (AXML file)

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.

Add composite applications or tiles to Flex or AIR applications

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.

Server session for a custom composite application

The mosaic:ServerSession element is located in the Declarations block. It specifies a connection to Experience Server and a server session that the composite application MXML components use. At runtime, Flash Player or AIR client uses the session to retrieve the application or components from the specified Experience Server.

For example:

<fx:Declarations> 
    <mosaic:ServerSession                        id="myServerSession" 
                            autoConnect="true" 
                            url="{_crxQuickstartServerUrl}" 
                            securityManager="{_securityManager}" 
                            openSessionEventSuccess="CCAUtil.openSessionEventSuccess(event)" 
                            openSessionEventFailure="CCAUtil.openSessionEventFailure(event)"/> 
... 
</fx:Declarations>

A securityManager instance defined elsewhere in the MXML file provides user authentication, not mosaic:ServerSession. For more information about the Experience Services Security Client, see the com.adobe.livecycle.ria.security.* class packages in ActionScript 3.0 Language Reference.

Creating a web or AIR client application that contains a standard composite application

You create a Flex web or desktop (AIR client) application that incorporates a standard composite application using a Flex project for custom composite applications. For information on creating this type of project, see Create a Custom Composite Applications project.

To reference a composite application, you specify the following elements in the MXML application file provided by the custom composite application project:

  • A server session

  • A composite application (AXML) file

  • An application shell

For information on the server session, see Server session for a custom composite application.

The mosaic:Application element is located in the Declarations block and specifies the composite application to add. It has an identifier and its name property specifies the appropriate application (AXML) file on Experience Server:

<fx:Declarations> 
    <mosaic:ServerSession                        id="myServerSession" 
                            autoConnect="true" 
                            url="{mosaicCrxQuickstartServerUrl}" 
                            securityManager="{securityManager}" 
                            openSessionEventSuccess="openSessionEventSuccess(event)" 
                            openSessionEventFailure="openSessionEventFailure(event)"/>  
    <mosaic:Application                     id="myAXMLApplication" 
                        name="TileGame" 
                        serverSession="{myServerSession}" 
                        loadApplicationEventSuccess="CCAUtil.loadApplicationEventSuccessHandler(event)" 
                        loadApplicationEventFailure="CCAUtil.loadApplicationEventFailureHandler(event)"/> 
</fx:Declarations>

The mosaic:Shell element is located in the Spark component that defines the layout area for the Flex application. It references the composite application using the identifier from the mosaic:Application element and specifies the application’s dimensions. For example, you can add the mosaic:Shell element to a VGroup:

<s:VGroup height="100%" width="100%"> 
    <mosaic:Shell                 id="myShell" 
                    application="{myAXMLApplication}" 
                    height="100%" 
                    width="100%"/> 
</s:VGroup>

Creating a web or AIR client application that contains tiles

You create a web or desktop (AIR client) application that uses composite application tiles and other components using a Flex project for custom composite applications. For information on creating this type of project, see Create a Custom Composite Applications project.

To reference a composite application components, you specify the following elements in the MXML application file provided by the custom composite application project:

  • A server session

  • An identifer for the set of composite application components to include

  • References to tiles and services and the catalogs associated with them

For information on the server session, see Server session for a custom composite application.

Application identifier and references to catalogs

The mosaic:Application element is located in the Declarations block and specifies a unique identifier for the composite application MXML components.

Elements in mosaic:Application specify one or more catalogs that are associated with the composite application components. Each mosaic:Catalog element has an identifier and its name property that corresponds to the catalog on Experience Server. The serverSession property specifies the appropriate Experience Server connection to use.

<fx:Declarations> 
    <mosaic:ServerSession                        id="myServerSession" 
                            autoConnect="true" 
                            url="{mosaicCrxQuickstartServerUrl}" 
                            securityManager="{securityManager}" 
                            openSessionEventSuccess="openSessionEventSuccess(event)" 
                            openSessionEventFailure="openSessionEventFailure(event)"/>   
    <mosaic:Application                     id="myNewApplication" 
                        loadApplicationEventSuccess="CCAUtil.loadApplicationEventSuccessHandler(event)" 
                        loadApplicationEventFailure="CCAUtil.loadApplicationEventFailureHandler(event)"/> 
        <mosaic:catalogs> 
            <mosaic:Catalog                 id="mySampleCatalog" 
                            name="CustomAppCatalog" 
                            serverSession="{myServerSession}" 
                            catalogLoadEventSuccess="CCAUtil.catalogLoadEventSuccess(event)" 
                            catalogLoadEventFailure="CCAUtil.catalogLoadEventFailure(event)"/> 
            </mosaic:catalogs> 
... 
</fx:Declarations>

Service references

If the tiles use a service, the Declarations block also requires a mosaic:Service element. Its properties specify an identifier, the name of the service on Experience Server, and the associated catalog and service library. The shell property makes the service a peer of tiles and any other components in the application shell.

<fx:Declarations> 
... 
    <mosaic:Service                id="myPropertyService" 
                    library="ComboService2" 
                    name="PropertiesService" 
                    catalog="{mySampleCatalog}" 
                    shell="{myNewApplication.shell}"/> 
</fx:Declarations>

Tile references

One or more mosaic:Tile elements are located in the Spark component that defines the Flex application layout. They reference tiles found in the catalogs that are specified in the mosaic:Application element. They also set the tile dimensions in the application shell. The parentNode property specifies that the tiles are peers in the shell, which allows them to interact with each other and any peer services.

<s:VGroup height="100%" width="100%"> 
    <mosaic:Tile                name="MyTile1" 
                    catalog="{mySampleCatalog}" 
                    parentNode="{myNewApplication.shell}" 
                    addTileEventSuccess="CCAUtil.addTileEventSuccess(event)" 
                    addTileEventFailure="CCAUtil.addTileEventFailure(event)" 
                    height="50%" width="100%"/> 
    <mosaic:Tile                name="MyTile2" 
                    catalog="{mySampleCatalog}" 
                    parentNode="{myNewApplication.shell}" 
                    addTileEventSuccess="CCAUtil.addTileEventSuccess(event)" 
                    addTileEventFailure="CCAUtil.addTileEventFailure(event)" 
                    height="50%" width="100%"/>          
</s:VGroup>

Add a view to an 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.

Add a panel to an application

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.

Add a tile to an application

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.

Add a service to an application

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.

Add composite application components to an HTML page

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.

Use skins in the application file

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

Apply default styles

Each composite application component uses a default style that is defined in the default style sheet (CSS). You can view the default CSS in the [ADEP SDK root directory]riaservices/mosaic/10.0.0.0/flex/4.5.0/runtimes/player/assets folder.

The following table maps the composite application components to their default styles. When you create your custom CSS, you can use the default naming, or create your own.

Component

Default Style Name

Default Layout

Alternate Styles

Shell

ShellStyle

BasicLayout

n/a

ViewManager

TabbedViewManagerStyle

StackLayout

PlainViewManagerStyle

View

TabbedViewStyle

StackLayout

PlainViewStyle

Panel

PlainPanelStyle

SmartGridLayout

TabbedPanelStyle, PanelInShellStyle

Tile

TileStyle

n/a

n/a

To use an alternate style, update the styleName attribute. For example:

<view:Panel label="Basic" name="Basic" styleName="PanelInShellStyle">

Apply custom styles

When creating a custom CSS, you can choose to use the same style names to overwrite default styles, or create new styles. If you use existing style names, you do not have to explicitly specify the styles using the styleName attribute in your application XML definition. If you use custom style names, then to implement it in your application, specify the style using the styleName attribute on the corresponding element.

For example, the following CSS entry defines the default style for the view:Shell element:

.ShellStyle { 
    skin-class: ClassReference('com.adobe.mosaic.skins.aqua.ShellSkin'); 
    background-alpha: 1; 
}

To use the existing style, but change its definition, you update values for the existing class. For example, you could create a custom ActionScript or MXML skin class and reference it using the skin-class attribute:

.ShellStyle { 
    skin-class: ClassReference('com.mycompany.styles.skins.MySkin'); 
    background-alpha: 1; 
}

Or you could create a custom CSS and define a new class:

.MyShellStyle { 
    skin-class: ClassReference('com.mycompany.styles.skins.MySkin'); 
    background-alpha: 1; 
}
Note: Do not apply a style that has a background -alpha value set for an HTML tile. A composite application displays HTML tiles that use this kind of style inconsistently.

If you choose to define a new class, add a reference to the style using the styleName attribute on the appropriate application XML element. For example:

<app:Shell label="Basic" name="Basic" styleName="MyShellStyle">

Tokens used in composite application, catalog, and Client Component Framework files

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.

Catalog-only tokens

Experience Services also generates additional tokens for catalog files only. These tokens are replaced with the current URI values by the composite application client runtime.

${catalogURL}
The Composite Application Framework client runtime replaces this token with the name of the catalog that a component references. For example, http://localhost:4502/content/mosaic/catalogs/myCatalog. TileReference, Stylesheet Reference, and ServiceReference are examples of components that reference catalogs.

${serverURL}
The client runtime replaces this token with the URL for the Experience Server that the runtime is connected to. The ${serverURL} token includes the context root. For example, http://localhost:4502/mosaic.

${baseURL}
The client runtime replaces this token with the URL for the root of the Experience Server that the runtime is connected to. For example, http://localhost:4502.

Client Component Framework-only tokens

Client Component Framework files use additional tokens as placeholders for debugging purposes and to configure where the Flex compiler checks for metadata tags. The Client Component Framework runtime evaluates these tokens.

${debug}
When the value assigned to this token is -debug, the Composite Application Framework client debug runtime is used.

Custom token for Client Component Framework

You can also define a custom token to use in a Client Component Framework (GXML) file.

Because of the way scoping works in Composite Component Framework, property definitions are only visible in GXML files that are included by the one that contains the definition. You refer to the definition using the ${myToken} syntax. For example, a GXML file contains the following definition:

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

The associated child.gxml can contain this constructor argument:

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

Composite Application Framework for HTML JavaScript API Reference

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.

Tile class

The Tile class represents a particular tile.

This constructor is for internal use only. Do not use.

Service class

The Service class represents a particular service.

This constructor is for internal use only. Do not use. For information on how to obtain a service, see Catalog.getService.

Catalog class

The Catalog class represents a particular catalog, and provides methods for retrieving views, panels, and tiles from a catalog that has been deployed to the server.

Methods

getTile

Retrieves a tile from the catalog to add to an application.

Syntax

getTile(tileName)

Parameters

tileName
The name of the tile in the catalog. This name corresponds to the name attribute in the deployed catalog.

Returns

An object of type Tile with the specified name.

getService

Retrieves a service from the service library in the catalog.

Syntax

getService(serviceName,libraryName)

Parameters

serviceName
The name of the service class.

libraryName
The service library name that holds the service class.

Returns

An object of type Service with the specified name from the specified library.

resolveURL

Converts a relative URL from the catalog to a fully qualified URL that points to the current Experience Server.

Syntax

resolveURL(url)

Parameters

url
Relative URL from the catalog.

Returns

A URL in which tokens are replaced and specifies the Experience Server.

MessageBus class

The MessageBus class provides methods for handling communication between tiles.

Methods

addMessageListener

Adds a message listener assigned to a namespace-name combination. Triggers the listener with a PropertyChange Event from Flex.

Syntax

addMessageListener(ns,name,listener)

Parameters

ns
The namespace of the message.

name
The name of the message.

listener
A function that triggers when a message matching the namespace-name combination is broadcast.

removeMessageListener

Removes a message listener assigned to a namespace-name combination.

Syntax

removeMessageListener(ns,name,listener)

Parameters

ns
The namespace of the message.

name
The name of the message.

listener
A function that triggers when a message matching the namespace-name combination is broadcast.

sendMessage

Broadcasts a message across the application level that reaches all listeners, regardless of the panel or view.

Syntax

sendMessage(message,forFlex,forHTML,pack)

Parameters

message
Any object that can be serialized.

forFlex
DEFINITION

forHTML
DEFINITION

pack
DEFINITION

Context class

The Context class models a simple hash map that allows tiles to store attributes in name-value pairs. The names of the name-value pairs uniquely identified them, and any tile can reference a name-value pair using the unique identifier.

The context is specific to its accessor. For example, mosaicApp.context is shared for the application. Views and Panels are not currently supported in HTML Shell and therefore do not have contexts.

This constructor is for internal use only. Do not use.

Syntax

Context(o)

Parameters

o
The ID of the current node to determine the associated context.

Methods

getAttribute

Returns a named attribute from the context.

Syntax

getAttribute(name)

Parameters

name
The name of the attribute.

Returns

The attribute stored in a context.

addAttributeWatcher

Adds a watcher to the context.

The context watchers behave similarly to watchers in Flex. What makes them different is that you do not need to set the context attribute before you create the watcher. This capability allows a tile to watch for an attribute that is not set yet.

Syntax

addAttributeWatcher(name, listener, tileId)

Parameters

name
The name of the context object to watch.

listener
A listener function that triggers when a PropertyChange event occurs.

tileId
The tile that is watching for the changes.

addAttributesWatcher

Adds a watcher to the context.

The context watchers behave similarly to watchers in Flex. What makes them different is that you do not need to set the context attributes before you create the watcher. This capability allows a tile to watch for an attribute that is not set yet.

Syntax

addAttributesWatcher(names, listener)

Parameters

names
The names of the context objects to watch.

listener
A listener function that triggers when a PropertyChange event occurs.

removeAttributeWatcher

Removes a watcher from the context.

The context watchers behave similarly to watchers in Flex. What makes them different is that you do not need to set the context attribute in advance of creating the watcher. This capability allows a tile to watch for an attribute that is not set yet.

Syntax

removeAttributeWatcher(name, listener)

Parameters

name
The name of the context object to no longer watch.

listener
A listener function that triggers when a PropertyChange event occurs.

setAttribute

Sets a single attribute in the context to a value.

Syntax

setAttribute(name, value)

Parameters

name
The name of the attribute to set a value for.

value
The value to assign to the specified attribute.

setAttributes

Sets an array of attributes in the context to an array of values.

Syntax

setAttributes(names,values)

Parameters

names
An array of names of the attributes to set values for.

values
The values to assign to the attributes.

Application class

The Application class provides access to the DOM for an application. It also provides methods for adding views, panels, and tiles and querying aspects of the application's environment.

JQuery Functions

addTile

The addTile method adds a tile to a particular jQuery object. The tile is appended to the end of the list of children that the jQuery object points to. This method creates a Flash Player embed tag and loads the tile.

Syntax

addTile(newTile)

Parameters

newTile
The tile to add.

Returns

A jQuery object.

loadCatalog

The loadCatalog method returns a catalog that has been deployed to the Experience Server. When you deploy a a catalog to the server, the browser loads the catalog into its cache.

Syntax

loadCatalog(catalogName,ready,error)

Parameters

catalogName
The name of the catalog to load.

ready
A function to call when the catalog is loaded. Give the function the following signature, where the catalog parameter is the catalog object to load:
function gotCatalog(catalog){}

error
A function to call when there is an error while attempting to load the catalog.