Accessing the XML structre of an InDesign^® document.

You will find a general example for the use of xml here.

Text or frame of a document can be linked with XML elements. The methods of the module permit access to these elements.

1. If the script has its own XML element, this will be used. This criterium is only fulfilled by scripts which are triggered by XML Link.
2. If a text model is defined (textmodel::available) and is linked with an XML element, this element will be used.
3. If a frame is defined (gFrame != 0) and is linked with an XML element, this element will be used.
4. Use the root element of the document

static int set_document_attribute(
  ItemRef docRef,
  char* name,
  char* value)

Set or update a attribute of the root element of a document

Name	Type	Default	Description
Return	int		0 or ErrorCode
docRef	ItemRef	-	document reference
name	String or char*	-	name of the attribute
value	String or char*	-	value of the attribute

Since

Version 3.4 R5804, 23. Sep 2014

Available:

Comet-Plug-Ins, comet_pdf, Illustrator

See Also

comet.CDocument.setAttribute

static int get_document_attribute(
  ItemRef docRef,
  char* name,
  char* out)

Get the value of an attribute of the root element of a document

Name	Type	Default	Description
Return	int		0 or ErrorCode
docRef	ItemRef	-	document reference
name	String or char*	-	name of the attribute
out	String or char*	-	buffer for the result string

Since

Version 3.4 R5804, 23. Sep 2014

Available:

Comet-Plug-Ins, comet_pdf, Illustrator

See Also

comet.CDocument.getAttribute

static int exec(ItemRef frameRef = 0, char* elementName = 0)

Execute a script from the XML structure of a frame. The XML elements of frames may contain script code as value. Here you can execute this code.

Name	Type	Default	Description
Return	int		0 or ErrorCode
frameRef	ItemRef	0	Valid document frame 0 : current script frame
elementName	String or char*	0	Name of element to execute. The elements value must consist of valid cScript code. 0 or "" : first element in frame

Since

v4.0.5 R9020, 30. Sep. 2015

Available:

Comet-Plug-Ins, comet_pdf

static int link(
  char* parent,
  char* name,
  int index,
  ...)

Link the current script frame or the current text model of the script with a new XML element. If the element name is not yet present in the panel 'Tags', it will be automatically inserted. If the element could be successfully linked, then a user-defined number of attributes with value can be set up in the element.

Name	Type	Default	Description
Return	int		0 or ErrorCode
parent	String or char*	-	absolute XML pathfor the parent element of the new XML element. If the parent does not exist, it will created. If the frame has an xml element already, the element is moved to the given parent.
name	String or char*	-	Name of the element The name of an XML element must must begin with a letter and may only consist of letters, numbers and '_'. You may mark the name by the trailing (and blank delimited) keywords noRename and/or noMove to declare how to work on existing xml elements : noRename Do not rename an element already existing noMove Do not move an element already existing
index	int	-	Index the parent, -1 = last element (0-based)
⇨User-defined number of attribute value pairs may follow
attr_name	String or char*	-	Name of the attribute which is to be added to the element. The name of an XML element must must begin with a letter and may only consist of letters, numbers and '_'.
attr_value	String or char*	-	Value of the attribute attr_name

siehe link_frame

Since

Available

priint:comet InDesign^® Plug-Ins

static int link_frame(
  ItemRef fm,
  char* parent,
  char* name,
  int index,
  ...)

Link a document frame with a new XML element. If the element name is not yet present in the panel 'Tags', it will be automatically inserted. If the element could be successfully linked, then a user-defined number of attributes with value can be set up in the element.
If the frame type has not yet been defined, the frame will be automatically made into a text frame. The call of the function can therefore change the content of the specified ItemReference.

Name	Type	Default	Description
Return	int		0 or ErrorCode
fm	ItemRef	-	Frames which should be linked. If the frame type is not defined, the frame will be made into a text frame. The content of the reference can be changed by the call.
parent	String or char*	-	absolute XML pathfor the parent element of the new XML element If the parent does not exist, it will created. If the frame has an xml element already, the element is moved to the given parent.
name	String or char*	-	Name of the element The name of an XML element must must begin with a letter and may only consist of letters, numbers and '_'. You may mark the name by the trailing (and blank delimited) keywords noRename and/or noMove to declare how to work on existing xml elements : noRename Do not rename an element already existing noMove Do not move an element already existing
index	int	-	Index the parent, -1 = last element (0-based)
⇨User-defined number of attribute value pairs may follow
attr_name	String or char*	-	Name of the attribute which is to be added to the element. The name of an XML element must must begin with a letter and may only consist of letters, numbers and '_'.
attr_value	String or char*	-	Value of the attribute attr_name

int main ()
{
    ItemList	frames  = itemlist::get_selected_frames ();
    int			len		= itemlist::length (frames);
    int			i      	= 0;
    ItemRef		frame	= item::alloc ();
    int     	r, g, b;
    char		attr_val1[255];
    char		attr_val2[255];
    char		attr_val3[255];

    r = 0; g = 100; b = 100;

    while (i < len)
    {
        // Get the next selected frames
        itemlist::get (frames, frame, i++);

        // Color frames
        r = r+30; frame::color (frame, r, g, b);

        // Calculate value of the attribute
        sprintf (attr_val1, "%d - 1", i);
        sprintf (attr_val2, "%d - 2", i);
        sprintf (attr_val3, "%d - 3", i);

        // Link frame with an XML element
        xml::link_frame (
         	frame,
         	"/",
         	"My_XML_Element",
         	-1,
         	"Wert 1", 	attr_val1,
         	"Wert 2", 	attr_val2,
         	"Wert 3", 	attr_val3);
    }

    item::release (frame);
    itemlist::release (frames);
}

Since

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static int untag(
  ItemRef frameRef,
  int startPos,
  int len)

Remove the XML element(s) of a frame or text range.

