Samples, news and updates from the Adobe Digital Enterprise Platform Engineering team

Posts in Category "Tech Articles"

1 Introduction

Even though the ADEP tooling doesn’t officially support building CAF tiles that use Flex SDKs earlier than 4.5.0, it is nevertheless possible to do so while taking advantage of many of the features it provides, if you do a little of the work yourself. The following features of the tooling can still be used with 3.6 Tiles, once they have been properly set up:

Some automatic catalog entry generation

Catalog and Application deployment

The things you give up include:

Automatic gxml generation for library projects

Code assist in library projects

Tile creation wizard

2 General ideas

The main thing you need to do to get started is to undo some of the work that the File->New->ADEP project wizard does for you. You give up all the features of tooling if you don’t ADEP-enable a project, so it’s better to go through the wizard as though creating a 4.5-based project, and then change the settings to make it a 3.6-based project instead. We’ll cover the two main types of tile projects, Module tiles and UIComponent tiles. There are other ways to get the tooling to help, such as telling a 3.6-based non-ADEP project to generate its output into a 4.5-based, ADEP-enabled project, but I won’t cover them here.

3 Creating a 3.6 Module tile project

Let’s start with Module tiles, since they’re the simplest, and are the recommended approach. Throughout this tutorial, we’ll use the default catalog, but all the steps work equally well with any catalog.

Begin by launching FlashBuilder, and ensure that you have all the normal ADEP-related parts set up (AEP_SDKS pointed at the right place, for instance). Then create a new ADEP-project, by choosing File->New Flex Project for ADEP Experience Services. Configure it as you would normally configure a 4.5 tile, but on the first panel of the wizard, choose the 3.6 Flex SDK instead. Accept all the default swc libraries that are added to the build path, even though they’re for 4.5, you’ll remove them after the project is set up. Once your project is ready, open the project build path pane, and remove all the library entries that mention “ux”, “riacore” and “dataservices”. Unfortunately, one of the swc directories just removed has a couple of swcs you still need in addition to many you don’t, so choose “Add SWC…” and enter “${AEP_SDKS}/riaservices/riacore/10.0.0.0/flex/security_api.swc”, and again for security_domain_library.swc. Then, edit the remaining entries that mention 4.5 and point them at 3.6 instead. Your build path should now look like this:

Finally, in the Flex Compiler pane, remove the additional compiler argument “-includes=mx.managers.systemClasses.MarshallingSupport”. Your project is now mostly “3.6-ready”, and if you’re in a hurry, you can skip the next step, though in a production environment you’ll need to come back and do it.

The wizard creates a sequence of RSL failover entries that ensure that your application, when it loads Flex SDK swz and swf files, gets them first from the server that served up the application. However, the URLs the wizard uses are for the 4.5 SDK, not the 3.6 one. The wizard will have set the default framework linkage for your project to “Use SDK default”, which is most likely RSL, so the RSL failover paths do need to be edited. Go to the Flex Build Path pane for the project, and open the list of the Flex 3.6 SDK components. The list should include playerglobal.swc, framework.swc, etc. The ones that are available on the CRX server need to have their entries modified. These are:

framework.swc

datavisualization.swc

rpc.swc

Each one needs to have the following failover pattern (replacing “framework” with “datavisualization” and “rpc”):

Next, create a new MXML module in that project. The File->New->Composite Application Tile wizard expects to with with a 4.5 project, and will refuse to create a tile in a 3.6 project, so you’ll have to create the module with the File->New MXML Module dialog instead. Then add the Tile metadata to your module, so it looks something like this:

Your 3.6-based module tile is now ready for use. You can right-click on the application file and choose Composite Application Framework->Deploy Composite Application, and then navigate to its URL in your browser.

4 Creating a 3.6 UIComponent tile

Follow these steps to create a new Composite Application tile or tiles from a Flex Library project, or to augment an existing Flex Library project so parts of it work as tiles and can be included in a Composite Application.

4.1 Creating the UIComponent project and tile

If you already have a Flex Library project that has a component or components in it that you want to expose as Tiles, skip this step and proceed to the next one, where you’ll modify the existing project to make an existing component into a Tile.

Otherwise, begin by creating a new Flex Library project, File->New->Flex Library project, making sure to choose Flex SDK 3.6. Then create a new component in that project, with File->New->MXML Component. For this example, base your component on mx:Button, and add a label to it so we will recognize it when we see it:

So far, there is nothing special about this component. In the next steps, we’ll make it into a Composite Application tile.

4.2 Modifying an existing Library project to make it into a Tile

There are three primary steps to take in order to convert an existing Flex component into a tile. The first is to mark the component as a tile, and then provide it with the necessary libraries to allow it to communicate with the rest of the Composite Application Framework. Second, since a Library project normally only produces a SWC file and CAF needs a SWF to load, we have to create a wrapper project that includes the SWC. Normally, this step is handled by the ADEP tooling, but it’s not supported for 3.6-based projects, so we have to do this step manually. Finally, we have to create a gxml file so that CCF can load the tile.

