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

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

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

Create an ADEP-Experience Services project in Flash Builder.

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

Create tiles and services.

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

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.

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.

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

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.

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:

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

Click CRXDE Lite.

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

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].

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.

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

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.

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.

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.

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:

Create a module or application tile

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

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.

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:

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.

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.

In the Catalogs project, open the default catalog (Default.cxml).

Ensure that you are in Source mode.

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

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.

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

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

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

Click Finish to accept the default values for the library.

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

Expand Adobe and then click Experience Services.

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

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

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.

Click OK to close the Properties dialog box.

Create the service interface

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

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
{
}

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.

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

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

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

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.

Click Finish.

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

Expand Adobe and then click Experience Services.

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

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

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

Click Flex Library Build Path.

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.

Click OK.

Create the service implementation class

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

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.

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.”

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.

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:

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.

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:

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.

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.

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

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.

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.

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

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.

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.

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.

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.

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:

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:

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:

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

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.

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.

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.

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.

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:

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.

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.

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:

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:

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:

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.

Twitter™ and Facebook posts are not covered under the terms of Creative Commons.