Name	Type	Default	Description
Return	int		0 or ErrorCode
frameRef	ItemRef	-	valid frame reference
startPos	int	-	start position to remove XML elements kTotalEnd : Remove the frames XML element. kSelection : Use current text selection. If no text selection is set or the text selection in a different frame, error 313 (noSelectionErr) is returned. otherwise : 0-based frame relative text position.
len	int	-	range length. Ignored if startPos = kTotalEnd or kSelection.

Preconditions

#include "internal/text.h"

remove the frames XML element

#include "internal/text.h"
#include "internal/types.h"

int main ()
{
    xml::untag (gFrame, kTotalEnd, 0);
    return 0;
}

Only remove sub elements connected to the text content.

#include "internal/text.h"
#include "internal/types.h"

int main ()
{
    xml::untag (gFrame, 0, kEnd);
    return 0;
}

Since

Version 2.1 R 1155, 22.2.2009

Available

priint:comet InDesign^® Plug-Ins

static int path(
  ItemRef frameRef,
  char* path,
  char* elementName = 0,
  int* indexInParent = 0)

Get the the path of the XML element of a frame.

Name	Type	Default	Description
Return	int		0 or ErrorCode
frameRef	ItemRef	0	Valid document frame
path	String or char*	-	Path to XML element of frame (or empty)
elementName	String or char*	0	Name of XML element of frame (or empty)
indexInParent	int*	0	1-based index in parent XML element of frame

Since

v4.0.5 R10330, 15. Apr 2015

Available:

Comet-Plug-Ins, comet_pdf

See Also

path_elem

static int path_elem(
  XMLElement elem,
  char* path,
  char* elementName = 0,
  int* indexInParent = 0)

Get the the path of the XML element of an XML element the the XML structure of a document.

Name	Type	Default	Description
Return	int		0 or ErrorCode
eleme	XMLElement	-	Valid document frame
path	String or char*	-	Path to XML element
elementName	String or char*	0	Name of XML element
indexInParent	int*	0	1-based index in parent XML element

int main ()
{
    XMLElement   	elem 	= 0;
    char 			path [5000], name [5000];
    int 			index;

    xml::get_element_by_path (0, &elem, "/abc/def/ghi[7]");
    xml::path_elem (elem, value, name, &index);
    wlog ("", " Path '%s/%s[%d]\n", value, name, index);

    xml::release (elem);
    return 0;
}

Since

v4.0.5 R20300, 5. Okt. 2017

Available:

Comet-Plug-Ins, comet_pdf

See Also

path

static int add_attribute(
  ItemRef frameRef,
  char* attrName,
  char* attrVal)

Add or change an attribute to/of the XML element of a frame.

Of course, the frame must have an XML element in the structure of the document beforehand!

To create or change an XML attribute of the document please use the following calls

XMLElement   	elem 	= 0;

xml::create_element (&elem, 0, "/", 1);
xml::add_attribute_elem (elem, "my_elem", "my value");

Name	Type	Default	Description
Return	int		0 or ErrorCode
frameRef	ItemRef	-	Valid document frame 0 : current script frame
attrName	String or char*	-	Valid name of an XML attribute
attrVal	String or char*	-	Value of attribute

Since

v4.0.5 R10330, 15. Apr 2015

Available:

Comet-Plug-Ins, comet_pdf

See Also

add_attribute_elem

static int add_attribute_elem(
  XMLElement elem,
  char* attrName,
  char* attrVal)

Add or change an attribute to/of an XML element.

Name	Type	Default	Description
Return	int		0 or ErrorCode
elem	XMLElement	-	Valid XML element of the XML structure of a document
attrName	String or char*	-	Valid name of an XML attribute
attrVal	String or char*	-	(New) value of attribute

int main ()
{
    XMLElement   	elem 	= 0;
    char			value 	[5000];

    xml::get_element_by_path (0, &elem, "/abc/def/ghi/aaa[9]");

    xml::sattribute_elem (elem, "AAA_9", value);
    printf ("A1 (%s)\n", value);

    xml::add_attribute_elem (elem, "AAA_9", "Value aaa 9");
    xml::sattribute_elem (elem, "AAA_9", value);
    printf ("A2 (%s)\n", value);

    xml::add_attribute_elem (elem, "AAA_9", "New value aaa 9");
    xml::sattribute_elem (elem, "AAA_9", value);
    printf ("A3 (%s)\n", value);

    xml::release (elem);
    return 0;
}

Since

v4.0.5 R20300, 6. Oct. 2017

Available:

Comet-Plug-Ins, comet_pdf

See Also

add_attribute

static int attribute_exists(char* xml_path, char* attribute)

Does the XML element have a certain attribute?

To get the name of an attribute, you may use one of the functions iattribute, iattribute_elem, ... and the index of the attribute.

Name	Type	Default	Description
Return	int		1 attribute exists 0 does not exist
xml_path	String or char*	-	relative XML path of own XML element or absolute XML path
attribute	String or char*	-	Name of the searched attribute

result = xml::attribute_exists (path, attribute);

Since

Available

priint:comet InDesign^® Plug-Ins

static int attribute_exists_frame(ItemRef fm, char* attribute)

Does the frame have an XML Element containing a certain attribute?

To get the name of an attribute, you may use one of the functions iattribute, iattribute_elem, ... and the index of the attribute.

Name	Type	Default	Description
Return	int		1 attribute exists 0 does not exist
fm	ItemRef	-	Frame reference
attribute	String or char*	-	Name of the searched attribute

result = xml::attribute_exists (path, attribute);

Since

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static int attribute_exists_elem(XMLElement xmlElement, char* attribute)

Does the XML element have a certain attribute?

To get the name of an attribute, you may use one of the functions iattribute, iattribute_elem, ... and the index of the attribute.

Name	Type	Default	Description
Return	int		1 : attribute exists 0 : does not exist
xmlElement	XMLElement	-	Valid reference to an XML element of a document
attribute	String or char*	-	Name of the searched attribute

Example

Complete example

Since

