Node Object Reference

There are 5 types of metadata node objects: MetaJob, MetaGroup, MetaDocument, MetaDatapage and MetaPage. Each node object holds three collections: attributes, fields and child nodes, except for the MetaPage which does not have child nodes. Most methods and properties are common to all the node objects while some are only available in one or a few objects. Unless otherwise noted, the methods and properties below are available in all node objects.

Some arguments are specific to a certain node type. For example, the Item method of the MetaGroup returns a MetaDocument, while the same method for a MetaDatapage returns a MetaPage. Because of that, the documentation uses node and child node as placeholder node types. The mental exercise to replace the placeholder with the appropriate type according to the context is left to the reader. For example, the documentation for the Fields property is written as Returns the node's field collection, but should be read as Returns the MetaPage's field collection when applied to a MetaPage object.

The TNodeType and TSelectWhat types are not defined in an Active Script environment, such as the PlanetPress Watch Script task. See the detailed reference for the numerical values to use.

Methods like Count, Index or PageCount work on all nodes, regardless of their Selected attributes. Methods whose names start with Selected however are meant to work with selected nodes. In other words, Selected methods only consider nodes that are set to be part of the output. For example, SelectedCount only considers child nodes that have their Selected property set to true, but also checks if their parents also have their Selected property to true. It is therefore possible that a node is selected but is not counted. The SelectedState property can be used to verify the effective selection state of a node, i.e. whether or not a node will be part of the output and, if not, whether it is because it is itself not selected or one of its parents is not.

Properties
TNodeType	NodeType
	Returns the node type of the current node.
Integer	Index
	Returns and sets the index of the node in its parent.
MetaCollection	Attributes
	Returns the node's attribute collection.
MetaCollection	Fields
	Returns the node's field collection.
Node	Parent ()
	Returns the parent node in the metadata tree.
Integer	Count
	Returns the number of child nodes.
Bool	Selected
	Indicates whether or not the node is set to be printed.
Integer	SelectedCount
	Returns the number child nodes selected to be output.
Methods
String	AttributeByIndex (Integer Index)
	Returns the specified attribute's value.
String	AttributeByName (const String Name)
	Returns the value of the attribute of the specified name.
String	FieldByIndex (Integer Index)
	Returns the specified field's value.
String	FieldByName (const String Name)
	Returns the value of field of the specified name.
String	FieldByNameIndex (const String Name, Integer Index)
	Returns the value of the N'th field of the specified name.
Node	Add (Integer Index)
	Adds a new child node to the current node.
	Clear ()
	Deletes all the child nodes as well as the attributes and fields.
	Copy ()
	Places a copy of the node in the metadata clipboard.
	Cut ()
	Removes the node and places it in the metadata clipboard.
	Delete ()
	Deletes the node.
Node	Paste ()
	Inserts the clipboard's content as the last child of the current node.
Node	PasteAt (Integer Index)
	Inserts the clipboard's content as a child node at the specified index.
Node	Item (Integer Index)
	Returns the child item at the specified index.
Node	Group (Integer Index)
	Returns the MetaGroup at the specified index.
Node	Document (Integer Index)
	Returns the MetaDocument at the specified index.
Node	Datapage (Integer Index)
	Returns the MetaDatapage at the specified index.
Node	Page (Integer Index)
	Returns the MetaPage at the specified index.
Integer	DocumentCount
	Returns the total number of documents in all groups.
Integer	DatapageCount
	Returns the total number of datapages present underneath this node.
Integer	PageCount
	Returns the total number of pages present underneath this node.
	Select (TSelectWhat SelectWhat)
	Selects the child nodes according to the SelectWhat parameter.
Integer	SelectedDatapageCount
	Returns the number of datapages selected to be output that are underneath this node.
Integer	SelectedDocumentCount
	Returns the number of documents selected to be output that are underneath this node.
Integer	SelectedPageCount
	Returns the number of pages selected to be output that are underneath this node.
Integer	IndexInDocument
	Index of the page among all the pages in its parent Document.
Integer	IndexInGroup
	Index of the page among all the pages in its parent Group.
Integer	IndexInJob
	Index of the page among all the pages in the Job.
Integer	SelectedIndexInDocument
	Index of the page among all the selected pages in its parent Document.
