Tile and service communication

When the Tile metadata tag adorns a class, Experience Services automatically updates the appropriate catalog definition file (CXML) with a corresponding tile reference.

For example, the following excerpt defines the class as a tile:

[Tile] 
public class SomeTile(){ 
 
}

[Tile] can also adorn a member variable of a class. In this context, the metadata tag directs the client runtime to inject the variable with the value of the host tile. This injection allows the tile to access the Composite Application Framework SDK. For example:

[Tile] 
public class someTile(){ 
    [Tile]    public var thisTile:ITile; 
}

When you use Tile to define a variable, ensure that the variable is public and typed as ITile.

The Tile metadata tag supports a bundle parameter when it adorns a UIComponent tile class. It specifies that the class is included in the named SWF file and allows multiple tiles to reside in a single SWF file. Normally, each UIComponent tile has its own SWF file. This ability improves efficiency and allows you to control how many SWF files are downloaded.

The MXML syntax is:

<fx:Metadata> 
    [Tile(bundle="manyTiles")] 
</fx:Metadata>

In this example, any UIComponent tile with the specified bundle value is added to the manyTiles.swf. The .swf filename extension is not included in the value of the bundle parameter.

You use the Application metadata tag with a public variable in an ActionScript class. It allows you to create a reference to the instance of the composite application that the framework generates at runtime. The variable is typed as IApplication.

For example, the following excerpt defines the variable app to inject the application into:

[Application] 
public var app:IApplication;

When you use [Application] to adorn a variable, ensure that the variable is public and typed as IApplication.

Composite Application Framework uses contexts to set attribute values and share those values among tiles and services. For example, contexts are often used to automatically update information in a tile or service when the user updates the same information in another tile or service.

Use the ContextBind metadata tag to define a context and its attributes.

attribute

The [ContextBind] metadata tag must reside in the MXML file that contains the [Tile] metadata tag. This ensures that Experience Services can correctly identify the file that the context belongs to.

For example, a tile can use multiple contexts where each instance of [ContextBind] represents a different attribute to communicate or listen for. However, although you can create a tile using multiple MXML source files, you cannot include the contexts in a MXML file other than the one that contains [Tile].

The following excerpt from a tile definition creates the context dashboardStatus and the attributes bugID and clientID.

<s:Group xmlns:fx="http://ns.adobe.com/mxml/2009" 
         xmlns:s="library://ns.adobe.com/flex/spark" 
         xmlns:mx="library://ns.adobe.com/flex/mx" width="400" height="300"> 
    <fx:Script> 
        <![CDATA[ 
        [Bindable] 
        [ContextBind(name="dashboardStatus",attribute="bugID")] 
        public var bugid:int; 
 
        [Bindable] 
        [ContextBind(name="dashboardStatus",attribute="clientID")] 
        public var client:int; 
        private function selectedCaseChanged():void 
        { 
            bugid = int(caseList.selectedItem.bugid); 
            client = int(caseList.selectedItem.clientid); 
        } 
        ]]> 
    </fx:Script>

The attributes are bound to fields in a data grid that is defined in the same tile’s user interface:

    <mx:DataGrid id="caseList" width="100%" height="100%" dataProvider="{cases}" change="selectedCaseChanged()"> 
        <mx:columns> 
            <mx:DataGridColumn headerText="id" dataField="id"/> 
            <mx:DataGridColumn headerText="issue" dataField="issue"/> 
            <mx:DataGridColumn headerText="os" dataField="os"/> 
            <mx:DataGridColumn headerText="clientid" dataField="clientid"/> 
            <mx:DataGridColumn headerText="bugid" dataField="bugid"/> 
        </mx:columns> 
    </mx:DataGrid> 
</s:Group>

You can reference the context and its attributes as required in other tiles. For example, the following tile excerpt retrieves the value of the bugID attribute.