Version 2.1, R1014, 31. Oct. 2008

Available

priint:comet InDesign^® Plug-Ins

See Also

get_element

static int count_attributes(char* xml_path)

Number of attributes of an XML element.

To get the name of an attribute, you may use one of the functions iattribute, iattribute_elem, ... and the index of the attribute.

Name	Type	Default	Description
Return	int		Number of attributes 0 : The element was not found or does not have any attributes
xml_path	String or char*	-	relative XML path of own XML element or absolute XML path

Since

Version 1.3.1 (24. Januar 2006)

Available

priint:comet InDesign^® Plug-Ins

static int count_attributes_frame(ItemRef fm)

Number of attributes of an XML element of a frame.

To get the name of an attribute, you may use one of the functions iattribute, iattribute_elem, ... and the index of the attribute.

Name	Type	Default	Description
Return	int		Number of attributes 0 : The element was not found or does not have any attributes
fm	ItemRef	-	Frame reference

Since

Version 1.3.1 (24 January 2006)

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static int count_attributes_elem(XMLElement xmlElement)

Number of attributes of an XML element.

To get the name of an attribute, you may use one of the functions iattribute, iattribute_elem, ... and the index of the attribute.

Name	Type	Default	Description
Return	int		Number of attributes
xmlElement	XMLElement	-	Valid reference to an XML element of a document

Example

Complete example

Since

Version 2.1, R1014, 31. Oct. 2008

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

get_element

static int remove_attributes_elem(
  XMLElement xmlElement,
  char* name,
  int index = -1)

Remove attributes from an XML element of the XML structure of a document.

To get the name of an attribute, you may use one of the functions iattribute, iattribute_elem, ... and the index of the attribute.

Name	Type	Default	Description
Return	int		0 or ErrorCode
xmlElement	XMLElement	-	Valid XML element
name	String or char*	-	Name of attribute to remove 0 : use index
index	int	-1	Index of attribute to remove. The index is used only if name is 0 or "". >= 0 : 0-based index of attribute -1 : Remove all attributes

int main ()
{
    XMLElement   	elem 	= 0;

    xml::get_xmlelement_by_path (0, &elem, "/abc/def/ghi/WWWW");
    xml::remove_attributes_elem (elem, 0, -1);
    xml::release (elem);

    return 0;
}

Since

v4.0.5 R20300, 6. Okt. 2017

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static int iattribute(char* xml_path, char* attribute)

Get the value of an XML attribute as an integer. The attribute can be called using its name or by means of an index.

Name	Type	Default	Description
Return	int		Value of XML attribute as int or -1
xml_path	String or char*	-	relative XML path of own XML element or absolute XML path
⇨ Select attribute by its name
attribute	String or char*	-	Name of an attribute
⇨ Select attribute by means of index
index	int	-	0-based attribute index, see count_attributes
name	String or char*	-	After execution the variable gets the name of the attribute 0 : Do not ascertain name otherwise : Allocated memory for the name

Name-based element selection

showmessage ("%d", xml::iattribute (xml_path, attr));

Index-based element selection For the name a parameter must be specified. The value of the name parameter may be 0.

char	name[256];

showmessage ("%s = %d", xml::iattribute (xml_path, 0, name), name);

Since

Index-based element selection since Version 1.3.1 (24 January 2006)

Available

priint:comet InDesign^® Plug-Ins

See Also

xml::getint
count_attributes

static int iattribute_frame(ItemRef fm, char* attribute)

Get the value of an XML attribute of the XML object of a frame as an integer. The attribute can be called using its name or by means of an index.

Name	Type	Default	Description
Return	int		Wert des XML-Attributes oder -1
⇨ Select attribute by its name
attribute	String or char*	-	Name of an attribute
⇨ Select attribute by means of index
index	int	-	0-based attribute index, see count_attributes
name	String or char*	-	After execution the variable gets the name of the attribute 0 : Do not ascertain name otherwise : Allocated memory for the name

Namensbasierte Elementauswahl

showmessage ("%d", xml::iattribute_frame (gFrame, attr));

Index-based element selection For the name a parameter must be specified. The value of the name parameter may be 0.

char	name[256];

showmessage("%s = %d",
 	name,
 	xml::iattribute_frame (gFrame, 0, name));

Since

Index-based element selection since Version 1.3.1 (24 January 2006)

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static int iattribute_elem(XMLElement xmlElement, char* attribute)

Like iattribute_frame, but the element is given by itself, not by its frame.

Example

Complete example

Since

Version 2.1, R1014, 31. Oct. 2008

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

get_element
iattribute_frame

static char* sattribute(
  char* xml_path,
  char* attribute,
  char* result)

Get the value of an XML attribute. The attribute can be called using its name or by its index.

Name	Type	Default	Description
Return	String or char*		Value of the XML attribute, or, in case of some errors, 0.
xml_path	String or char*	-	relative XML path of own XML element or absolute XML path
⇨ Select attribute by its name
attribute	String or char*	-	Name of an attribute
result	String or char*	-	Allocated memory for the result. Empty when element or attribute not found.
⇨ Select attribute by means of index
index	int	-	0-based attribute index, see count_attributes
name	String or char*	-	After execution the variable gets the name of the attribute 0 : Do not ascertain name otherwise : Allocated memory for the name
result	String or char*	-	Allocated memory for the result. Empty when element or attribute not found.

Namensbasierte Elementauswahl

char	val[2000];

showmessage ("%s", xml::sattribute_frame (xml_path, attr, val));

Index-based element selection For the name a parameter must be specified. The value of the name parameter may be 0.

char	name[256];

char 	val[2000];

showmessage ("%s = %s,", xml::attribute (xml_path, 0, name, val), name);

Since

Index-based element selection since Version 1.3.1 (24 January 2006)

Available

priint:comet InDesign^® Plug-Ins

See Also

xml::strcpy

static char* sattribute_frame(
  ItemRef fm,
  char* attribute,
  char* result)

