Requirements

Prerequisite knowledge

Knowledge of Flex and ActionScript, basic knowledge of XMP Metadata

User level

All

Additional required Adobe products

  • At least one Creative Suite 5 (or later) product

Introduction

The XMP Namespace Designer feature of Extension Builder 1.5 was developed to speed up and simplify working with metadata, for both developers and users of the Creative Suite. This tutorial shows how to use the XMP Namespace Designer to formally specify a custom XMP Namespace, automatically generate a ready-to-use FileInfo panel, and automatically generate a tailor-made ActionScript library for working with that custom namespace.

Designing custom namespaces with XMP Namespace Designer

In this tutorial, we're going to define a custom namespace for artwork.

Use the values and selections shown in the images for this namespace.

To create a new custom namespace:

  1. Open Extension Builder and select XMP Namespace Designer Project from the New Project Wizard.
  2. Specify a name for the project, a prefix and URL for the custom namespace, and a package name for the generated library.
  1. Click Finish.
  2. In the XMP Namespace Designer, use the Add and Remove buttons to set the properties of the custom namespace, and edit them in the table. The container types and value types should be more or less self-explanatory; if you need more information, these are explained in the XMP Specification.

There are now two automatically generated projects in the project explorer, Artwork_lib and Artwork_panel, in addition to the original Artwork project.

  • Artwork_lib is the library project, which allows us to work with our new XMP namespace from ActionScript.
  • Artwork_panel is the FileInfo panel project, which allows us to access the properties of our custom namespace from within Creative Suite applications.

Adding validation rules

We can add validation rules to our custom namespace properties to make the generated resources even more useful.

To add validation rules:

  1. In the XMP Namespace Designer, click the icon in the validation column.
  2. In the Edit Validation Rules dialog box, click Add Rule.
  3. For the first rule, select the criteria must be, after, and 1990.
  4. Click Add Rule again.
  5. For the second rule, select the criteria must not be, after, and 2050.
  1. When you're finished adding rules, click Done.

If you select the Strict validation option, the generated library and FileInfo panel accept only valid values, and remove any preexisting invalid values. If you deselect this option, the library and FileInfo panel accept invalid values.

Specifying Validation Rules in Expert Mode

For extra flexibility, we can specify validation rules for a property using Expert Mode, which allows us to enter a regular expression for the property. For this example, we'll specify a rule for the Artist property.

To add a regular expression:

  1. In the XMP Namespace Designer, click the validation icon for the Artist property.
  2. In the Edit Validation Rules dialog box, select the Expert Mode option.
  3. Enter the regular expression ([A-Z][a-z]+ ?)+ in the text box. This means one or more words separated by a space, each at least two letters long, and each starting with a capital letter. For more information, see Regular expression syntax.
  1. When you've completed the rule, click Done.

Setting choices for Closed Choice and Open Choice value types

The Closed Choice and Open Choice value types define a property that can contain one of a predefined set of specific values:

  • A Closed Choice property can only have one of the predefined value choices.
  • For an Open Choice property, the predefined values offer suggested choices, but other values can also be chosen.

To set the choices for a property of this type:

  1. In the XMP Namespace Designer, click the validation icon for the Style property.
  2. Because this has the type Closed Choice, the Choices dialog opens. Click Add to enter a predefined value choice.
  3. Enter several choices, as shown.
  1. When you've finished adding choices, close the dialog.

When you save the changes, the generated projects Artwork_lib and Artwork_panel are updated with the new properties and validation rules.

XMP FileInfo panel

The generated Artwork_panel project is a standard XMP FileInfo panel project. See the XMP Developer Center for more information on customizing FileInfo panels.

Note: In this example, we're using Illustrator; you can use any of the listed CS programs.

To access the FileInfo panel:

  1. In the context menu for the Artwork_panel project, choose Run As > Adobe Illustrator Extension.
  2. Create a new document, choose File > File Info, and then select the Art tab. The FileInfo panel shows the appropriate controls for all of the properties of the art namespace.
  3. Fill out the fields of the Art tab as shown in the example.

The data must match the criteria specified earlier. If you enter invalid data for the Artist or Release properties, the FileInfo panel rejects them.

  1. When all data is entered, click OK.

The Raw Data tab of the FileInfo dialog box shows the properties of our custom namespace serialized into XML.

XMP Wrapper library

We can use the generated Artwork_lib project to easily access and manipulate the properties of our custom XMP namespace from within ActionScript.

In this section we're going to create an extension for Adobe Illustrator that uses our Artwork library.