<fx:Script> 
        <![CDATA[ 
            import mx.events.PropertyChangeEvent; 
            [Bindable] private var _bug:Object = new Object; 
 
            [ContextBind(name="dashboardStatus",attribute="bugID")] 
            public function get bugID():int{ 
                return _bug.id; 
            } 
            public function set bugID(id:int):void{ 
                _bug = findBug(id); 
            } 
            private function findBug(id:int):Object 
            { 
                var b:XMLList = bugs; 
                for each( var bug:XML in b) { 
                    if( int(bug.id) == id ) 
                    { 
                        return bug; 
                    } 
 
                } 
                return new Object; 
            } 
 
        ]]> 
    </fx:Script>

The following excerpt defines an XMLList that the findbug function searches:

<fx:Declarations> 
        <fx:XMLList id="bugs" xmlns=""> 
            <bug> 
                <id>23312</id> 
                <description>Nullam eget at nulla nec eget ipsum.</description> 
                <owner>Michael King</owner> 
                <notes>Ut sit amet dolor arcu, ac feugiat metus</notes> 
                <dateopen>2009-03-15</dateopen> 
                <priority>3</priority> 
                <status>open</status> 
            </bug> 
            .... more bug samples .... 
            <bug> 
                <id>23299</id> 
                <description>Nullam eget at nulla nec eget ipsum.</description> 
                <owner>Michelle Jones</owner> 
                <notes>Mauris euismodtempus ut.</notes> 
                <dateopen>2009-03-26</dateopen> 
                <priority>3</priority> 
                <status>open</status> 
            </bug> 
        </fx:XMLList> 
    </fx:Declarations>

When the user updates the bugID property in the first tile, the new value is automatically displayed in both tiles.

For more information on using [ContextBind], including limitations on the data types you can use with contexts, see Add a context to a tile.

In Composite Application Framework, components that use a service make reference to it using an interface. The implementation of the service exists separately. This design pattern allows any binding to a service definition to happen dynamically at runtime. The client runtime injects the appropriate instance of the service at the location specified by the Consume metadata tag. The Expose metadata tag indicates that classes are part of an interface or implementation library.

The Expose metadata tag specifies that an interface is part of a service interface library or that a class is part of a service implementation library.

Use Expose with no additional properties to define an interface for use in a service interface library. To define a class in an implementation library, use Expose and the following properties as required:

library

In the following excerpt, Expose specifies that the interface is deployed to the server in a service interface library. The interface provides tiles with access to the information and functions that the service provides:

[Expose] 
public interface IStockDataService 
{ 
    ... 
}

You also use the Expose metadata tag and its properties to define classes in an implementation library. The implementation library contains classes that perform functions such as data lookup. For example, the following excerpt defines a class that implements the IStockDataService interface:

[Expose(catalog="StockService" library="StockDataInterfaceLibrary", scope="singleton")] 
    public class StockDataService implements IStockDataService

Use the Consume metadata tag to inject a tile with a service at runtime. This configuration allows a tile to exist independently and still access the functionality and information provided by the service.

For composite applications, you define a service interface using the Expose metadata tag.

library

In the following tile excerpt, Consume specifies the interface that it is requesting:

<fx:Script> 
    <![CDATA[ 
        import com.adobe.mosaic.samples.services.stockdata.IStockDataService; 
 
        [Bindable] 
        [Consume(catalog="StockService" library="StockDataInterfaceLibrary")] 
        public var stockDataService:IStockDataService; 
 
    ]]> 
</fx:Script>

The public variable stockDataService references the exposed interface found in the interface library.

Use the SecurityManager metadata tag to inject an attribute with the current Experience Services Security Manager.

The Security Manager is the ISecurityManager interface provided by the com.adobe.livecycle.ria.security.api class package. For more information on this package, see ActionScript 3.0 Language Reference.

The variable must be public and typed as ISecurityManager. Typically, you use the variable that [SecurityManager] adorns to obtain a user ID. For example:

<?xml version="1.0" encoding="utf-8"?> 
<s:Module xmlns:fx="http://ns.adobe.com/mxml/2009" 
          xmlns:s="library://ns.adobe.com/flex/spark" 
          xmlns:mx="library://ns.adobe.com/flex/mx" 
          xmlns:mc="com.adobe.mosaic.core.*" 
          preinitialize="{this.addEventListener(AnnotationParseEvent.COMPLETE, annotationsDone)}"> 
 
    <fx:Metadata> 
        [Tile] 
    </fx:Metadata> 
 
    <fx:Script> 
        <![CDATA[ 
            import com.adobe.mosaic.om.events.AnnotationParseEvent; 
 
            private function annotationsDone(event:AnnotationParseEvent):void { 
                this.removeEventListener(AnnotationParseEvent.COMPLETE, annotationsDone); 
                trace('Annotations Parse Event Complete!'); 
            } 
        ]]> 
    </fx:Script> 
</s:Module>

If HTTP Basic Authentication is enabled on the Experience Server, you cannot use the Experience Services Security Manager within a tile. The injected ISecurityManager defaults to null.

You can see an example of [SecurityManager] in the UserInfoTile tile (UserInfoTile.mxml) that the GeoMetrixxDashboard sample application uses. GeoMetrixxDashboard is part of the Dashboard sample. For more information on samples, see Sample composite applications.

When you add Expose, Consume, or Tile metadata tags to a class, Experience Services automatically generates corresponding Client Component Framework (GXML) files. These configuration files are added to the project’s mosaic/generated folder.

Because the GXML files externalize the interface and implementation of application services, you can modify services without changing the composite application source code. For example, to change the current service configuration, replace the appropriate GXML files in the mosaic/generated folder with files that have the same name and the desired configuration.

At runtime, the Composite Application Framework client checks tile components and their children in the display list for metadata tags related to composite applications. Use the annotationDepth property to set to what depth the client runtime checks for annotations.

The default value for annotationDepth is 10.

Checking for annotations as classes are loaded uses processing resources. The higher the value of annotationDepth, the more processing resources are required. For best performance, set this value to the lowest value that is needed for your applications.

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 folder. Double-click gravity-flex-di-swf11.gxml to display it in the Edit pane.

4. In the Edit pane, edit the value of annotationDepth.

5. Click Save All.

The composite application client processes some of the composite application metadata tags at runtime. Therefore, ensure that the metadata tags are included in the SWF file that the Flex compiler generates.

The compiler retains annotations when it compiles the debug version of the SWF file but removes and optimizes them when it compiles the release version. For Flex projects that are enabled for Composite Application Framework Services, Experience Services automatically adds the following option to the project’s additional compiler arguments:

-keep-as3-metadata+=Tile,Application,ContextBind,SecurityManager

To preserve annotations when you compile a release build using Ant, add a keep-as3-metadata element for each metadata tag to the mxmlc target. (You do not have to add the option for debug builds.)

For example:

<mxmlc ...> 
        <keep-as3-metadata name="Application"/> 
        <keep-as3-metadata name="ContextBind"/> 
        <keep-as3-metadata name="SecurityManager"/> 
        <keep-as3-metadata name="Tile"/> 
</mxmlc>

Alternatively, write a <flex-config> file and then load it during the build. The Composite Application Framework samples provide examples of this method.

To know when your application can safely refer to variables that you have annotated with either [Tile] or [Application], you can listen for AnnotationParseEvent events (com.adobe.mosaic.om.events.AnnotationParseEvent). For each variable annotated with [Tile] or [Application], you receive an AnnotationParseEvent with a type of AnnotationParseEvent.COMPLETE when that variable is available to use.

Alternatively, you can use a preinitialize event with a handler to verify that a composite application component is loaded. For example:

<s:Module 
... 
preinitialize="this.addEventListener(AnnotationParseEvent.COMPLETE, handleAnnotationParseEvent);"> 
 