Get the value of an XML attribute of the XML object of a frame. The attribute can be called using its name or by its index.

Name	Type	Default	Description
Return	String or char*		Value of the XML attribute or 0 in case of some errors.
⇨ Select attribute by its name
attribute	String or char*	-	Name of an attribute
result	String or char*	-	Reserved memory for the result
⇨ Select attribute by means of index
index	int	-	0-based attribute index, see count_attributes
name	String or char*	-	After execution the variable gets the name of the attribute 0 : Do not ascertain name otherwise : Allocated memory for the name
result	String or char*	-	Reserved memory for the result 0 : If only the name is to be ascertained, the parameter can be specified with 0.

Name-based element selection

char val[2000];

showmessage("%s", xml::attribute_frame (gFrame, attr, val));

Index-based element selection For the name a parameter must be specified. The value of the name parameter may be 0.

char	name[256];
char	attr[256];

showmessage("%s = %s",
 	name,
 	xml::sattribute_frame(gFrame, 0, name, attr));

Since

Index-based element selection since Version 1.3.1 (24 January 2006)

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static char* sattribute_elem(
  XMLElement xmlElement,
  char* attribute,
  char* result)

Like sattribute_frame, but the element is given by itself, not by its frame.

Example

Complete example

Since

Version 2.1, R1014, 31. Oct. 2008

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

get_element
sattribute_frame

static float fattribute(char* xml_path, char* attribute)

Get the value of an XML attribute as a real number. The attribute can be called using its name or by means of an index.

Name	Type	Default	Description
Return	float		Value of the XML attribute as float or -1.0
xml_path	String or char*	-	relative XML path of own XML element or absolute XML path
⇨ Select attribute by its name
attribute	String or char*	-	Name of an attribute
⇨ Select attribute by means of index
index	int	-	0-based attribute index, see count_attributes
name	String or char*	-	After execution the variable gets the name of the attribute 0 : Do not ascertain name otherwise : Allocated memory for the name

Name-based element selection

showmessage ("%f", xml::fattribute_frame (xml_path, attr));

Index-based element selection For the name a parameter must be specified. The value of the name parameter may be 0.

char	name[256];

showmessage ("%s = %f", xml::fattribute (xml_path, 0, name), name);

Since

Index-based element selection since Version 1.3.1 (24 January 2006)

Available

priint:comet InDesign^® Plug-Ins

See Also

xml::getfloat

static float fattribute_frame(ItemRef fm, char* attribute)

Get the value of an XML attribute of an XML object of a frame as a real number. The attribute can be called using its name or by means of an index.

Name	Type	Default	Description
Return	float		Wert des XML-Attributes oder -1
fm	ItemRef	-	valid frame reference
⇨ Select attribute by its name
attribute	String or char*	-	Name of an attribute
⇨ Select attribute by means of index
index	int	-	0-based attribute index, see count_attributes
name	String or char*	-	After execution the variable gets the name of the attribute 0 : Do not ascertain name otherwise : Allocated memory for the name

Name-based element selection

showmessage("%f", xml::fattribute_frame (gFrame, attr));

Index-based element selection For the name a parameter must be specified. The value of the name parameter may be 0.

char	name[256];
char	attr[256];

showmessage("%s = %f",
 	name,
 	xml::fattribute_frame(gFrame, 0, name, attr));

Since

Index-based element selection since Version 1.3.1 (24 January 2006) Index-based element selection since Version 1.3.1 (24 January 2006)

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static float fattribute_elem(XMLElement xmlElement, char* attribute)

Like fattribute_frame, but the element is given by itself, not by its frame.

Example

Complete example

Since

Version 2.1, R1014, 31. Oct. 2008

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

get_element
fattribute_frame

static int getint(
  char* xml_path,
  int* outStartPos = 0,
  int* outLen = 0)

Get the text which is linked with an XML element as an integer.

Name	Type	Default	Description
Return	int		Value of the XML attribute as int or -1
xml_path	String or char*	-	relative XML path for own XML element or absolute XML path
outStartPos	int*	0	On successful return it contains the (0-based) textposition of the XML elements text.
outLen	int*	0	On successful return it contains the the length of the linked with the XML element.

int f = xml::getint (xml_path);

Since

outStartPos and outLen since Version 2.1, R 1014, 30. Oct. 2008 (day of the first snow of 2008)

Available

priint:comet InDesign^® Plug-Ins

See Also

getfloat
strcpy
getint_frame

static int getint_frame(
  ItemRef frameRef,
  char* xml_path,
  int* outStartPos = 0,
  int* outLen = 0)

Get the text which is linked with an XML element of a given frame as an integer.

Name	Type	Default	Description
Return	int		Value of the XML attribute as int or -1
frameRef	ItemRef	-	Valid document frame
xml_path	String or char*	-	relative XML path for own XML element or absolute XML path
outStartPos	int*	0	On successful return it contains the (0-based) textposition of the XML elements text.
outLen	int*	0	On successful return it contains the the length of the linked with the XML element.

Since

outStartPos und outLen since version 2.1, R 1014, 30. Oct. 2008 (day of the first snow of 2008)

Available

priint:comet InDesign^® Plug-Ins

See Also

getint

static int getint_elem(
  XMLElement xmlElement,
  int* outStartPos = 0,
  int* outLen = 0)

Like getint_frame, but the element is given by itself, not by its frame and an XML path.

Example

Complete example

Since

Version 2.1, R1014, 31. Oct. 2008

Available

priint:comet InDesign^® Plug-Ins

See Also

get_element
getint_frame

static float getfloat(
  char* xml_path,
  int* outStartPos = 0,
  int* outLen = 0)

Get the text which is linked with an XML element as a real number.

Name	Type	Default	Description
Return	float		Value of the XML attribute as int or -1
xml_path	String or char*	-	relative XML path for own XML element or absolute XML path
outStartPos	int*	0	On successful return it contains the (0-based) textposition of the XML elements text.
outLen	int*	0	On successful return it contains the the length of the linked with the XML element.