To create a new extension project:

  1. In Extension Builder, select a new Creative Suite Extension Project from the new project wizard.
  2. Name the project something like ArtworkExtension, and select Adobe Illustrator as one of the target host applications.
  3. In the properties dialog box for the ArtworkExtension project, add the Artwork_lib project to the Flex Build Path.

Okay, now to write some code. There should be two files in the project src directory:

  • ArtworkExtension.mxml defines the UI for your extension; initially, it defines only one button.
  • ArtworkExtensionIllustrator.as contains the code that is executed when you click the button. Open this file to add some new code to the button-click handler.
  1. In the run() function, add this line to extract the XMP packet from the active Illustrator document:
var xmpPacket:String = app.activeDocument.XMPString;
  1. Create an object to represent our custom art namespace, in the context of the XMP packet:
var context:ArtXMPContext = new ArtXMPContext(xmpPacket);

Now we can read the properties of the namespace:

If we run this extension in Illustrator and click the button, we see this output in the console:

The title is Landscape The artist's name is Joe Bloggs The work of art is digital The release date was Tue Jan 13 2004
  1. There are more lines we can add to the run() function to work with the XMP properties. For instance, we can update the values of the properties as follows:
context.art.style = "Sketch"; context.art.artist = "j.c. anderson";
  1. If we add a couple of trace statements, we can check the actual values that are stored in the XMP itself:
trace("The style of the work is " + context.art.style); trace("The artist's name is " + context.art.artist);

In this example, we've entered an invalid name (according to the rules we specified earlier). Because the library validates the properties using those rules, we can see from the console output that the invalid artist name has been rejected, whereas the style has been set:

The style of the work is Sketch The artist's name is Joe Bloggs

Adding encryption

Let's imagine that the contents of this namespace are confidential. For the sake of security, they can't then be embedded in an Illustrator document if that document might be sent by email. The generated library provides a solution for this problem: encryption.

Using the context object's serializeToXML function, we can encrypt the contents of our art namespace:

app.activeDocument.XMPString = context.serializeToXML("password"); Note: calling serializeToXML() without an encryption key will simply cause the XMP to be serialized to XML without being encrypted.

The Raw Data tab of the FileInfo panel shows that the properties of the namespace have been encrypted:

To decrypt these properties, we simply pass in the decryption key to the constructor of the context object:

var context:ArtXMPContext = new ArtXMPContext(xmpPacket,"password");

This decrypts the properties in the new context object.

Binding properties

Using the [Bindable] and [xmp] tags in ActionScript, we can bind properties of our custom XMP Namespace to ActionScript variables, so that they're automatically kept in sync.

Here's a sample Flex application:

<?xml version="1.0" encoding="utf-8"?> <s:WindowedApplication xmlns:fx="http://ns.adobe.com/mxml/2009" xmlns:s="library://ns.adobe.com/flex/spark" xmlns:mx="library://ns.adobe.com/flex/mx" initialize="windowedapplication1_initializeHandler(event)"> <fx:Script> <![CDATA[ import com.example.artwork.ArtXMPContext; import mx.events.FlexEvent; [Bindable] [xmp(ns="art", property="price")] public var price:Number = 34; [Bindable] [xmp(ns="art", property="artist")] public var artist:String = "Bob Burns"; public function windowedapplication1_initializeHandler(event:FlexEvent):void { var context:ArtXMPContext = new ArtXMPContext; context.registerClassBindings(this); trace(context.art.price); trace(context.art.artist); trace(price); context.art.price = 200; trace(price); trace(artist); context.art.artist = "Billy Byrne"; trace(artist); } ]]> </fx:Script> <fx:Declarations> <!-- Place non-visual elements (e.g., services, value objects) here --> </fx:Declarations> </s:WindowedApplication>

The output to the console is:

34 Bob Burns 34 200 Bob Burns Billy Byrne

With minimal effort, we can keep ActionScript variables consistent with their counterpart properties in XMP.

Where to go from here

In this tutorial, we've seen that from a very simple on-screen namespace specification, we have generated some powerful resources for working with XMP. The generated library is strongly typed, enforces our validation rules, and gives us useful features such as encryption and bindings to ActionScript variables. Also, the generated FileInfo panel is ready to go straight away; it validates our properties' values, ensuring that invalid metadata never makes it into our XMP packet. These features make working with custom XMP Namespaces straightforward and accessible to many more users, so I would highly encourage you to give it a try!

For further information about XMP, you may wish to visit

http://www.adobe.com/devnet/xmp.html

If you have any questions or feedback on this new feature, please contact us via the Extension Builder Forum