Integer	SelectedIndexInGroup
	Index of the page among all the selected pages in its parent Group.
Integer	SelectedIndexInJob
	Index of the page among all the selected pages in the Job.
	Sort
	Sorts the sub-nodes according to a number of criteria.

---

Property Documentation

MetaCollection Attributes

Returns the attribute collection of the current node.

Returns:

MetaCollection object of the attribute collection.

Integer Count

not available in MetaPage

Returns the number of child nodes in the current node.

Returns:

Number of child nodes.

MetaCollection Fields

Returns the field collection of the current node.

Returns:

MetaCollection interface of the field collection.

Integer Index

not available in MetaJob

Returns and sets the index of the node in its parent.

(reading)

Returns:

The index at which the current node is found in the parent's node list.

(writing)
Parameters:

Value

New index to move the node to. The valid range goes from 0 (i.e. the first node in the list) to Count-1.

Exceptions:

EOleException

Index is lower than 0 or higher than Count-1.

TNodeType NodeType

Returns the type of the current node. This allows to programmatically identify the node type and thus more easily program some cases that would be overly complex otherwise.

Returns:

Value representing the node type.

Script users: ntJob = 0, ntGroup = 2, ntDocument = 3, ntDatapage = 5, ntPage = 6.

Node Parent

(

)

not available in MetaJob

Returns the parent node of the current node.

Returns:

Reference to the parent node.

Bool Selected

not available in MetaPage

Indicates whether or not the node is set to be printed. If a node has its Selected property set to true, all of its child that also have their own Selected property set to true will print. If Selected is false, its child will not print, regardless of their Selected status.

(reading)

Returns:

True if the node is selected, false otherwise.

(writing)
Parameters:

Select

True to mark as selected to be printed, false if it is not to be printed.

Integer SelectedCount

not available in MetaPage

Returns the number of child nodes in the current node that are set to be output, meaning that they have their Selected property set to true, taking the parents into account.

Returns:

The number of child nodes that will be included in the output. If the current node and all of its parents have their Selected property set to true, this amounts to the number of child nodes that are selected. If any parent is not selected, returns 0.

---

Method Documentation

Node Add

(

Integer

Index

)

not available in MetaPage

Adds a new node as a child of the current node.

Parameters:

Index

Specifies where in the child list to add the node. The node is inserted before the node at the specified index. In other words, the node being inserted becomes the node found at Index. To add a node at the start of the collection, use 0. To add it at the end, use Node.Count.

Returns:

Reference to the node that was added.

Exceptions:

EOleException

The value of Index is invalid.

String AttributeByIndex

(

Integer

Index

)

Returns the value of the metadata attribute at the specified index.

Parameters:

Index

0-based index of the attribute value to retrieve. The index of the first element is 0 and the index of the last is Count-1.

Returns:

The value of the attribute as a string.

Exceptions:

EOleException

Index is lower than 0 or higher than Count-1.

String AttributeByName

(

const String

Name

)

Returns the value of the metadata attribute of the specified name.

Parameters:

Name

Name of the attribute to retrieve.

Returns:

The value of the attribute as a string. If an attribute named Name is not found, an empty string is returned.

Clear

(

)

not available in MetaPage

Deletes all the child nodes of the current node, as well as all of its attributes and fields.

Copy

(

)

not available in MetaJob

Places a copy of the current node, along with all of its children, attributes and fields, in the metadata clipboard. Modifying the original node after the copy is made does not modify the copy in the clipboard.

Cut

(

)

not available in MetaJob

Places a copy of the current node, along with all of its children, attributes and fields, in the metadata clipboard and immediately removes the original from the metadata structure.

WARNING: The node being cut is removed immediately. Any reference to it or its child nodes becomes invalid. The results of calling methods of such references is undefined.

Integer DatapageCount

MetaJob and MetaGroup only

Returns the number of MetaDatapage in all child nodes. This methods recursively goes through all child nodes to count the total number of MetaDatapage that are contained underneath the current node.

Returns:

Total number of MetaDatapage found under the current node.

Delete

(

)

not available in MetaJob

Removes the current node, along with all of its children, attributes and fields, from the metadata structure.