4.2.1 Prepare the Library Project

Begin by adding the needed library directories to the project. They are:

${AEP_SDKS}/riaservices/mosaic/10.0.0.0/flex3.6.0/frameworks/libs

${AEP_SDKS}/riaservices/gravity/10.0.0.0/flex/3.6.0/libs

${AEP_SDKS}/riaservices/gravity/10.0.0.0/flex/core/libs

Then switch the framework linkage to RSL, which will reduce the size of the tile, and add the following to the Flex Compiler options: -locale en_US -keep-as3-metadata+=Tile,Application,ContextBind,SecurityManager

Finally, update the RSL failovers as described in the earlier section.

You are now ready to add CAF-specific constructs to the project, specifically the [Tile] annotation. If you are using the extended button from the previous step, your new source code would look like this:

4.2.2 Create the wrapper project

Create a new ADEP-enabled project, with File->New->Flex Project for ADEP-Experience services, make sure it’s set to use Flex SDK 3.6, and complete the dialog as you did for the section “Creating a 3.6 Module tile project”. Also as in the earlier section, remove the unused libraries, and update the necessary ones from 4.5 to 3.6. Then make this wrapper project depend on the Library project.

Adjust the RSL failovers, switch the project to RSL linkage, and add the compiler options you added earlier to the Library project. Then create a new MXML Module called, for example, “ComponentWrapper.mxml”. This file will be very simple, it serves only to wrap the component in a particular way to enable it to be loaded by CAF:

Finally, we have to create the GXML file. This will go in the “mosaic” folder, which is created automatically when you create an ADEP-enabled project. The file should be named “MyButton-com-acme.gxml”, if MyButton is in the com.acme package, or just “MyButton.gxml” if it’s in the default package. The content should be as below:

It may be instructive to compare this gxml file with one that the Tooling generates automatically for a Library component tile built with SDK 4.5. You may see several differences, but only some of them are significant. Many of the “id” attributes serve only as identifiers within the gxml, and need only match each other where they appear, but their actual names are not significant. However, there are a couple of instances where the values of strings are important:

The bundle element’s location attribute must name the swf built by the project.

The constructorArg value attribute in the “Creator” bean and the “Purpose” bean must have the fully qualified class name of the wrapped component that you marked as a Tile.

Even though this tile is ADEP-enabled, an entry in the catalog will not be generated, because nothing directly inside the project was marked with the [Tile] annotation. Therefore, we need to add an entry manually to the catalog. In this case, it will refer to the gxml file we created, rather than the swf. The entry should look like this:

Our recent release of the Adobe Digital Enterprise Platform contains not only software but a library of documentation that has been authored by the Adobe Learning team with direct input from all our engineers around the world.

One of our most important documents is a very short introduction that you read first, called “Adobe Digital Enterprise Platform Overview“. This was a very tricky document to write because there is a lot to say about ADEP, from its architecture & guiding principles to a precise description of each of the components and frameworks offered to developers. But how do you do that with accuracy while at the same time being extremely brief ..?

Well I think we managed it. The Overview gives enough information for anyone to quickly understand (in plain simple English) what ADEP is all about, starting with a simple graphic and then describing all the basic features and capabilities:

In particular, I suggest you make a bee line for the document called “Developing for ADEP Experience Services“. This is intended to give you as a developer a total gloves-off crash course on the new Experience Server, with links to more detailed information too. You can check that one out here:

The core of our new Adobe Digital Enterprise Platform comes in a very small box (you could probably email the entire server to yourself as an attachment!) but we managed to squeeze in an important element. When you launch the Quick Start there is a rather unremarkable little link in the top right hand corner called, “Getting Started“. Click it and we bring you to a whole set of running applications with developer tutorials and sample code.

You don’t need to wade through lots of documentation when trying to build your first application. Just fire up the samples, see applications running right away, download the source code, follow the tutorials and you’ll be an ADEP expert in no time!

Here is what you see when you select “Getting Started”:

(Click to enlarge)

These links are split into two groups. The first is a set of “Spotlights”. They show you some basics of what the platform can do to help you build great web applications and they link to this blog for more details. The second group is a more in-depth set of sample applications that use multiple frameworks together; such as Composite Applications, Data Services, CRX and Task Management. They run out of box and come with tutorials that show you how to recreate the application yourself with sample code.

Furthermore if you need even more samples and code we have a handy link in Package Share that will download lots of deep dive (and running!) applications for Data Services and the Composite Application Framework. Once you download the Package it automatically adds more links to the page above.

Our objective is to help you learn our platform in a way that is “by developers for developers“. Our core engineering team (in between fixing bugs!) produces all of this content and the articles on this blog. We can’t wait to see what you build with the Adobe Digital Enterprise Platform.

