Create Custom Metadata Panels in CS5 with XML

So you got all excited about metadata in CS5 and want to create your own namespace and properties and custom UI layout, etc. etc.  Well, that’s very cool because you can do most of that very simply if you know your way around hacking a bit of XML.

Before we start, you should understand the benefits and downsides in creating your own schema.  Benefits include

• optimization of UI into one panel for critical properties
• support for properties that are not available in the standard panels
• integration with other systems that use your custom properties

Downsides include:

• maintenance of namespaces and property versions over time
• distribution of panel if others need to view your custom properties
• possible learning curve frustration

Most folks want to create their own panel for 2 main reasons:

1. optimize the editing and viewing of metadata
2. add support for custom properties

The following provides an overview and description of the Generic panel SDK sample properties.xml file.  It shows how the XML structure and definition is related to the UI and interaction that is shown in the File Info dialog.

Get the SDK

The first step is to download the latest XMP FileInfo SDK 5.1 libraries from XMP Developer Center.  After unzipping the libraries you will find within the Tools folder another folder called Generic.  We will be using the components of that folder to create custom panels

Copy the Generic Folder

Copy the Generic to:

MAC OS:  /Library/Application/Support/Adobe/XMP/Custom File Info Panels/3.0/panels/


WINDOWS XP: C:\Program Files\Common Files\Adobe\XMP\Custom File Info Panels\3.0\panels\

WINDOWS VISTA: C:\Program Files (x86)\Common Files\Adobe\XMP\Custom File Info Panels\3.0\panels\


The above is the easiest place to add custom panels if you have admin privileges since it is the location for the existing set installed with CS5.

The user specific locations are:
MAC OS: /Users/<username>/Library/Application Support/Adobe/XMP/Custom File Info Panels/3.0/panels

WINDOWS XP: C:\Document and Settings\<username>\Application Data\Adobe\XMP\Custom File Info Panels\3.0\panels


WINDOWS 7/VISTA: C:\Users\<username>\AppData\Roaming\Adobe\XMP\Custom File Info Panels\3.0\panels
If you use the user specific locations you will need to add the above path to the Flash Global Security Settings Manager:

1. Click on the Edit Locations… drop down and select Add Location…
2. Paste in the path as above (replacing <username> with your specific data)
3. Check to see location is added in the Manager
4. Copy Generic folder to location
5. Load up a CS5 app and check the File Info Dialog to see if it has been added (be sure to scroll the dialog and the drop menus to see if it might be hidden)

Since the Panels are Flex/Flash based and are being run locally, the panel path needs to be recognized by the Flash player as OK to run.

Modify the Properties.xml File

The Properties.xml file is located in the Generic folder and defines the namespaces, properties and basic UI of the panel.  So get out your favorite text editor – I suggest TextWrangler for the Mac since it is free and highlights the text nicely making it easier to read.  Do NOT use Word or other word processing editors unless you know that you are saving the file as pure text and not RTF or doc format.  Now let’s look at the content of the file:

The area we want to mess with is within the <xmp_definitions> </xmp_definitions> tags, starting with:

<xmp_schema prefix=”custom” namespace=“http://my.custom.namespace/&#8221; label=“$$$/Custom/Schema/Label=Custom Properties” description=“$$$/Custom/Schema/Description=This example panel contains most of the options available for the ‘Generic Panel’.”>

<xmp_schema – defines the beginning of the schema definition

prefix= this defines a variable name for the namespace URL, like a short reference name to be used only within this panel

namespace= define that namespace that you want your properties to be defined within

label= defines the Title of the panel NOT the Tab name – that is defined in the manifest.xml file

$$$/Custom/Schema/Label= defines the localization property that is used to store the different language versions.  If you go into the Generic/loc/ folder and open the “Generic_de_DE.dat” file in the text editor, you will see how the localization property is mapped to the German value.  If you are not localizing the panel, you can remove this property and just define the value, for example: label=”My Custom Label”