WARNING: The node being deleted is removed immediately. Any reference to it or its child nodes becomes invalid. The results of calling methods of such references is undefined.

Integer DocumentCount

MetaJob only

Returns the number of MetaDocument in all child nodes. This methods recursively goes through all child nodes to count the total number of MetaDocument that are contained underneath the current node.

Returns:

Total number of MetaDocument found under the current node.

String FieldByIndex

(

Integer

Index

)

Returns the value of the metadata field at the specified index.

Parameters:

Index

0-based index of the field value to retrieve. The index of the first element is 0 and the index of the last is Count-1.

Returns:

The value of the field as a string.

Exceptions:

EOleException

Index is lower than 0 or higher than Count-1.

String FieldByName

(

const String

Name

)

Returns the value of the metadata field of the specified name. If more than one field has the same name, this method returns the value of the first one it finds, starting at the first field in the list.

Parameters:

Name

Name of the field to retrieve.

Returns:

The value of the field as a string. If an field named Name is not found, an empty string is returned.

String FieldByNameIndex	(	const String	Name,
		Integer	Index
	)

Returns the value of the n'th metadata field of the specified name. This method can be used to retrieve the value of a specific field when more than one field has the same name.

Parameters:

	Name	Name of the field to retrieve.
	Index	Ordinal of the field to retrieve. To retrieve the value of the first field named Name, use 0. For the second field, use 1, and so on.

Returns:

The value of the specified field as a string. If an field named Name is not found, or Index is higher or equal to the number of fields named Name (in other words, you specify 4 to get the fifth but there are only three), an empty string is returned.

Exceptions:

EOleException

Index is lower than 0.

Integer IndexInDocument

MetaPage and MetaDatapage only

Returns the index of this page in its parent document, taking all the pages from all the datapages into account.

Returns:

Absolute index of the page within all the pages under the parent document.

Integer IndexInGroup

MetaDocument, MetaDatapage and MetaPage only

Returns the index of this page in its parent group, taking all the pages from all the datapages from all documents into account.

Returns:

Absolute index of the page within all the pages under the parent group.

Integer IndexInJob

not available in MetaJob

Returns the index of this page in the job, taking all the pages from all the datapages from all the documents from all the groups into account.

Returns:

Absolute index of the page within all the pages in the job.

Node Item	(	Integer	Index	)
MetaGroup Group	(	Integer	Index	)	MetaJob only
MetaDocument Document	(	Integer	Index	)	MetaGroup only
MetaDatapage Datapage	(	Integer	Index	)	MetaDocument only
MetaPage Page	(	Integer	Index	)	MetaDatapage only

Returns the child node located at the specified index.

Parameters:

Index

0-based index of the node to retrieve. The index of the first node is 0 and the index of the last is Count-1.

Returns:

Reference to the specified node.

Exceptions:

EOleException

Index is lower than 0 or higher than Count-1.

Integer PageCount

MetaJob, MetaGroup and MetaDocument only

Returns the number of MetaPage in all child nodes. This methods recursively goes through all child nodes to count the total number of MetaPage that are contained underneath the current node.

Returns:

Total number of MetaPage found under the current node.

Node Paste

(

)

not available in MetaPage

Inserts the contents of the metadata clipboard as the last child node of the current node. This removes the node from the clipboard, making it empty after the paste operation.

Returns:

Reference to the top node being pasted.

Exceptions:

EOleException

The node type of the clipboard and the current node don't match. For example, trying to paste a MetaGroup in a MetaGroup or a MetaPage in a MetaDocument.

Node PasteAt

(

Integer

Index

)

not available in MetaPage

Inserts the contents of the metadata clipboard at the specified index in the current node. This removes the node from the clipboard, making it empty after the paste operation.

Parameters:

Index

Specifies where in the child list to add the node. The node is inserted before the node at the specified index. In other words, the node being inserted becomes the node found at Index. To add a node at the start of the collection, use 0. To add it at the end, use Node.Count.

Returns:

Reference to the top node being pasted.

Exceptions:

	EOleException	The node type of the clipboard and the current node don't match. For example, trying to paste a MetaGroup in a MetaGroup or a MetaPage in a MetaDocument.
	EOleException	The value of Index is invalid.

Select