float f = xml::getfloat (xml_path);

Since

outStartPos and outLen since Version 2.1, R 1014, 30. Oct. 2008 (day of the first snow of 2008)

Available

priint:comet InDesign^® Plug-Ins

See Also

getint
strcpy
getfloat_frame

static float getfloat_frame(
  ItemRef frameRef,
  char* xml_path,
  int* outStartPos = 0,
  int* outLen = 0)

Get the text which is linked with an XML element a given frame as a real number.

Name	Type	Default	Description
Return	float		Value of the XML attribute as int or -1
frameRef	ItemRef	-	Valid document frame
xml_path	String or char*	-	relative XML path for own XML element or absolute XML path
outStartPos	int*	0	On successful return it contains the (0-based) textposition of the XML elements text.
outLen	int*	0	On successful return it contains the the length of the linked with the XML element.

Since

outStartPos und outLen since version 2.1, R 1014, 30. Oct. 2008 (day of the first snow of 2008)

Available

priint:comet InDesign^® Plug-Ins

See Also

getfloat

static float getfloat_elem(
  XMLElement xmlElement,
  int* outStartPos = 0,
  int* outLen = 0)

Like gefloat_frame, but the element is given by itself, not by its frame and an XML path.

Example

Complete example

Since

Version 2.1, R1014, 31. Oct. 2008

Available

priint:comet InDesign^® Plug-Ins

See Also

get_element
gefloat_frame

static char* strcpy(
  char* xml_path,
  char* result,
  int maxlen = 0,
  int* outStartPos = 0,
  int* outLen = 0,
  int fmt = 0)

Get the text which is linked with an XML element.

Name	Type	Default	Description
Return	int		Same as parameter result. Value of the XML attribute.
xml_path	String or char*	-	relative XML path for own XML element or absolute XML path
result	String or char*	-	Reserved memory for the result
maxlen	int	user-defined maximum number of bytes for the result 0 user-defined length
outStartPos	int*	0	On successful return it contains the (0-based) textposition of the XML elements text.
outLen	int*	0	On successful return it contains the the length of the linked with the XML element.
fmt	int	kExportPlain	Format of result string. See frame::gettext for details.

Preconditions

#include "internal/text.h"

char	s[256];
xml::strcpy (xml_path, s, 255);

Since

outStartPos and outLen since Version 2.1, R 1014, 30. Oct. 2008 (day of the first snow of 2008)
fmt since version 2.1, R 1070, 16. Dec. 2008 (still snow)

Available

priint:comet InDesign^® Plug-Ins

See Also

getint
strcpy_frame
getfloat_frame

static char* strcpy_frame(
  ItemRef frameRef,
  char* xml_path,
  char* result,
  int maxlen = 0,
  int* outStartPos = 0,
  int* outLen = 0,
  int fmt = 0)

Get the text which is linked with an XML element a given frame.

Name	Type	Default	Description
Return	String or char*		Same as result. Value of the XML attribute.
frameRef	ItemRef	-	Valid document frame
xml_path	String or char*	-	relative XML path for own XML element or absolute XML path
result	String or char*	-	Reserved memory for the result
maxlen	int	0	User-defined maximum number of bytes for the result 0: any length.
outStartPos	int*	0	On successful return it contains the (0-based) textposition of the XML elements text.
outLen	int*	0	On successful return it contains the the length of the linked with the XML element.
fmt	int	kExportPlain	Format of result string. See textmodel::gettext for details.

Preconditions

#include "internal/text.h"

Since

outStartPos and outLen since version 2.1, R 1014, 30. Oct. 2008 (day of the first snow of 2008)
fmt since version 2.1, R 1070, 16. Dec. 2008 (still snow)

Available

priint:comet InDesign^® Plug-Ins

See Also

strcpy

static char* strcpy_elem(
  XMLElement xmlElement,
  char* result,
  int maxlen = 0,
  int* outStartPos = 0,
  int* outLen = 0,
  int fmt = 0)

Like strcpy_frame, but the element is given by itself, not by its frame and an XML path.

Example

Complete example

Since

Version 2.1, R1014, 31. Oct. 2008

Available

priint:comet InDesign^® Plug-Ins

See Also

get_element
strcpy_frame

static int get_element(
  ItemRef frameRef,
  XMLElement* xmlElement = 0,
  char* path = 0)

Get the XML element of the given frame (if any). Optionally you can select a subelement by a given xml path.

Name	Type	Default	Description
Return	int		0 : element found otherwise : ErrorCode
frameRef	ItemRef	-	Valid frame reference
xmlElement	XMLElement*	0	Pointer to a varaibale of type XMLElement (&elem).
path	String or char*	0	XML path to a sub-element

Example

Complete example

Since

Version 2.1, R1014, 31. Oct. 2008

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

xml::release
count_children
get_child
get_parent

static int get_xmlelement(
  ItemRef frameRef,
  XMLElement* xmlElement = 0,
  char* path = 0)

Deprecated

Please use xml::get_element instead.

static int get_element_by_path(
  ItemRef docRef,
  XMLElement* xmlElement = 0,
  char* path = 0)

Get an XML element by its XML path.

Name	Type	Default	Description
Return	int		0 : Element found otherwise : eeror code
docRef	ItemRef	-	Document reference 0 : current document
xmlElement	XMLElement*	-	Result. Pointer to a valid variable of type XMLElement (&elem).
path	String or char*	-	XML-Pfad of element to search for.

int main ()
{
    XMLElement   	elem 	= 0;
    char			value 	[5000];

    xml::get_element_by_path (0, &elem, "/abc/def/ghi/aaa[8]");
    xml::sattribute_elem (elem, "Name_AAA_8", value);
    wlog ("# Value (%s)\n", value);

    xml::release (elem);
    return 0;
}

Since

v4.0.5 R20300, 6. Okt. 2017

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