description= defines the description for the panel that is shown when the user rolls over the Tab Name.

$$$/Custom/Schema/Description= as described above, this is used for localization purpose, you can choose to include or not depending on your internationalization needs.

Simple Properties

Simple properties like, text, data, numbers, true/false are defined in one line entries of the form:

<xmp_property name=”Text” category=”external” label=”Text Field:” type=”text”/>

If you noticed I removed the localization variables for simplicity.

<xmp_property – defines the element that will describe the property

name= defines the UI widget that will be used to display the property type.  Includes the following simple types:

• Text – used for properties that can only hold a single value, like Country or City or Name
• TextML – used for properties that hold a single value but can be verbose, like description
• Boolean – used for check box like options, on or off, like male or female, or review status: yes/no
• Date – used for entering a single date, the calendar widget is the UI
• Integer – used for entering numbers, works with the ui:format variable to define the units, like cm, in

category= defines whether the field is displayed for editing (external) or read only (internal).

label= defines what label description is shown in the UI before the entry/display field

type= defines the type of value that can be stored in the property, works with the property_name variable:

• text = contains textual data
• boolean = if the checkbox is selected, the value of “True” will be set for the property
• date = the date will be stored in the property as yyyy-mm-dd
• integer = only the numeric value will be stored in the property, not the prefixes or suffixes

UI Control Properties

• ui:height= defines the height of the input field, can be absolute “=15” or relative “=10%”
• ui:width= defines the width of the input field, can be absolute “=15” or relative “=10%”
• ui:format=defines the prefix “re: {0}” or suffix “{0} cm” that is appended to the view of the value.  The prefix or suffix content is NOT added to the value stored in the metadata
• ui:multiline= defined as “true” or “false”, works best when combined with an the appropriate property_name and type

The above UI variables can be included with any of the property definitions BUT may or may not work or make sense depending on the types of properties.  Remember that in the Generic panel, each property is provided with a single horizontal space that it occupies.  Customizations are restricted to the labels and entry field properties.

Simple Properties Choices

These definitions allow us to create drop down and multiple choice entries for the panel.

<xmp_property name=”ClosedChoice” category=”external” label=”Closed-Choice Input:” type=”closedchoice” element_type=”text”>

name = defines the UI widget that will be used to display the property type.  Also includes the following simple types:

• ClosedChoice – defines the UI widget for a closed list of values that the user can chose from.
• OpenChoice – defines the UI widget for a list of values the user can chose from or they can write their own in

type = defines the type of property that will store the values, works together with the name property

• closedchoice – works with ClosedChoice to limit the selection of variables
• openchoice – works with OpenChoice to provide selection and option to provide custom entry

element_type = defines variable type that is stored in the property, similar to type for simple properties

Once the property and widget is defined, the choices for the drop need to be enumerated.

<xmp_choice raw_value=”” label=”(select color)”/>

xmp_choice – defines the elements that will provide the choices, each choice will have it’s own entry.

raw_value = defines the value that is stored in the property, in the above case it is set to null if the user has not selected anything.  Here is where you define what value you want stored in the metadata.

label = defines what is shown in the UI, since this is the first xmp_choice definition it is the default view and provides instructions on selecting the values.

Arrays

Arrays are useful for defining properties that can contain multiple values, like keywords, or contributors.

<xmp_property name=”TextArray” category=”external” label=”Text Array Input:” type=”bag” element_type=”text”/>

type = defines the array type which can be:

• bag – meaning it is unstructured and a ‘bag’ of values
• seq – meaning it is sequential and their is value in the sequence of values

The default display separator for values is the “;” semicolon.  However, if you enter values with a “,” comma it will be converter to a semicolon.  There are ways to change this but are beyond the scope of this intro.

There are some localization definitions that I am not going into, maybe that will be another post if people are interested.  I hope this is a good start on how to understand what the Generic panel is about and how to begin to use it to create custom schemas.