require('uxp').xmp.XMPMeta

XMPMeta This class provides the core services of the XMP Toolkit. The functions provide the ability to create and query metadata properties from an XMP namespace. The class also provides static functions that allow you to create and query namespaces and aliases.

There is one static property on the class that provides XMP version information; there are no JavaScript properties in the instance. The object encapsulates a set of metadata properties, which you access through the object functions.

The generic functions getProperty(), setProperty(), and deleteProperty() allow you to manipulate alltypes of properties, when used with appropriately composed path expressions. For convenience, the object also provides more specific functions for use with specific types of properties, such as arrays.

Since: v7.2.0

XMPMeta(packet, buffer)

To create an XMPMeta object, use the new operator. The constructor accepts an RDF/XML serialized metadata packet as a string, or as an array of numbers that contain only byte values. It returns the new object. If no argument is supplied, the new object is empty; you can use the object’s functions to add namespaces and properties.

Example

// Create an XMPMeta object using property based APIs

let { XMPMeta, XMPConst } = require("uxp").xmp;
let meta = new XMPMeta();
meta.setProperty(XMPConst.NS_XMP, "Name", "vkumarg");
let prop = meta.getProperty(XMPConst.NS_XMP, "Name");
console.log(prop.namespace);
console.log(prop.options);
console.log(prop.path);
// checking for the property existence and deleting it
if(meta.doesPropertyExist(XMPConst.NS_XMP, "Name")) {
     meta.deleteProperty(XMPConst.NS_XMP, "Name");
}

if(!meta.doesPropertyExist(XMPConst.NS_XMP, "Name")) {
     console.log("Property doesn't exist");
} else {
     console.log("Property exists");
}

Example

// Create an XMPMeta object using struct based APIs

let { XMPDateTime, XMPMeta, XMPConst } = require("uxp").xmp;
let meta = new XMPMeta();

let jsDate = new Date("2007-04-10T17:54:50+01:00");
let xmpDate = new XMPDateTime(jsDate);
meta.setProperty(XMPConst.NS_XMP, "CreateDate", xmpDate, XMPConst.XMPDATE);
meta.doesPropertyExist(XMPConst.NS_XMP, "CreateDate");
let prop = meta.getProperty(XMPConst.NS_XMP, "CreateDate", XMPConst.XMPDATE);
meta.deleteProperty(XMPConst.NS_XMP, "CreateDate");

meta.setStructField(XMPConst.NS_XML, "structNameSample", XMPConst.NS_XMP, "sampleFieldName", "sampleFieldValue");
if (meta.doesStructFieldExist(XMPConst.NS_XML, "structNameSample", XMPConst.NS_XMP, "sampleFieldName")) {
     prop = meta.getStructField(XMPConst.NS_XML, "structNameSample", XMPConst.NS_XMP, "sampleFieldName");
     meta.deleteStructField(XMPConst.NS_XML, "structNameSample", XMPConst.NS_XMP, "sampleFieldName");
     if (meta.doesStructFieldExist(XMPConst.NS_XML, "structNameSample", XMPConst.NS_XMP, "sampleFieldName")) {
        console.log("Struct field exists");
    } else {
       console.log("Struct field doesn't exist");
   }
} else {
 console.log("Struct field doesn't exist");
}

appendArrayItem(schemaNS, arrayName, itemValue, [itemOptions], [arrayOptions])

Appends an item to an existing array, or creates a new array-type property if the named array does not exist.

Example

XMPMetaObj.appendArrayItem(schemaNS, arrayName, itemValue[, itemOptions, arrayOptions])

countArrayItems(schemaNS, arrayName)

Reports the number of items in an array-type metadata property.

Returns: number - the number of items

Example

XMPMetaObj.countArrayItems(schemaNS, arrayName)

deleteArrayItem(schemaNS, arrayName, itemIndex)

Deletes the metadata tree that has the given array item as its root.

Example

XMPMetaObj.deleteArrayItem(schemaNS, arrayName, itemIndex)

deleteProperty(schemaNS, propName)

Deletes the metadata tree that has the given property as its root. If the property does not exist, does nothing.