Web and Mobile applications built using the Adobe Digital Enterprise Platform permit modular development of a user interface, such that you can compose an application out of multiple individual components (could be HTML or Flash based).

The “Composite Application Framework” lets you assemble your application by hosting its constituent parts as content managed in the CRX Repository. Then you can modify layout properties and change your application administratively (by editing content in the Repository after your application) has been developed and deployed. No need to rebuild and redeploy the whole application.

The individual components of your application are called, “Tiles“. In the example below one Tile is a JSP based HTML application built with Apache Sling. The other Tile is a classic Flex application that shows a data grid. Both Tiles may be developed and maintained separately but brought together by the framework to form a “Composite Web Application”.

The Composite Application Framework also provides communication of data and objects between each Tile via a “Shared Global Application Content”. In the example below a “watch” attribute (any string) may be configured in the Flex Tile, then a value for that attribute gets set by the HTML Tile.

(or click below to see a screen shot)

Now let’s look at the code behind each Tile (HTML and Flex)

html.jsp

Here is the JSP used to display the HTML tile able to communicate data with Flex.

Note the following aspects:

A java script utility mosaicBridge.js is imported in order to obtain the mosaicApp.getContext() function which you can use to get/set attributes on the Global Contecxt. This java script needs to be part of your web application.

The buttons in the HTML simply call function in the script block that wrap use of the mosaicBridge.js utility.

(Click to enlarge)

Flex Application Tile

Here is the MXML code used for the Flex Tile.

Note the following aspects:

The data grid relies on a dataProvider which is a simple array collection

There is a “mosaicApp” object of type IApplication which is injected by the Composite Application Framework allowing your flex application to access the Global Shared Context. This Tile adds itself as a “watcher” for an attribute with a given name.

Now any time there is a change to a property in the shared global context, the Tile gets an onChange event for the property being watched and simply adds it to the dataProvider used for the grid.

This example shows how a simple Web UI is built using Apache Sling such that text content in the page is dynamic in that it can change easily without the need to re-author any HTML.

The example uses a JSP to render some HTML with a very simple style sheet. Let’s say this is the web UI we we want to arrive at looks like this:

Two things to notice first:

The URL is /content/samples/testdrive/dynamichtml.html. That URL structure (especially the /content part) is important. It is literally the same as a node path in your CRX content repository

The web page is showing a title and some body text that it claims to be “dynamic”. What does that mean? Well, as we shall see, these values are not literally coded in the HTML but come from “JCR Properties” of the node in the CRX content repository sitting at the end of the node path.

Traditional JEE web developers would use a WAR file in which all of the assets (JSPs, scripts etc.) are held in a folder within the ZIP structure of the WAR”. This is possible to mimic in the CRX Repository but it is not the best practice when using Sling.

Let’s start by looking at the JSP that renders this page:

(Click to Enlarge)

Notice the HTML in the JSP is using two variables “currentNodeTilte” and “currentNodeBody“. These variables in turn come from the currentNode binding which gives you access to the JCR node where the .html request was made. Now let’s consider where the JSP is stored and how it is referenced.

First we start by defining a content node (under /content) where requests will be made for a “.html” rendition:

(Click to Enlarge)

This is a simple content node under /content/samples/testdrive/dynamichtml with some text properties (including our title and body). Notice in particular the property called “sling:resourceType“. That property is used to reference the location of the JSP.

The JSP is placed under the /apps folder and its location is referenced by the the resourceType in your content node. This approach permits some useful

(Click to Enlarge)

There are some advatages to this approach:

Anonymous end users don’t literally need read access to the JSP, They just talk to the content node and ask it for “.html“. It is then the Sling framework on the server that executes the JSP and returns the requested “.html” rendition of the content node. That’s why, in this case, we have called it “html.jsp“.

You can re-use this JSP as the base web application for requests to other URLs. All you need is another content node that uses the same sling:resourceType and sets its own properties for the dynamic text.

Although the JSP is under /apps that reference to “currentNode” still binds to the node under /content where the HTML request was made. Therefore the JSP gets to substitute text in the HTML based on the “title” and “body” properties of the actual content node.

In addition within the JSP you will see that it its HTML references a style sheet. However style sheets are not part of the base web application. The style sheet belongs under /etc/clientlibs. Then the JSP simply references it under it literal path in this case, /etc/clientlibs/aep/samples/testdrive/dynamichtml/style.css.

(Click to Enlarge)

So in summary to build our simple web UI correctly with Apache Sling we needed to:

Write a JSP called “html.jsp” and place it under a location in the /apps folder.

Create a node for the web UI whose folder hierarchy matches the intended URL. Then set the sling:resourceType property of the node to point to the location of your html.jsp in the /apps folder. Therefore when anyone requests a “.html” rendition for that node (called dynamichtml) , Sling will know how to do it.

Within your JSP implementation refer to the style sheet .css file from a folder location under /etc/clientlibs.