xml::release
count_children
get_child
get_parent

static int create_element(
  XMLElement* out_elem,
  ItemRef docRef,
  char* path,
  int useExisting = 1)

Create a new XML element in the XML structure of the document. If the element already exists, you may choose just to get this or create a sibling.

Name	Type	Default	Description
Return	int		0 or ErrorCode
out_elem	XMLElement*	-	Output variable (e.g. &aml;elem)
docRef	ItemRef	-	Document containing the XML structure 0 : current documnt
path	String or char*	-	Complete path to element. If the path does not exist, it will be created automatically. If the path contains index parts (for instance [10]), missing elements are created too. Please take care to use valid XML identifiers in the path!
useExisting	int	1	What to do, if the element already exists: 1 : Return the existing one 0 : Create a sibling

int main ()
{
    XMLElement   	elem 	= 0;
    int 			res;
    char 			path [5000], name [5000], value [5000];
    int 			index;

    xml::create_element (&elem, 0, "/abc/def/ghi/aaa");

    xml::path_elem (elem, path, name, &index);
    showmessage ("<%s/%s> : %d", path, name, index);

    xml::add_attribute_elem (elem, "Name_AAA", "Value AAA");
    xml::sattribute_elem (elem, "Name_AAA", value);
    showmessage ("%s", value);

    xml::release (elem);
    return 0;
}

Since

Version 4.0.5 R20300, 5. Oct 2017

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static int delete_element(XMLElement elem, int autoRelease = 1)

Remove an XML element and all its sub-elements from the XML structure of its document.Entferne ein XMLElement mit allen Unterelementen aus der XML-Struktur des Dokumentes. When deleting XML elements associated with document content, e.g. with frames, this document content is retained.

Name	Type	Default	Description
Return	int		0 or ErrorCode
elem	XMLElement	-	Valid XML element
autoRelease	int	1	Automatically release the element? 1 : Yes 0 : No. You may use xml::release to release the element later.

int main ()
{
    XMLElement   	elem 	= 0;

    xml::get_element_by_path (0, &elem, "/abc/def/Root");
    xml::delete_element (elem);

    return 0;
}

Since

Version 4.0.5 R20300, 5. Oct 2017

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static int count_children(XMLElement xmlElement)

Count the subelements of an XML element of the document. Only the direct successors are counted.

Name	Type	Default	Description
Return	int		Number of children
xmlElement	XMLElement	-	Valid reference to an XML element of a document

Example

Complete example

Since

Version 2.1, R1014, 31. Oct. 2008

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

get_element

static int get_child(
  ItemRef xmlElement,
  int index,
  XMLElement* childRef)

Get a sub element of an XML element.

Name	Type	Default	Description
Return	0 : element found otherwise : ErrorCode
xmlElement	XMLElement	-	Valid reference to an XML element of a document
index	int	-	0-based index
childRef	XMLElement	0	Destination variable for the child. If missing or 0, only the existance of the requested child is checked.

Example

Complete example

Since

Version 2.1, R1014, 31. Oct. 2008

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

get_element
count_children

static int get_parent(ItemRef xmlElement, XMLElement* parentRef)

Get a parent element of an XML element.

Name	Type	Default	Description
Return	0 : element found otherwise : ErrorCode
xmlElement	XMLElement	-	Valid reference to an XML element of a document
parentRef	XMLElement	0	Destination variable for the parent. If missing or 0, only the existance of the requested parent is checked.

Example

Complete example

Since

Version 2.1, R1014, 31. Oct. 2008

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

get_element

static char* get_name(XMLElement xmlElement)

Get the name of an XML element.

Name	Type	Default	Description
Return	String or char*		"" : Error otherwise : Name of element. The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. See here to learn more about functions returning r/o char* values.
xmlElement	XMLElement	-	Valid reference to an XML element of a document

For later uses of an XML element name, copy it to a local variable.

char name[512];

:

strcpy (name, xml::get_name (elem));

Example2

Complete example

Since

Version 2.1, R1014, 31. Oct. 2008

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

get_element

static int release(XMLElement xmlElement)

Release memory of an XMLElement variable allocated by calls to get_element, get_parent or get_child. If the script will use this variable in next statements, please reset it to 0.

Name	Type	Default	Description
Return	0 : element released otherwise : ErrorCode
xmlElement	XMLElement	-	Valid reference to an XML element of a document

XMLElement elem;

:

xml::release (elem);
elem = 0;

Example2

Complete example

Since

Version 2.1, R1014, 31. Oct. 2008

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

get_element

static int is_textlink(
  XMLElement xmlElement,
  int* startPos = 0,
  int* len = 0,
  int* isTable = 0,
  int* isInline = 0)

Does the element point to an piece of text of the document?

Name	Type	Default	Description
Return	0 : Element not valid, element has no content, content is a frame (text or grafic) 1 : Yes
xmlElement	XMLElement	-	Valid reference to an XML element of a document
startPos	int*	0	(Output, text-, table- and inline-elements only) Start position in text
len	int*	0	(Output, text-, table- and inline-elements only) Length of text
isTable	int*	0	(Output, text-, table- and inline-elements only) Element is linked against a table (1) or not (0)
isInline	int*	0	(Output, text-, table- and inline-elements only) Element is linked against a anchored frame (1) or not (0)

Example

Complete example

Since

Version 2.1, R1014, 31. Oct. 2008
startPos, len, isTable and isInline since version 2.1, R1166, 26. Feb. 2009

Available

priint:comet InDesign^® Plug-Ins

See Also

get_element

static int export_placeholder(
  DBC dbc = 0,
  int userID = 0,
  char* path = "",
  char* name = "")

Export the placeholder definitions of the database in a XML folder. If not otherwise specified, the export file contains the name placeholder.xml and is stored in the current XML data folder. The actions of the placeholder are stored in the folder actions alongside the file.
The command is only implemented for employees and partners of Werk II.