private function handleAnnotationParseEvent(event:AnnotationParseEvent):void { 
    this.removeEventListener(AnnotationParseEvent.COMPLETE, handleAnnotationParseEvent); 
    // The tile is now ready 
}

For more information about Composite Application Framework annotations, see Using composite application annotations (Tile, Application, ContextBind, Expose, Consume, SecurityManager).

Use the loadPolicy attribute to choose when an application loads a Flex-based tile.

Loading a tile involves retrieving all the logic, styles, and content associated with the tile from the Experience Server. If your application has large or complex tiles, or many tiles, loading them all at startup can increase how long it takes to open. The loadPolicy attribute allows you to specify which tiles are not loaded until the user opens a view in which they are displayed.

The loadPolicy attribute is available for TileClass elements when you create catalogs. It is also available for TileReference elements when you define the contents of a view or panel in an application. It can have one of the following values:

auto

Tiles can inherit their loadPolicy setting from their parent components. For example, a tile is defined in a catalog with a loadPolicy value of all. When an application that uses this tile is opened, the tile is loaded. However, if the same tile in the application file has a loadPolicy value of auto, the catalog setting is ignored. A tile with a loadPolicy value of auto loads only when the panel is displayed.

In the following example, Open Issues and Order History are large tiles. By setting loadPolicy to auto, those tiles are not loaded until the user opens the view that contains them (Customer Service).

                <tile:TileReference name="OpenIssues" label="Open Issues" top="0" left="0" width="50%" height="40%" loadPolicy="auto"/>  
                <tile:TileReference name="Offers" label="Special Offers" top="0" right="0" width="50%" height="40%" loadPolicy="all"/>   
                <tile:TileReference name="Orders" label="Order History" left="0" right="0" bottom="0" height="60%" loadPolicy="auto"/> 

Client Component Framework injects the variables marked with the [Consume] metadata tag when the service is loaded into your application, not during the annotation parsing phase. Therefore, use a technique other than AnnotationParseEvent to determine when service injection is complete.

One technique is to use a setter instead of a public variable. When you use a public variable, the variable is set directly when the service is injected.

[Consume(catalog="stockmosaicservice_catalog" library="StockDataInterfaceLibrary")] 
public var _stockDataService:IStockDataService;

To determine when a service injection is complete, you can use a setter and private variable. When the variable is private, the public setter is called when the service is injected. After the setter is called, you can safely make calls to the service. Because tile developers provide the setter, they can add code to the setter to notify that the service injection is complete.

import com.adobe.mosaic.samples.services.stockdata.IStockDataService; 
[Consume(catalog="stockmosaicservice_catalog" library="StockDataInterfaceLibrary")] 
private var _stockDataService:IStockDataService; 
public function set stockDataService(service:IStockDataService){ 
        //after  this setter  method is called by the Client Composite Framework, you can safely make calls to the service 
        _stockDataService = service; 
 
        //add your own code here to trigger an event or indicate the service has been initialized 
}

For an additional technique and complete example, see Add a service to a tile.

Context changes can only be persisted in a saved view. When the user saves a view, any tile, panel, or view context is saved to Experience Server as part of the view. Although you can define the default or named context in the application (AXML) file saved on the server, changes to the default or named context are not persisted.

You can set the initial value for a context in a catalog (CXML) file or application (AXML) file. All contexts defined in the catalog or the application are available at runtime. Context values that are defined in the application file override the ones in the catalog.

The following example illustrates how to initialize a context for a panel. This behavior also applies to views and tiles. The example catalog defines two attributes:

<view:PanelClassList> 
<view:PanelClass name="PanelExample"> 
    <ct:Context xmlns:ct="http://ns.adobe.com/Mosaic/CommonTypes/1.0/">  
        <ct:Data key="defaultExample" type="string" value="A1"/> 
        <ct:Data key="overrideExample" type="string" value="B1"/>  
    </ct:Context>   
    <view:Content> 
        <view:Panel name="PanelExample" label="Panel Context Override Example" allowContentDelete="true" tileChrome="full" width="100%" height="100%"> 
            <catalog:CatalogReference name="MyCat" uri="MyCat"/> 
            <view:Layout numColumns="2" paddingBottom="4" paddingRight="4" paddingTop="4" paddingLeft="4" name="SmartGridLayout"/> 
            <tile:TileReference catalog="MyCat" name="OpenCases" label="Open Cases" width="100%" height="50%" chrome="full"/> 
        </view:Panel> 
    </view:Content> 
</view:PanelClass> 
</view:PanelClassList>

An application references the panel and provides a different definition of the context. The application definition adds the attribute newAttributeExample and sets a new value for the attribute overrideExample.

<app:Shell > 
    <catalog:CatalogReference name="MyCat" uri="MyCat"/> 
    <view:PanelReference catalog="MyCat" name="PanelExample" > 
        <ct:Context xmlns:ct="http://ns.adobe.com/Mosaic/CommonTypes/1.0/">  
            <ct:Data key="newAttributeExample" type="string" value="C1"/> 
            <ct:Data key="overrideExample" type="string" value="B2"/>  
        </ct:Context>   
    </view:PanelReference> 
    </view:Panel> 
</app:Shell>

At runtime, Experience Server initializes the context attributes with the following values:

• defaultExample = A1

• overrideExample = B2

• newAttributeExample = C1

To define the context for inline panels, initialize the context in the view:Panel element.

<app:Shell > 
    <view:Panel name="PanelExample" label="Panel Context Override Example" allowContentDelete="true" tileChrome="full" width="100%" height="100%">  
        <ct:Context xmlns:ct="http://ns.adobe.com/Mosaic/CommonTypes/1.0/"> 
            <ct:Data key="defaultExample" type="string" value="A1"/> 
            <ct:Data key="newAttributeExample" type="string" value="C1"/> 
            <ct:Data key="overrideExample" type="string" value="B2"/> 
        </ct:Context>    
        <view:Layout numColumns="2" paddingBottom="4" paddingRight="4" paddingTop="4" paddingLeft="4" name="SmartGridLayout"/> 
        <tile:TileReference catalog=" MyCat" name="OpenCases" label="Open Cases" width="100%" height="50%" chrome="full"/> 
    </view:Panel> 
</app:Shell>

In the catalog file, you can define the context in the view:Panel element of view:PanelClass as well as in the view:PanelClass element itself. If you define the context in both of these catalog elements, the context from the view:PanelClass overrides the context from the view:Panel. However, the view:PanelReference context defined in the application still overrides any context defined in the catalog.

There are limitations on the types of data that composite application components can share across the Composite Application Framework environment.

For information on the restrictions that apply wherever composite application components share data, see the limitations for service interface libraries in Create a service.

1. Create a tile (see Create a Flex-based tile).

2. In Source mode, under the Metadata block, add a Script block that contains the [ContextBind] metadata tags. Include set and get functions that manage attributes of the context.

   For example, you can add functions that use integer, string, and date attributes:

   <fx:Metadata> 
       //This module is a Composite Application Framework Tile 
   [Tile] 
   </fx:Metadata> 
   <fx:Script> 
   <![CDATA[ 
   protected var _transID:int; 
   [Bindable] 
   [ContextBind(context="helloStatus",attribute="transID")] 
   public function get transid():int{ 
           return _transID; 
   } 
   public function set transid(i:int):void{ 
           _transID = i; 
   } 
   protected var _client:String; 
   [Bindable] 
   [ContextBind(context="helloStatus",attribute="clientName")] 
   public function get client():String{ 
           return _client; 
   } 
   public function set client(s:String):void{ 
           _client = s; 
   } 
   [Bindable] protected var _date:Date = new Date(); 
   [Bindable] 
   [ContextBind(context="helloStatus",attribute="localDate")] 
   public function get cbDate():Date{ 
           return _date; 
   } 
   public function set cbDate(d:Date):void{ 
           _date = d; 
           dateField.selectedDate = d; 
   } 
   private function dateChanged(date:Date):void { 
           cbDate = date; 
   } 
   ]]> 
   </fx:Script>

   In the Script block, the context attributes are bound to the functions themselves. You can reference the functions in the MXML file either in simple assignment statements or by binding attributes to user interface elements.