(

TSelectWhat

SelectWhat

)

not available in MetaPage

Changes the "selected" status of the current node as well as all of its child nodes according to the SelectWhat parameter.

Parameters:

SelectWhat

Indicates what to select. The value swNone changes the Selected property of the current node and all child nodes to false, while swAll changes it to true. Script users: use 0 for swNone, 1 for swAll.

Integer SelectedDatapageCount

MetaJob and MetaGroup only

Returns the number of datapages under the current node that are set to be part of the output, i.e. that have their Selected property set to true, as well as all of their parents.

Returns:

The number of such nodes, if any. If the current node is not selected or one of its parents is not, it returns 0.

Integer SelectedDocumentCount

MetaJob only

Returns the number of documents under the current node that are set to be part of the output, i.e. that have their Selected property set to true, as well as all of their parents.

Returns:

The number of such nodes, if any. If the current node is not selected or one of its parents is not, it returns 0.

Integer SelectedIndexInDocument

MetaDatapage and MetaPage only

Returns the index of this page in its parent document, taking only the selected pages into account.

Returns:

Absolute index of the page within all the selected pages under the parent document. If the page is not set to be output (i.e. its SelectedState is different than ssTrue), it returns -1.

Integer SelectedIndexInGroup

MetaDocument, MetaDatapage and MetaPage only

Returns the index of this page in its parent group, taking only the selected pages from all the datapages from all documents into account.

Returns:

Absolute index of the page within all the selected pages under the parent group. If the page is not set to be output (i.e. its SelectedState is different than ssTrue), it returns -1.

Integer SelectedIndexInJob

not available in MetaJob

Returns the index of this page in the job, taking only the selected pages from all the datapages from all the documents from all the groups into account.

Returns:

Absolute index of the page within all the selected pages in the job. If the page is not set to be output (i.e. its SelectedState is different than ssTrue), it returns -1.

Integer SelectedPageCount

MetaJob, MetaGroup and MetaDocument only

Returns the number of pages under the current node that are set to be part of the output, i.e. that have their Selected property set to true, as well as all of their parents.

Returns:

The number of such nodes, if any. If the current node is not selected or one of its parents is not, it returns 0.

Sort	(	const String	Name,
		TSortFlags	Flags,	(optional)
		const String	Name2,	(optional)
		TSortFlags	Flags2,	(optional)
		const String	Name3,	(optional)
		TSortFlags	Flags3	(optional)
	)			not available in MetaPage

Sorts the sub-nodes contained in the node according to a number of sort criteria. Unselected sub-nodes will be placed at the end, after all the selected sub-nodes, in the order in which they were placed prior to the sort.

Each of the three sort criteria can be modified by specifying one or more flags.

• sfAttribute (value = 1): The name refers to an Attribute rather than a field;
• sfDescending (value = 2): The sort is done in descending order (i.e. the highest to the lowest);
• sfNumeric (value = 4): The field is an integer numeric value.

All the parameters to this method except for the first one are optional. If a Name is specified, it must be valid for every sub-node. If, for example, the specified field is not found in a sub-node, or a numeric sort is performed and one of the values is not numeric (i.e. consists of only decimal characters, no thousand or decimal separator allowed), the method will fail.

If a sub-node contains multiple occurences of fields with the specified name, only the first occurrence will be considered.

String comparisons are done without regards to the case (case-insensitive) using the Windows Win32 API function CompareString(LOCALE_USER_DEFAULT, NORM_IGNORECASE, ...).

Parameters:

	Name	Name of the field contained in each sub-node whose value will be used as the first sort criteria.
	Flags	(optional) Set of flags that modify how the sorting on Name is done.
	Name2	(optional) Name of the field contained in each sub-node whose value will be used as the second sort criteria.
	Flags2	(optional) Set of flags that modify how the sorting on Name2 is done.
	Name3	(optional) Name of the field contained in each sub-node whose value will be used as the third sort criteria.
	Flags3	(optional) Set of flags that modify how the sorting on Name3 is done.

Exceptions:

	EOleException	Specified field does not exist in one of the sub-nodes.
	EOleException	A numeric sort is specified and one of the fields does not contains a valid numeric integer value.
	EOleException	An error occurred while comparing two strings.

---