Flash Article

Creating web photo galleries in ActionScript for use with Adobe digital imaging software

For many years, Adobe Photoshop and Photoshop Elements have offered users the ability to create web pages that show a collection of digital photos. With Photoshop Elements 5 and Photoshop Lightroom, Adobe introduces a new generation of Flash-based web galleries that deliver an engaging user experience and provide many styling and customization options.

Photoshop Elements and Lightroom ship with a single SWF file containing the gallery program, which users can customize extensively using the authoring interface in those programs. These programs produce XML files that the SWF parses to style the gallery and determine its content.

As a Flash programmer, you can create your own Flash gallery program as an alternative to the SWF that Adobe provides. You can build designs for your own use, or for paid or free distribution to other users of Adobe software, who in turn will be able to create galleries using your SWF just as easily as using the products' default SWF—as long as your design conforms to the new Adobe XML schema, called the Adobe Media Gallery.

Adobe has published the Adobe Media Gallery code as open source, so you can modify it or learn from it to create entirely new galleries. To help get you started, this article provides an overview of how the Adobe Media Gallery works with the XML files. After you read this article, you should refer to the Adobe Media Gallery XML specification and the other resources listed at the end for more details.

First we should comment on our particular terminology:

• The Adobe Media Gallery architecture supports any type of media that Flash Player can render as an external asset. We use the term photos rather than media in this article because that is the predominant use, but the gallery can also be used for Flash video (FLV format) as well.
• We use the term gallery program to refer to the ActionScript code and the resulting SWF it generates. A gallery instance is the combination of this SWF and a set of XML and image files that creates a particular gallery.

Requirements

To complete this tutorial you will need to install the following software and files:

Flash Professional 8

• Try
• Buy

You also need one of the following two programs that can author instances of the Adobe Media Gallery:

Photoshop Elements 5 (Windows)

• Try
• Buy

Photoshop Lightroom

• Try
• Buy

Current stable open source project release:

• Download the files

The sample files are located in the templates\sample_gallery directory of the source tree.

Prerequisite knowledge

To modify the existing Adobe Media Gallery source code, you'll need to be able to find your way around a fairly large, object-oriented ActionScript program and write ActionScript to implement any changes or new features that you want. If you want to build your own gallery from scratch, yet retain compatibility with the authoring application in Adobe's digital imaging products, you should be comfortable with creating complex ActionScript programs and using XML.

How the Adobe Media Gallery works

Adobe's digital imaging applications do not, at this point, actually create Flash gallery programs. Instead, they come with some very capable and flexible gallery programs, already compiled into SWFs, whose behavior is determined by a set of XML files.

Standard SWF customized via XML files

Photoshop Elements and Lightroom include Flash gallery authoring workflows that make it easy for users to select photos, choose a style, and create a Flash gallery. What each program is really creating is a set of XML files which—when combined with the standard Adobe Media Gallery SWF that's installed as part of the application—ultimately render the gallery.

Although there are several XML files involved, two provide all the customization information for any published gallery: group.xml, which lists the assets, and style.xml, which controls the presentation options. When the Flash gallery runs, it parses these two files and they determine what gets shown and how it is styled.

Creating your own designs

If you want to create a new Flash gallery program that Photoshop Elements and Lightroom users can easily use to create their own galleries, your program needs to follow the architecture described in this article. Theoretically, you don't have to use any ActionScript code to do this; you can write the gallery however you want. However, your gallery program does have to parse the two XML files that either Photoshop Elements or Lightroom produces. You also must create a third XML file that provides these applications with information about your gallery.

Rather than writing all this code from scratch, you can get the ActionScript code from http://stlab.adobe.com/amg/ and either modify it or borrow parts of it. This is much easier than writing your own parser and making sure it complies with all the requirements of the Adobe Media Gallery specification.

Using the group.xml file

The group.xml file tells the SWF where to find the photos that make up the gallery. It points to versions (called renditions) of the media assets at various resolutions, plus metadata for each item. This is how the photo-selection workflow in Photoshop Elements or Lightroom communicates to the SWF which set of photos the user selected to create the gallery in the first place.

The group.xml file has a gallery-wide metadata section that you can use to specify the name of the gallery, the author, and so forth. But the heart of the file is the section that lists the media items:

<media>
   <item>
      <title><This is the caption></title>
      <description><This is the optional long version of the caption></description>
      <metadata><EXIF or other metadata></metadata>
      <photographer><Photographer's name></photographer>
      <copyright><Copyright 2006 Joe Photographer></copyright>
      <imageId image="1234" dbtype="pse5" dbname="mycatalog"/>
      <mediaType category="image" format="jpeg"/>
      <location latitude="37.8123" longitude="-122.5432" accuracy="16"/>
      <renditions>
         <rendition size="thumb" src="images/xyz/large/sample1.jpg" width="160" height="120" />
         <rendition size="small" src="images/xyz/small/sample1.jpg" width="640" height="480" />
         <rendition size="medium" src="images/xyz/medium/sample1.jpg" width="880" height="660" />
         <rendition size="large" src="images/xyz/large/sample1.jpg" width="1024" height="768" />
      </renditions>
   </item>
      ... other items ...
</media>

In this example, there's only one media item shown, with four renditions (a thumbnail and three sizes of larger images), title, description, and other metadata. The item element is repeated for each photo.

You don't have much control over what's in this file; it reflects the media the user selected and the metadata associated with that media. You can, however, choose the number and size of the renditions created, as described later in the section on the gallerymaker.xml file. You are also free to ignore all the elements other than the renditions but users may be unhappy with your design if you don't, at a minimum, support the title element.

Using the style.xml file

The style.xml file configures many aspects of the presentation, including the thumbnail arrangement, color scheme, background image, and so forth. As the name suggests, it is all about style; the substance of the gallery is controlled by the group.xml file.

Each style.xml file needs a styleInfo element:

<styleInfo>
   <templateId>company.designer.template</templateId> 
   <thumbnailPath src="gallerythumb.jpg"/>
   <previewPath src="largepreview.jpg"/> 
   <styleName>Blue Marble</styleName> 
   <styleDescription>Marbled blue background</styleDescription> 
   <galleryMaker name="Adobe Flash Gallery" version="1.23"/>
   [XMP metadata block goes here]
</styleInfo>

The styleInfo element is defined by the specification, and there are no options for changing it for a particular design—beyond, of course, providing the appropriate contents for each element.

The appearance element, on the other hand, is defined by a combination of whatever controls you—as the author of the Flash gallery program—want to provide, and the settings that the user chooses for each control. The user might choose settings manually, or implicitly by choosing a template.

Here's an example of a very simple appearance element of a style.xml file:

<appearance xmlns="http://ns.adobe.com/AMG/FlashGallery/style/1.0/">
   <slideTransitions slideDuration="2" transition="fade"/>
   <background color="222222"/>
   <title color="ae9f88"/>
</appearance>

In this example, the only styling controls are the duration of each slide, type of transition, background color, and title color.

Note that none of these elements is prescribed by the specification. As the author of a new Flash gallery program, you can decide what to name all of these elements and what attributes each has. The Adobe Media Gallery program has dozens of appearance elements, but your design can be much simpler (or more complex).

As the author of a Flash gallery program, you communicate what these options are, and how to present them to the user, in a third XML file that we haven't discussed yet: gallerymaker.xml. That file is the topic of the next section.

Styling a gallery with the gallerymaker.xml file

As you've just seen, the appearance section of the style.xml file tells the SWF how to style the gallery presentation. This file and the group.xml file are the only two XML files with which your Flash gallery program must interact.

There is a third XML file, however, that is just as important but is used only by the authoring application (Photoshop Elements or Lightroom), not by the gallery program itself: gallerymaker.xml.

The gallerymaker.xml file provides all the information needed by the authoring application to create the gallery. It tells the authoring application what renditions to produce, what customization controls to display, and how to create the style.xml file.

This file must be provided by the creator of any new gallery program. It does not need to be included with the published version of the gallery, but it could be included there to enable later editing of the gallery without requiring access to the authoring program that originally created it.

The gallerymaker.xml file has four sections:

• General information about the gallery program, such as its name, description, and author

  Note: This does not refer to a specific instance of the gallery, but to the design itself.

• Number and sizes of renditions it expects
• Metadata supported for each image
• User interface controls presented to gallery authors for styling the gallery and entering metadata, such as the gallery title

You can find details on the first three sections in the Adobe Media Gallery XML Specification. This article focuses on the last item: the controls.

The controls section of the gallerymaker.xml file tells the authoring program (such as Photoshop Elements or Lightroom) what parameters the user can control, how to present the control (menu, slider, color picker, etc.), and the names that identify the controls in the Style XML file. It also lists gallery-wide metadata fields, such as title and description of the gallery, for which the user can enter text when creating a gallery.