3. Add a layout block and controls that create user interface elements. Bind the context attributes to your controls.

   For example, bind the transid and client context attributes to the control properties to enable users to display or update the context attributes.

   <s:VGroup> 
       <s:NumericStepper id="value"  change="{transid = value.value}"  value="{transid}"/> 
       <s:TextInput id="clientValue" change="{client = clientValue.text}" text="{client}"/> 
       <mx:DateField id="dateField"  change="dateChanged(DateField(event.target).selectedDate)"/> 
       </s:VGroup>

   The get transid() and get client() functions are called using the bound variables in the NumericStepper and TextInput controls.

4. Save the tile.

5. Create a second tile. For example, a tile named Listener.mxml.

6. Add a Script block that contains the [ContextBind] metadata tags. For example, you can add the Script block that you added to the HelloWorld tile.

7. Add a layout block and controls to create a user interface.

   For example:

   <s:layout> 
       <s:BasicLayout/> 
   </s:layout> 
   <s:NumericStepper id="value" 
                   x="95" y="36" 
                   change="{transid = value.value}" 
                   maximum="100" minimum="0" 
                   value="{transid}"/> 
   <s:TextInput id="clientValue" 
               x="95" y="78" 
               change="{client = clientValue.text}" 
               text="{client}"/> 
   <s:Label x="24" y="10" 
           fontSize="18" 
           fontWeight="bold" 
           text="Listener on ContextBind"/> 
   <s:Label x="6" y="123" 
           width="341" height="29" 
           fontSize="14" 
           text="These update as ContextBind attributes are changed."/> 
   <s:Label x="6" y="154" 
           fontSize="14" 
           text="Making changes these will propogate out to other Listeners."/> 
   <s:Label x="179" y="40" 
           fontSize="14" 
           fontWeight="bold" 
           text="integer"/> 
   <s:Label x="231" y="88" 
           fontSize="14" 
           fontWeight="bold" 
           text="String"/> 
       <s:Label x="210" y="112" fontSize="14" fontWeight="bold" text="Date"/> 
   <mx:DateField id="dateField" 
           x="60" y="108"  
           change="dateChanged(DateField(event.target).selectedDate)"/>

You can use a context to create an HTML Tile that displays a dynamically generated URL. For example, the following catalog definition specifies a tile that displays financial information. Part of the URL is specified using an application context attribute:

<tile:Content contentType="text/html" uri=" http://finance.yahoo.com/lookup?s=${application.symbol}"/>

At runtime, the value of the symbol attribute replaces ${application.symbol}. User input in another tile in the application can set the value of the symbol attribute. Whenever the symbol attribute value changes, the HTML tile refreshes its content.

This mechanism allows you to use context to control any website that uses query parameters in its URL. However, a developer has less control over this type of tile because it does not communicate any changes back to the context.

For example, if you change the symbol in the example financial information tile, the HTML tile content is updated but the context is not. To avoid this limitation, write your own HTML tile and use the JavaScript code to keep the context synchronized with the HTML tile. The JavaScript code is provided with the Composite Application Framework SDK

The Concepts sample includes the Brokerage application, which illustrates how to use a context in an HTML tile. For information on samples, see Sample composite applications.

You add tiles that use a shared context to a composite application in the same way you add any other tile. The tiles communicate in an application without any additional application configuration.

For information on adding a tile to an application, see Create a composite application file (AXML file).

For information on testing your application, see Deploy a composite application.

To test the application, change the values in the integer, string, and date fields.

Changes you make in one tile are automatically reflected in the other tile.