Name	Type	Default	Description
Return	int		0 or ErrorCode
dbc	DBC	0	Database from which the export is to be made 0 : Use the current database connection
userID	int	0	Only export the placeholders of this user. The current user ID of the connection can be ascertained using sql::userid. 0 : All placeholders will be exported independent of the user classification
path	String or char*	""	Entry path for the export. Empty string : Use the current XML data folder as it is set in inDesign®.
name	String or char*	""	Name of the XML folder. Empty string : placeholder.xml

Since

Version 1.1.7, January 2005

Available

priint:comet InDesign^® Plug-Ins

See Also

export_action
xmlquery::app_path
system::crypt
system::app_path
system::plugin_path

static int export_action(
  DBC dbc = 0,
  int actionID = 0,
  char* tbl = "",
  char* attr = "",
  char* xmlpath = "")

Export an action of the database in an encrpyted text file. Actions are always encoded and exported under the name actionID.crpt. If a file with this name already exists, it will be overwritten.
The command is only implemented for employees and partners of Werk II.

Name	Type	Default	Description
Return	int		0 or ErrorCode
dbc	DBC	0	Database from which the export is to be made 0 : Use the current database connection
actionID	int	-	ID of the action which is to be exported (select statement from actions where id = actionID)
xmlpath	String or char*	""	Entry path for the export. Empty string : The current path of the XML folder will be used, see xmlquery::app_path
subfolder	String or char*	"actions"	Subfolder in path, in which the action is to be stored.

Since

Version 1.1.7, January 2005

Available

priint:comet InDesign^® Plug-Ins

See Also

export_placeholder
system::crypt

static int export_actions(
  DBC dbc,
  char* selectCmd,
  char* xmlPath = "",
  char* subfolder = "actions")

Export a selection of actions of the database. Actions are always encoded and exported under the name actionID.crpt. If a file with this name already exists, it will be overwritten.
The command is only implemented for employees and partners of Werk II.

Name	Type	Default	Description
Return	int		0 or error code
dbc	DBC	-	Database from which the export is to be made 0 : Use the current database connection
selectCmd	String or char*	-	Complete select instruction to ascertain the IDs of the actions. The command must deliver the IDs of the ascertained actions in the first results column.
xmlpath	String or char*	""	Entry path for the export. Empty string : The current path of the XML folder will be used, see xmlquery::app_path
subfolder	String or char*	"actions"	Subfolder in path, in which the action is to be stored.

Export all actions of the database

xml::export_actions (0, "select id from actions where id > 0");

Since

Version 1.1.7, January 2005

Available

priint:comet InDesign^® Plug-Ins

See Also

export_action
export_placeholder
system::crypt

static int export_(
  DBC dbc,
  char* selectCmd,
  char* xmlPath,
  char* filename,
  char* root = "",
  char* parent = "",
  int lowerCase = 1)

General data export from the database in XML. The files will be created in the following format

<root>
 	<parent>
 		<ATTR>
 		</ATTR>
 		<!-- ... -->
 	</parent>
 	<!-- ... -->
</root>

The names for the root and the respective parent elements will either be ascertained from the file name or may be assigned as a parameter of the function. If the identifiers are ascertained, the file name will be used as the root name minus the file extension and as the parent name of the root name minus a letter.
If the file name is panelstatements.xml, the root element panelstatements will be named and the parent element in each case is called panelstatement.

The elements of the export are called the same as the columns of the Selects. With Oracle the columns names will be automatically delivered in upper case. The name can during export be converted into lowercase (Parameter lowerCase). If the name contains characters which do not comply with the XML identifier convention, these characters will be converted into underscores (_). Strings can be directly inserted in the Select for nesting the XML elements. Here is an example:

select a.id, '<Type>', d.id, d.name, '</Type>', a.name from ...

creates the following output for example

<id>123</id>
<Type>
 	<id>1</id>
 	<name>Type-name</name>
<Type>
<name>kahsgd<name>

Binary data of the database (BLOB) is exported in files. For the target in each case the subfolder filename/attribute will be used. This folder will be automatically created. For the file name, the ID of the dataset will be used. In the XML folder, the local path to the export file will be entered as XML attribute src so for example

<preview src='pageitems/preview/12.gif'></preview>.

For the folder names the conversion for the element names as previously described will be used.
In order that during the export the correct file types (file extensions for Windows, file types and creator and/or file extension for Mac OSX) will be created, classifications between table attributes and file extensions can be made.
For the export of constants such as select id, 1401, ..., for example, a column must be specified. Moreover, the value must be converted so that not decimal number is returned, because Oracle internally recognised such columns as decimal numbers :
select id, to_char (1401)"id2", ....

the classification between file extension and type/creator with Mac OSX is undertaken automatically in accordnace with the following listing.

File extension	Type	Creator	Program
indd	IDd3	InDn	InDesign®
psd	8BIM	8BIM	Photoshop
psd	8BPS
pict	PICT
tiff	TIFF
gif	GIFf
eps	EPSF
targa	TPIC
jpg	JPEG
psd	8BPS
png	PNGF
pdf	PDF	CARO	Acrobat Reader
txt	text	TEXT	TextEdit
rtf

Name	Type	Default	Description
Return	int		0 or ErrorCode
dbc	DBC	0	Database from which the export is to be made 0 : Use the current database connection
selectCmd	String or char*	-	Complete select instruction for ascertaining the data which is to be exported. In order that the names of the XML elements are unique, you should give names to the outpu columns of the select select c.name"color name", ... Special characters, points, empty spaces, ... will be replaced by '_' in the identifiers.
xmlpath	String or char*	""	entry path for the export. Empty string : The current path of the XML data will be used, see xmlquery::app_path
filename	String or char*	""	Name of the XML folders and the element in which the data is to be stored. The data name must have an extension (if possible .xml).
root	String or char*	"root"	Name of the root element of the XML folder Empty string : Use the name of the XML folder with file extension
parent	String or char*	""	Name of the element in which the data is to be stored Empty string : use the name of the XML folder with file extension and without the final letter (hopefully the s of the English plural.)
lowerCase	int	1	Are the names of the database attributes to be displayed in lower case? 1 : Use lowercase otherwise : Uppercase for the attribute names, column names in the select select (in double quotations after the attribute) remain unchanged.
attrXformat	String or char*	""	Allocations between table columns and file extensions consist of comma separated pairs attribute name file ending (without period), e.g. "Preview gif, Data indd". Empty string : All data will be exported in binary files (.bin).