This section of the gallerymaker.xml file is wrapped in an element called mx:application. This name comes from the XML language that we use in this section: a subset of the MXML language that is part of Adobe Flex. MXML is designed to enable you to specify user interface elements and other web page components declaratively (that is, with XML rather than executable code). It is a perfect fit for your needs here because you want to enable the gallery programmer to tell the authoring application what controls to present to the user.

Specifying style and metadata controls

The mx:application section of the gallerymaker.xml file is divided into three subsections:

• Models define the parameters that users can view and modify. The model gives each parameter an ID, which the authoring application uses to name the element in the style.xml file.
• Views specify the UI elements that the authoring application displays, such as sliders, text-entry boxes, and color pickers. This section also includes layout elements, which specify how controls are laid out in the dialog box within the authoring application.
• Bindings make connections between model and view elements. Every view should have a model, but models do not need to have views. (A model without a view simply specifies a fixed value for a parameter.)

Inside the model

There are two mx:Model sections: one for appearance (style) controls and the other for gallery-wide metadata fields:

<mx:Model id="appearance">
   <slideTransitions>
      <slideDuration />
      <transition />
   <slideTransitions />
   <background>
      <color />
   </background>
   <title>
      <color />
   </title>
</mx:Model>

<mx:Model id="metadata">
   <galleryTitle />
   <galleryDescription />
</mx:Model>

Note that only the existence—not the content—of the mx:model elements is described by the specifications; the previous listing is just one example. As the gallery programmer, you choose the model elements that you want to use to style your gallery.

How model elements result in style.xml and group.xml elements

Each element in the <mx:model id= "appearance"> section creates one element in the style.xml file, with each child element creating an attribute. For example, the code in the previous section yields a slideTransitions element with slide duration and transition attributes, plus background and title elements that each have a color attribute. (Refer back to the section on the style.xml file to see an example of the XML that the authoring application produces.)

The metadata elements work in a slightly different way. Each element in the <mx:model id= "metadata"> section creates one element in the group.xml file, with each child element creating an element (not an attribute) in the element in the group.xml file. For example, the metadata element in the example above produces this entry in the group.xml file's custom element:

<galleryTitle>User-entered gallery title</galleryTitle>
<galleryDescription>User-entered gallery description</galleryDescription>

Defining views

Views are where you describe the UI that the authoring application presents the user who creates a gallery. You could have an empty view section, in which case there would be no styling options, or you could have hundreds of settings. You can also provide multiple gallerymaker.xml files for a single gallery program; for example, you might want to offer a simple one for typical users, which exposes few controls, and a more complex one for advanced users.

Because the views use a subset of MXML, you can use the Adobe Flex Builder development tool to create this code by dragging and dropping UI elements. This can be tricky, though, because the AMG XML specification supports only a small subset of MXML, and it is hard to restrain Flex Builder to this subset.

Here's a View element that creates UI controls for the model elements we described in previous section:

<mx:View>
   <mx:Label text="Slide Transitions"/>
   <mx:VBox>
      <mx:HBox>
         <mx:Label text="Slide Duration" />
         <mx:HSlider id="durationView" minimum="1" maximum="10"/>
      </mx:HBox>
      <mx:HBox>
         <mx:Label text="Transition Style" />
         <mx:ComboBox id="transitionView">
            <mx:dataProvider>
               <mx:Array>
                  <mx:Object label="Fade" data="fade"/>
                  <mx:Object label="Cut" data="cut"/>
                  <mx:Object label="Iris" data="iris"/>
               </mx:Array>
            </mx:dataProvider>
         </mx:ComboBox>
      </mx:HBox>
      <mx:HBox>
         <mx:Label text="Background Color" />
         <mx:ColorPicker id="backgroundColorView"/>
      </mx:HBox>
      <mx:HBox>
         <mx:Label text="Title Color" />
         <mx:ColorPicker id="titleColorView"/>
      </mx:HBox>
   </mx:VBox>
</mx:View>

Figure 1 shows the general look of the UI that this code generates in the authoring application.

Figure 1. UI generated by the View element

The exact appearance depends on the application but you can control the arrangement (within limits) using HBox and VBox elements. You can also add dividing lines, control alignment, and add application-specific visual enhancements in some cases (such as for Lightroom).

Linking views and models

There's one more critical part of the mx:application section of the gallerymaker.xml file: the bindings. Note that the IDs used in your models must be different than those in your views (since all IDs must be unique). The bindings tie the two together:

<mx:Binding source="durationView.value" destination="appearance.slideTransitions.slideDuration"/>
<mx:Binding source=" appearance.slideTransitions.slideDuration" destination="durationView.value"/>