Example

XMPMetaObj.deleteProperty(schemaNS, propName)

deleteStructField(schemaNS, structName, fieldNS, fieldName)

Deletes the metadata tree that has the given structure field as its root.

Example

XMPMetaObj.deleteStructField(schemaNS, structName, fieldNS, fieldName)

deleteQualifier(schemaNS, structName, qualNS, qualName)

Deletes the metadata tree that has the given qualifier as its root. If the qualifier does not exist, does nothing.

Example

XMPMetaObj.deleteQualifier(schemaNS, structName, qualNS, qualName)

doesArrayItemExist(schemaNS, arrayName, itemIndex)

Reports whether an array item with a given index currently exists in an existing array in the metadata.

Returns: boolean - true if the array and item exist.

Example

XMPMetaObj.doesArrayItemExist(schemaNS, arrayName, itemIndex)

doesPropertyExist(schemaNS, propName)

Reports whether a property with a given name currently exists in the metadata.

Returns: boolean - true if the property exists.

Example

XMPMetaObj.doesPropertyExist(schemaNS, propName)

doesStructFieldExist(schemaNS, structName, fieldNS, fieldName)

Reports whether a structure field with a given name currently exists in the metadata.

Returns: boolean - true if the structure and field exist.

Example

XMPMetaObj.doesStructFieldExist(schemaNS, structName, fieldNS, fieldName)

doesQualifierExist(schemaNS, structName, qualNS, qualName)

Reports whether a qualifier with a given name currently exists for a given property.

Returns: boolean - true if the property and qualifier exist.

Example

XMPMetaObj.doesQualifierExist(schemaNS, structName, qualNS, qualName)

dumpObject()

Creates and returns a string containing the metadata content of this object as RDF.

Returns: string - a string containing the metadata content of this object as RDF.
Example

XMPMetaObj.dumpObject()

getArrayItem(schemaNS, arrayName, itemIndex)

Retrieves an item from an array-type metadata property. Returns an XMPProperty object.

Returns: XMPProperty | undefined - the contents of the file.

Example

XMPMetaObj.getArrayItem(schemaNS, arrayName, itemIndex)

getLocalizedText(schemaNS, altTextName, genericLang, specificLang)

Retrieves the text value for a specific language from an alternate-text array. First tries to match the specific language. If not found, tries to match the generic language, if specified. If not found, gets the x-default item, if any. Otherwise, gets the first item.

Returns: string | undefined - the text value for a specific language from an alternate-text array.

Example

XMPMetaObj.getLocalizedText(schemaNS, altTextName, genericLang, specificLang)

getProperty(schemaNS, propName, [valueType])

Retrieves the value and options of a metadata property. Use for top-level, simple properties, or after using the path-composition functions in the XMPUtils object. Returns an XMPProperty object.

Returns: XMPProperty | undefined - the value and options of a metadata property

Example

XMPMetaObj.getProperty(schemaNS, propName[, valueType])

getStructField(schemaNS, structName, fieldNS, fieldName)

Retrieves a field value from within a nested structure in metadata. Returns an XMPProperty object.

Returns: XMPProperty | undefined - the field value from within a nested structure in metadata.

Example

XMPMetaObj.getStructField(schemaNS, structName, fieldNS, fieldName)

getQualifier(schemaNS, structName, qualNS, qualName)

Retrieves a qualifier attached to a metadata property. Returns an XMPProperty object.

Returns: XMPProperty | undefined - the qualifier attached to a metadata property

Example

XMPMetaObj.getQualifier(schemaNS, structName, qualNS, qualName)

insertArrayItem(schemaNS, arrayName, itemIndex, itemValue, [itemOptions])

Inserts an item into an array, before an existing item. The index positions of all later items are incremented. The array must exist.

Example

XMPMetaObj.insertArrayItem(schemaNS, arrayName, itemIndex, itemValue[, itemOptions])

iterator(options, schemaNS, propName)

Creates an iteration object that can iterate over the properties, arrays, and qualifiers within this metadata. Specify options, a namespace, and a property to limit the range and granularity of the resulting items. Returns an XMPIterator object.