Export some fields of the table panelstatements. The root element of the XML folder is called panelstatements. Data is written in each case in elements with the name panelstatement.

xml::export_ (
 	0,
 	"select id, description, statement from panelstatements where id > 0",
 	"",	// path from InDesign®
 	"panelstatements.xml");

Export some fields of the table panelstatements. The root element of the XML folder is called ROOT. Data is written in each case in elements with the name ENTRY. The database attribute panelstatements.description creates XML elements with the name description

xml::export_
 	0,
 	"select id, description\"Beschreibung\", statement from panelstatements where id > 0",
 	"",
 	"panelstatements.xml",
 	"ROOT",
 	"ENTRY");

xml::export 
 	0,
 	"select id, description, statement from panelstatements where id > 0",
 	"",	// path from InDesign®
 	"panelstatements.xml");

In order to export all values of a table, the asterisk * can be used to description the table attributes.Bear in mind that the name of all attributes are displayed in uppercase.

xml::export_ (
 	0,
 	"select *  from panelstatements where id >0",
 	"",
 	"panelstatements.xml")

Export all data of the table pageitems. In doing so the previews will be stored as gif images and the data will be stored as InDesign^® files.

xml::export_ (
 	0,
 	"select * from pageitems where id >0",
 	"",	// path from InDesign®
 	"pageitems.xml",
 	"",	// root <pageitems>
 	"",	// parent <pageitem>
 	1,	// lower case names
 	"Data indd, Preview gif")));

The following instructions export the data of the pageitems table in the format in which it is required by plugin templates.

 
int main ()
{
    char    cmd[2000];

    *cmd = 0;
    strcat (cmd, "select");
    strcat (cmd, "	p.id,");
    strcat (cmd, "	p.name,");
    strcat (cmd, "	p.description,");
    strcat (cmd, "	p.data,");
    strcat (cmd, "	p.preview,");
    strcat (cmd, "	'<type>', t.id, t.name, '</type>',");
    strcat (cmd, "	'<state>', s.id, s.value, '</state>',");
    strcat (cmd, "	'<domain>', d.id, d.name, '</domain>',");
    strcat (cmd, "	p.leftpos,");
    strcat (cmd, "	p.toppos,");
    strcat (cmd, "	p.rightpos,");
    strcat (cmd, "	p.bottompos");
    strcat (cmd, " from pageitems p, PageItemTypes t,");
    strcat (cmd, " RelatedTo s, Domain d");
    strcat (cmd, " where");
    strcat (cmd, "		p.id	> 0");
    strcat (cmd, "	and 	t.ID 	= p.TypeID");
    strcat (cmd, "	and 	s.ID 	= p.StateID");
    strcat (cmd, "	and 	d.ID	= p.DomainID");

    showmessage ("Export the PageItems : %s",
     	serror (xml::export_ (
     		0,
     		cmd,
     		"",
     		"pageitems.xml",
     		"",
     		"",
     		1,
     		"Data indd, Preview gif")));
    return 0;
}

Since

Version 1.1.7, January 2005

Available

priint:comet InDesign^® Plug-Ins

See Also

export_action
export_placeholder

Write the xml structure of all frames of the document to the logfile.

int wlevel (char * m1, char * m2, int level)
{
    int 			l		= 0;

    for (l = 0; l < level; l++)	wlog ("", "\t");
    if (m1)							wlog ("", "%s", m1);
    if (m1 && m2)					wlog ("", " ");
    if (m2)							wlog ("", "'%s'", m2);
    wlog ("", "\n");

    return 1;
}

int visit_xml (ItemRef frame, XMLElement elem, int level)
{
    int 			ix			= 0;
    int				iX;
    char			name 		[512];
    char			content 	[20000];
    int				pos, len;
    char			txt	 		[512];
    char			descr		[512];
    XMLElement		child		= 0;

    // Element name
    wlevel (xml::get_name (elem), 0, level);

    // Content
    xml::strcpy_elem (elem, txt, 511, &pos, &len);
    if (len >= 0)
    {
        sprintf (descr, "[%d, %d]", pos, pos+len);
        wlevel (descr, 0, level+1);
        wlevel (txt, 0, level+1);
    }

    // Attributes
    iX	= xml::count_attributes_elem (elem);
    if (iX)	wlevel ("Attributes", 0, level+1);
    for (ix = 0; ix < iX; ix++)
    {
        xml::sattribute_elem (elem, ix, name, content);
        wlevel (name, content, level+2);
    }

    // Recursive call for all children
    iX =  xml::count_children (elem);
    for (ix = 0; ix < iX; ix++)
    {
        if (xml::get_child (elem, ix, &child) == 0)
        {
            visit_xml (frame, child, level+1);
            xml::release (child);
            child = 0;
        }
    }

    // Ready
    return 0;
}

int main ()
{
    ItemList		frames	= itemlist::allframes (1, 0);
    ItemRef			frame	= item::alloc ();
    XMLElement		elem	= 0;
    int				len		= itemlist::length (frames);
    int				i		= 0;

    while (i < len)
    {
        itemlist::get (frames, frame, i++);
        if (xml::get_element (frame, &elem) == 0)
        {
            visit_xml (frame, elem, 0);
        }
    }

    xml::release (elem);
    item::release (frame);
    itemlist::release (frames);
    return 0;
}

Alphabetic index HTML hierarchy of classes or Java