<mx:Binding source="transitionView.selectedData" destination="appearance.slideTransitions.transition"/>
<mx:Binding source=" appearance.slideTransitions.transition" destination=" transitionView.selectedData"/>

<mx:Binding source="backgroundColorView.selectedColor" destination="appearance.background.color"/>
<mx:Binding source="appearance.background.color" destination="backgroundColorView.selectedColor"/>

<mx:Binding source="titleColorView.selectedColor" destination="appearance.title.color"/>
<mx:Binding source="appearance.title.color" destination="titleColorView.selectedColor"/>

This code ties each of the appearance models in the examples on the previous sections to a given view. Because the bindings are repeated for each direction, changes in the model affect the view and changes in the view affect the model. (Bindings are also required for the metadata fields, but are not shown here.)

In this example, we provided a one-to-one relationship between models and views. In more complex designs, it is often useful to tie multiple model elements to a single view. For example, there could be model elements for title color, subtitle color, and caption color, and all could be bound to a single "text color" view element (and UI control).

Adding your gallery to Photoshop Elements

Once you've created a new SWF and gallerymaker.xml file, how do users install it in their application? This section explains how to do so for Photoshop Elements; the process for Lightroom will be the subject of a future article.

After you have Photoshop Elements 5 installed on a Windows system, navigate to the following folder:

C:\Documents and Settings\All Users\Application Data\Adobe\Photoshop Elements\5.0\Flash Galleries\Web Gallery

Note: Application Data is a hidden folder, so you won't see it in Windows Explorer unless you enable display of hidden folders in Windows.

Inside the Web Gallery folder you'll find a set of subfolders with names like 01default_st. You need to add your own folder alongside these. The name doesn't matter, except that the list of choices the user sees in Photoshop Elements will be sorted according to these names. (That's why the existing folder names start with numbers—to force this ordering.) Take a look at the contents of one of these folders to see what goes in them, and mimic that structure.

After you create your own folder, place within it your gallerymaker.xml file, an index.html wrapper file (you can use an index.html file from any existing folder), a thumbnail image (approximately 115 x 63 pixels) to represent your gallery design, and a folder called resources.

Inside the resources folder, place your SWF (name it gallery.swf) and create folders called groups and styles. You can leave the groups folder empty because the group.xml file is created by the authoring application. However, you need to provide at least one default style.xml file, which you place in the styles folder, along with a thumbnail image to represent it.

Now when the Photoshop Elements user chooses Create > Photo Galleries from the main menu, they'll see a wizard that presents a series of template and style options (see Figure 2).

Figure 2. Photoshop Elements Photo Galleries wizard

If you name your folder something like 001mygallery.swf, it will appear at the beginning of the list. When the user clicks your template in the upper list, the list of styles (the lower list) will show any styles you've provided in the styles folder. Then, when the user clicks Next, Photoshop Elements creates the group.xml file and displays the customization panel of the wizard (see Figure 3).

Figure 3. Customizing a gallery in the wizard

The controls in the left panel are all determined by the gallerymaker.xml file; this is the part of the customization wizard you control. The preview on the right shows what the gallery looks like. If you start from Adobe's open-source ActionScript gallery code, you may want to support the live preview interface, which updates the preview immediately whenever the user changes a control on the left. If you don't, then the user has to click the Refresh button to see the changes.

When the user is done, he or she just clicks the Share button and Photoshop Elements creates a style.xml file that reflects all the customizations that the user made in the left panel.

Where to go from here

The Adobe Media Gallery specification offers a new opportunity for Flash developers to create digital photo and video galleries that users of applications such as Photoshop Elements and Lightroom can make from within the application. You can start from Adobe's existing ActionScript gallery code, which is available as open source, or build your own from scratch as long as it works with XML files that comply with the specification.

Check out the following resources to help you get started:

• Adobe Open Source site: This is the central location containing links to the source code plus a wiki, forum (on SourceForge), and issue tracker for people working with the code.
• SourceForge site: This site hosts the current stable open source project files.
• Adobe Media Gallery XML specification: Located in the documentation subdirectory of the open source project directory on SourceForge, this is where you'll find the central reference for understanding the requirements for a gallery program to be compatible with Adobe's authoring applications. It goes into much more detail than this article.
• Adobe Media Gallery tools: Located in the tools subdirectory of the open source project directory on SourceForge, this is where we'll be publishing XML validators and other resources.
• Overview of MXML: The Macromedia Flex Markup Language: This overview article by Flex evangelist Christophe Coenraets provides useful background information for understanding MXML, which is used to describe the gallery customization controls.

About the authors