Returns: XMPIterator - the XMPIterator object for this metadata object

Example

XMPMetaObj.iterator(options, schemaNS, propName)

serialize([options], [padding], [indent], [newline], [baseIndent])

Serializes this XMP metadata into a string as RDF.

Returns: string - the serialized XMP metadata as a RDF string

Example

XMPMetaObj.serialize([options, padding, indent, newline, baseIndent])

serializeToArray([options], [padding], [indent], [newline], [baseIndent])

Serializes this XMP metadata into a string as RDF, then converts that to an array of one-byte numeric values, the UTF-8 or UTF-16 encoded characters.

Returns: Array - the Array of Numbers.

Example

XMPMetaObj.serializeToArray([options, padding, indent, newline, baseIndent])

setArrayItem(schemaNS, arrayName, itemIndex, itemValue, [itemOptions])

Replaces an item within an array, or appends an item. The array must exist. To create an item, appendArrayItem() and insertArrayItem() are preferred.

Example

XMPMetaObj.setArrayItem(schemaNS, arrayName, itemIndex, itemValue[, itemOptions])

setLocalizedText(schemaNS, altTextName, genericLang, specificLang, itemValueThe)

Sets the text value for a specific language in an alternate-text array. Handles special cases for the x-default item.

Example

XMPMetaObj.setLocalizedText(schemaNS, altTextName, genericLang, specificLang, itemValue, setOptions)

setStructField(schemaNS, structName, fieldNS, fieldName, fieldValue, [options])

Sets the value of a field within a structure-type property, or creates a new field if the named field does not exist in the structure, or creates a new structure containing the named field if the named structure does not exist.

Example

XMPMetaObj.setStructField(schemaNS, structName, fieldNS, fieldName, fieldValue[, options])

setQualifier(schemaNS, propName, qualNS, qualName, qualValue, [options])

Attaches a new qualifier to a metadata property. A qualifier can be added to a simple property, an array item, a struct field, or another qualifier.

Example

XMPMetaObj.setQualifier(schemaNS, propName, qualNS, qualName, qualValue[, options])

setProperty(schemaNS, propName, propValue, [setOptions], [valueType])

Sets the value of a simple metadata property, creating the property if necessary, or creates a new array or structure property. For creating array and structure properties, setArrayItem() and setStructField() are preferred. Use this call to create or set top-level, simple properties, or after using the path-composition functions in the XMPUtils object.

Example

XMPMetaObj.setProperty(schemaNS, propName, propValue[, setOptions, valueType])

sort()

Sorts the XMP contents alphabetically. At the top level, sorts namespaces by their prefixes. Within a namespace, sorts top-level properties are sorted by name. Within a struct, sorts fields by their qualified name (that is, the XML prefix:local form.) Sorts unordered arrays of simple items by value. Sorts language alternative arrays by the xml:lang qualifiers, with the "x-default" item placed first.

Example

XMPMetaObj.sort()

deleteNamespace(namespaceURI)

Deletes a registered prefix - namespace URI pair.

Example

XMPMeta.deleteNamespace(namespaceURI)

dumpNamespaces(namespaceURI)

Creates and returns a human-readable string containing the list of registered namespace URIs and their associated prefixes.

Returns: string - the list of registered namespace URIs and their associated prefixes.

Example

XMPMeta.dumpNamespaces()

getNamespacePrefix(namespaceURI)

Retrieves the prefix associated with a registered namespace URI.

Returns: string - the prefix string followed by a colon.

Example

XMPMeta.getNamespacePrefix(namespaceURI)

getNamespaceURI(namespacePrefix)

Retrieves the registered namespace URI associated with a namespace prefix.

Returns: string - the URI String.

Example

XMPMeta.getNamespaceURI(namespacePrefix)

registerNamespace(namespaceURI, suggestedPrefix)

Registers a namespace with a prefix. If the suggested prefix is already in use, generates, registers, and returns a different prefix.

Returns: string - the String containing the actual registered prefix. This is the suggestedPrefix, unless that one is already assigned to another namespace.

Example

XMPMeta.registerNamespace(namespaceURI, suggestedPrefix)