Xml Plug-in Scripting Reference

Overview

The XML plugin implements a parser for editing XML text.

The XML can be displayed as a color coded, outlined, and selectable object.

This is similar to a Document Object Model (DOM) but visual, and easy to use.

Navigation through the document is done with unique ID numbers assigned to every element and attribute.

Messages: nodemove, nodechange, nodeselect

Nodemove is sent when the position of the xml object changes.

Nodechange is sent when the xml changes.

Nodeselect is sent when the selected elements or attributes change.

 

Commands and Functions

attachboundaryget, attachboundaryset

boundary $ = attachboundaryget(node name $)
attachboundaryset(node name $, boundary $)

These routines get or set the MIME boundary marker string.

The default value for this string is "--MIME_boundary".

attachcountget, attachcountset

total # = attachcountget(node name $)
attachcountset(node name $, total #)

These routines get or set the number of MIME or DIME attachments.

attachdataget, attachdataset

data $ = attachdataget(node name $, index #)
attachdataset(node name $, index #, data $)

These routines get or set the MIME or DIME binary data given the index of the attachment.

attachencodingget, attachencodingset

encoding $ = attachencodingget(node name $, index #)
attachencodingset(node name $, index #, encoding $)

These routines get or set the MIME or DIME encoding string given the index of the attachment.

For MIME attachments this is the "Content-Transfer-Encoding" header value.

attachidget, attachidset

id $ = attachidget(node name $, index #)
attachidset(node name $, index #, id $)

These routines get or set the MIME or DIME id string given the index of the attachment.

For MIME attachments this is the "Content-ID" header value.

attachlocationget, attachlocationset

location $ = attachlocationget(node name $, index #)
attachlocationset(node name $, index #, location $)

These routines get or set the MIME or DIME location string given the index of the attachment.

For MIME attachments this is the "Content-Location" header value.

attachstart, attachstop

data looks good TF = attachstart(node name $, attach data $)
attach data $ = attachstop(node name $)

Attachstart parses a block of binary data from a web transaction and initializes a new MIME or DIME package.

If you supply the empty string to attachstart then an empty MIME or DIME package is created.

If the data is not in MIME or DIME format then attachstart returns false.

After calling attachstart, the individual attachment information can be read, and the structure of the package can be edited.

Attachstop converts the MIME or DIME package to a block of binary data for use in a web transaction.

attachstyleget, attachstyleset

style $ = attachstyleget(node name $)
attachstyleset(node name $, style $)

These routines get or set the style of the attachment, either "MIME" or "DIME".

attachtypeget, attachtypeset

type $ = attachtypeget(node name $, index #)
attachtypeset(node name $, index #, type $)

These routines get or set the MIME or DIME location string given the index of the attachment.

For MIME attachments this is the "Content-Type" header value.

attribute2xpath, xpath2attribute

xpath $ = attribute2xpath(node name $, attribute ID #)
attribute ID # = xpath2attribute(node name $, xpath $)

Convert between an xpath string and an attribute id. This is useful for user specification of an XML attribute.

DreamFactory supports the subset of xpath syntax needed to select single XML attributes. Example:

theid = xml.xpath2attribute(myxml, "/root/brother[2]/child@attribute")

attributebrother

attribute ID # = attributebrother(node name $, attribute ID #)

Given an attribute ID, return the ID of the next attribute.

The value negative-one is returned if the attribute ID does not exist or there is no next attribute.

attributenameget, attributenameset

attribute name $ = attributenameget(node name $, attribute ID #)
attributenameset(node name $, attribute ID #, attribute name $)

Get or set the name of an attribute given the attribute's ID number.

Routines are available to get or set the name or value of elements or attributes.
See: elementnameset, elementnameget, elementvalueset, elementvalueget, attributevalueset, attributevalueget

attributenameselectget, attributenameselectset

select TF = attributenameselectget(node name $, attribute ID #)
attributenameselectset(node name $, attribute ID #, select TF)

Get or set the select property of an attribute name given the attribute's ID number.

This controls if the attribute name is currently inverted.

attributeowner

element ID # = attributeowner(node name $, attribute ID #)

Given an attribute ID, return the element ID which owns this attribute.

The value negative-one is returned if the attribute ID does not exist.

attributerefget, attributerefset

ref # = attributerefget(node name $, attribute ID #)
attributerefset(node name $, attribute ID #, ref #)

Get or set the attribute ref, which is a user definable property that sticks to the attribute.

attributetoindex, indextoattribute

index # = attributetoindex(node name $, attribute ID #)
attribute ID # = indextoattribute(node name $, element ID #, index #)

Given an element ID and an index between 1 and the number of attributes, indextoattribute returns the attribute ID of the attribute at that index.

Attributetoindex takes an attribute id and returns the index of that attribute relative to all of the attributes in that element.
See: countattributes

attributevalueget, attributevalueset

attribute value $ = attributevalueget(node name $, attribute ID #)
attributevalueset(node name $, attribute ID #, attribute value $)

Get or set the value of an attribute given the attribute's ID number.

All attributes must have a value.

Routines are available to get or set the name or value of elements or attributes.
See: elementnameset, elementnameget, elementvalueset, elementvalueget, attributenameset, attributenameget

attributevalueselectget, attributevalueselectset

select TF = attributevalueselectget(node name $, attribute ID #)
attributevalueselectset(node name $, attribute ID #, select TF)

Get or set the select property of an attribute value given the attribute's ID number.

This controls if the attribute value is currently inverted.

base2text, text2base

binary data $ = base2text(base 64 text $)
base 64 text $ = text2base(binary data $)

Convert text or binary data to base 64 text and back.

The base 64 format is used to encode MIME types in email and in SOAP envelopes for binary data.
See: binaryread, binarywrite

binaryread, binarywrite

binary data $ = binaryread(file name $)
binarywrite(file name $, binary data $)

Read or write a file with raw binary data.

This is useful for serving out graphics files, or transfering binary data.
See: base2text, text2base

binarysegment

binary data $ = binarysegment(binary data $, start #, stop #)

Grab a segment from any piece of data.

The start and stop are offsets into the given data, the result is the segment.

boundsget, boundsset

rectangle $ = boundsget(node name $)
boundsset(node name $, rectangle $)

Get or set the boundary rectangle of the object.

cleanup

tabbed xml text $ = cleanup(xml text $)

Cleans up and tabs parseable text to look like XML.

colortextget, colortextset

text has color TF = colortextget(node name $)
colortextset(node name $, text has color TF)

Turn on or off text coloring.

copyattribute, copyelement

text data $ = copyattribute(node name $, attribute ID #)
xml text $ = copyelement(node name $, element ID #)

Given an element id, copyelement returns the element and all children as text.

Given an attribute id, copyattribute returns the attribute and value as text.

countallattributes, indextoallattribute

total attributes # = countallattributes(node name $)
attribute ID # = indextoallattribute(node name $, index #)

These routines provide a convenient way to enumerate all the attributes and index through them.

Given an index between 1 and the total number of attributes, indextoallattribute returns the attribute ID of attribute at that index.

The attributes are not returned in any particular order.

countallelements, indextoallelement

total elements # = countallelements(node name $)
element ID # = indextoallelement(node name $, index #)

These routines provide a convenient way to enumerate all the elements and index through them.

Given an index between 1 and the total number of elements, indextoallelement returns the element ID of element at that index.

The elements are not returned in any particular order.

countattributes

attributes # = countattributes(node name $, element ID #)

Given an element ID, count the attributes this element has.
See: indextoattribute

countelements

elements # = countelements(node name $, father element ID #)

Given a father element ID, returns the number of attached children.

Use zero to count the number of top level children.
See: indextoelement

createattribute, createelement

createattribute(node name $, father element ID #, after index #)
createelement(node name $, father element ID #, after index #)

Given a father element ID and an index number, insert a blank element or attribute into the XML.

Use zero for the father ID of top-level elements. This is useful for building XML from scratch.
See: insertelement, insertattribute

data2hex, hex2data

hex string $ = data2hex(binary data $)
binary data $ = hex2data(hex string $)

These functions convert between binary data and hex strings.

Each byte of binary data will result in 2 text characters in hexadecimal format.

data2md5

binary data $ = data2md5(binary data $)

This function produces an MD5 hash of the given data.

The hash will be 16 bytes of binary information that represents a unique fingerprint of the original data.

This can be used to verify that data has not been corrupted or for web services security routines.

dataget, dataset

text data $ = dataget(node name $)
dataset(node name $, text data $)

Transform text data into XML.

Dataget returns the tabbed data with a return at the end of each line.

Dataset will return an error if the text is not parseable, test this beforehand with parseable or wellformed.

deleteattribute, deleteelement

deleteattribute(node name $, attribute ID #)
deleteelement(node name $, element ID #)

Given an element or attribute ID, delete that object.

Deleteelement will also delete all child elements!

element2xpath, xpath2element

xpath $ = element2xpath(node name $, element ID #)
element ID # = xpath2element(node name $, xpath $)

Convert between an xpath string and an element id. This is useful for user specification of an XML element.

DreamFactory supports the subset of xpath syntax needed to select single XML elements. Example:

theid = xml.xpath2element(myxml, "/root/brother[2]/child[@attribute='value']")

elementattribute

attribute ID # = elementattribute(node name $, element ID #)

Given an element ID, return the ID for the first attribute.

The value negative-one is returned if the element ID does not exist or there is no child attribute.

elementbrother

element ID # = elementbrother(node name $, element ID #)

Given an element ID, return the brother element ID.

The value negative-one is returned if the element ID does not exist or there is no brother element.

elementchild

element ID # = elementchild(node name $, element ID #)

Given an element ID, return the element ID of the child element.

Use an element ID of zero to specify the top-level element.

The value negative-one is returned if the element ID does not exist or there is no child element.

elementfather

element ID # = elementfather(node name $, element ID #)

Given an element ID, return the element ID for the father element. This will be zero for top-level elements.

The value negative-one is returned if the element ID does not exist or there is no father element.

elementisopenget, elementisopenset

is open TF = elementisopenget(node name $, element ID #)
elementisopenset(node name $, element ID #, is open TF)

Get or set the open property of an element given the element's ID number.

This controls the outlining open and closed state.

elementnameget, elementnameset

element name $ = elementnameget(node name $, element ID #)
elementnameset(node name $, element ID #, element name $)

Get or set the name of an element given the element's ID number.

Routines are available to get or set the name or value of elements or attributes.
See: elementvalueset, elementvalueget, attributenameset, attributenameget, attributevalueset, attributevalueget

elementnameselectget, elementnameselectset

select TF = elementnameselectget(node name $, element ID #)
elementnameselectset(node name $, element ID #, select TF)

Get or set the select property of an element name given the element's ID number.

This controls if the element name is currently inverted.

elementrefget, elementrefset

ref # = elementrefget(node name $, element ID #)
elementrefset(node name $, element ID #, ref #)

Get or set the element ref, which is a user definable property that sticks to the element.

elementstyleget, elementstyleset

element style $ = elementstyleget(node name $, element ID #)
elementstyleset(node name $, element ID #, element style $)

Get or set the style of an element given the element's ID number.

Available styles include: envelope, content, empty, processing, comment, DOCTYPE, CDATA, ENTITY, NOTATION, ELEMENT, ATTLIST, and reference.

envelope: < ...whatever... >
content: content
empty:
processing:
comment:
DOCTYPE:
CDATA:
ENTITY:
NOTATION:
ELEMENT:
ATTLIST:
reference: &whatever;

elementtoindex, indextoelement

index # = elementtoindex(node name $, element ID #)
element ID # = indextoelement(node name $, father element ID #, index #)

Given a father element ID and an index between 1 and the number of child elements, indextoelement returns the element ID of child element at that index.

Use zero for the father ID of top-level elements.

Elementtoindex takes an element id and returns the index of that element relative to all brothers of that element.
See: countelements

elementvalueget, elementvalueset

element value $ = elementvalueget(node name $, element ID #)
elementvalueset(node name $, element ID #, element value $)

Get or set the value of an element given the element's ID number.

These routines either get or set the value of the element as a text string.

If the element style is "content" then elementvalueget will return a text string.

If the element style is "empty" then elementvalueget will return an empty string.

If the element style is "envelope" then elementvalueget will return the enclosed XML data as text.

If the given source value looks like a text string, then elementvalueset will insert the string and the element style will become "content".

If the given source value looks like XML data, then elementvalueset will insert the XML data and the element style will become "envelope".

Routines are available to get or set the name or value of elements or attributes.
See: elementnameset, elementnameget, attributenameset, attributenameget, attributevalueset, attributevalueget

elementvalueselectget, elementvalueselectset

select TF = elementvalueselectget(node name $, element ID #)
elementvalueselectset(node name $, element ID #, select TF)

Get or set the select property of an element value given the element's ID number.

This controls if the element value is currently inverted.

enabledget, enabledset

enabled TF = enabledget(node name $)
enabledset(node name $, enabled TF)

Get or set the enabled property of the xml. If enabled, the xml inverts selected elements and attributes.
See: elementnameselectset, elementvalueselectset, attributenameselectset, attributevalueselectset

escape2text, text2escape

text $ = escape2text(escaped text $)
escaped text $ = text2escape(text $)

Convert a text string to a URL encoded escape sequence, or an escape sequence back to a text string.

Escaping a string removes control characters and converts reserved, non-ascii, and unsafe characters to hexadecimal notation.

Escape sequences are often required by browsers or other agents that handle URLs.

URL parameters are also often supplied by the browser in escaped format.

file2gzip, gzip2file

file2gzip(file name $, gzip file $)
gzip2file(gzip file $, file name $)

These functions convert between binary gzip format files and regular files.

This is useful for general purpose compression and for implementing the gzip encoding format for web services transactions.

fillcolorget, fillcolorset

fill color $ = fillcolorget(node name $)
fillcolorset(node name $, fill color $)

Get or set the fillcolor for the XML.

fillget, fillset

fill TF = fillget(node name $)
fillset(node name $, fill TF)

Get or set if the background is filled or transparent.

findattributebrother

attribute ID # = findattributebrother(node name $, attribute ID #, attribute name $)

Given an attribute ID and an attribute name, return the next brother attribute ID with that name.

Findattributebrother returns negative-one if there is no such brother attribute following the given attribute.

Use an asterisk * at the start or end of the search string for a wildcard namespace match.
See: findattributename, findattributevalue, findattributechild

findattributechild

attribute ID # = findattributechild(node name $, father element ID #, attribute name $)

Given a father element ID and an attribute name, return the child attribute ID with that name.

Findattributechild returns negative-one if there is no such attribute belonging to the father element.

Use an asterisk * at the start or end of the search string for a wildcard namespace match.
See: findattributename, findattributevalue, findattributebrother

findattributename

attribute ID # = findattributename(node name $, attribute name $)

Given an attribute name, return an attribute ID with that name. There could be other attributes with that name in the XML data.

Findattributename returns negative-one if there is no such attribute.

Use an asterisk * at the start or end of the search string for a wildcard namespace match.
See: findattributechild, findattributebrother, findattributevalue

findattributevalue

attribute ID # = findattributevalue(node name $, attribute value $)

Given an attribute value, return an attribute ID with that name. There could be other attributes with that value in the XML data.

Findattributevalue returns negative-one if there is no such attribute.

Use an asterisk * at the start or end of the search string for a wildcard namespace match.
See: findattributechild, findattributebrother, findattributename

findelementbrother

element ID # = findelementbrother(node name $, element ID #, element name $)

Given an element name, and an element ID, return the next brother element ID with that name.

Findelementbrother returns negative-one if there is no such brother element following the given element.

Use an asterisk * at the start or end of the search string for a wildcard namespace match.
See: findelementname, findelementvalue, findelementchild

findelementchild

element ID # = findelementchild(node name $, father element ID #, element name $)

Given an element name, and a father element ID, return the child element ID. There could be other elements with that name in the XML data.

Findelementchild returns negative-one if there is no such element.

Use an asterisk * at the start or end of the search string for a wildcard namespace match.
See: findelementname, findelementvalue, findelementbrother

findelementname

element ID # = findelementname(node name $, element name $)

Given an element name, return the element ID. There could be other elements with that name in the XML data.

Findelementname returns negative-one if there is no such element.

Use an asterisk * at the start or end of the search string for a wildcard namespace match.
See: findelementchild, findelementbrother, findelementvalue

findelementvalue

element ID # = findelementvalue(node name $, element value $)

Given an element value, return the element ID. There could be other elements with that value in the XML data.

Findelementvalue returns negative-one if there is no such element.

Use an asterisk * at the start or end of the search string for a wildcard namespace match.
See: findelementchild, findelementbrother, findelementname

fontnameget, fontnameset

font name $ = fontnameget(node name $)
fontnameset(node name $, font name $)

Get or set the font name for the XML.

fontsizeget, fontsizeset

font size # = fontsizeget(node name $)
fontsizeset(node name $, font size #)

Get or set the font size for the XML.

fullget, fullset, infoget, infoset

full $ = fullget(node name $)
fullset(node name $, full $)
info $ = infoget(node name $)
infoset(node name $, info $)

Get or set XML data that describes all the settings for this node.

The fullget and fullset routines have a header element with appropriate namespaces, infoget and infoset are an XML snippet for access as a property. Example:

mynode.info.title = "new title"

handlesget, handlesset

handles TF = handlesget(node name $)
handlesset(node name $, handles TF)

Turn on or off dragable handles for reshaping the node.

This routine is used by the system tool palettes for manual positioning.
See: markersget, markersset, partget, partset

hashstring

hash # = hashstring(text string $)

Given a string, return a unique, consistent, case-insensitive hash value for that string.

The same string will always generate the same hash value, so this is useful for remembering and testing passwords.

hittest

hit info $ = hittest(node name $, hor #, ver #)

Returns an XML string with the type, ID, and part clicked on.

The type is "element" or "attribute", the ID is the element or attribute ID, and the part is "name", "value", or "arrow."

If nothing is hit the type is "none" and the other elements are empty.

This allows hit testing of the XML for selecting elements and attributes.

insertattribute, insertelement

new attribute ID # = insertattribute(node name $, father element ID #, after index #)
new element ID # = insertelement(node name $, father element ID #, after index #)

Given a father element ID and an index number, insert a blank element or attribute into the XML.

The newly created attribute or element id is returned.

Use zero for the father ID of top-level elements. This is useful for building XML from scratch.

leadingget, leadingset

text leading # = leadingget(node name $)
leadingset(node name $, text leading #)

Get or set the leading, which is extra pixels between every line of text.

linecolorget, linecolorset

line color $ = linecolorget(node name $)
linecolorset(node name $, line color $)

Get or set the color of the line around the XML.

linesizeget, linesizeset

linesize # = linesizeget(node name $)
linesizeset(node name $, linesize #)

Get or set the linesize, which is the border around the XML.

markersget, markersset

markers TF = markersget(node name $)
markersset(node name $, markers TF)

Turn on or off the node outline to show selection.

This routine is used by the system tool palettes to show that a node is selected.
See: handlesset, handlesget, partget, partset

multiselectget, multiselectset

multiselect TF = multiselectget(node name $)
multiselectset(node name $, multiselect TF)

Turns on or off multiple selection of elements and attributes.

parseable, wellformed

XML can be parsed TF = parseable(text data $)
XML is well formed TF = wellformed(text data $)

Returns true if the XML is parseable or wellformed.

Parseable means that the text can be turned into XML without error.

Wellformed means that the text can be turned into standard well-formed XML, a stricter requirement.

parseableerror, wellformederror

error string $ = parseableerror(text data $)
error string $ = wellformederror(text data $)

Returns an error string for the text, or "No errors." if the string is OK.

Wellformederror is stricter and more likely to return an error.

parseableoffset, wellformedoffset

error offset # = parseableoffset(text data $)
error offset # = wellformedoffset(text data $)

Returns an error offset for the text, or -1 if there is no error.

Wellformederror is stricter and more likely to return an error.

partget, partset

part # = partget(node name $, hor #, ver #)
partset(node name $, hor #, ver #, part #)

Get or set the points for an individual handle.
See: markersget, markersset, handlesset, handlesget

pasteattribute, pasteelement

new attribute ID # = pasteattribute(node name $, father element ID #, after index #, text data $)
new element ID # = pasteelement(node name $, father element ID #, after index #, xml text $)

Given a father element ID, an index number, and some XML text, pasteelement inserts the XML at the given position.

Given a father element ID, an index number, and some attribute text, pasteattribute adds the attribute to the given element. Example:

newid = xml.pasteelement("myxml", elementid, 3, xml.dataget("otherxml"))

reset

reset(node name $)

Resets the height of the XML to include all items. This is useful for scrolling.

styleget, styleset

style name $ = styleget(node name $)
styleset(node name $, style name $)

Get or set the presentation style of the XML.

Available styles include: outline, standard, and cascade.

Outline and cascade have controls at left for opening and closing tabbed elements.

tabwidthget, tabwidthset

tab width # = tabwidthget(node name $)
tabwidthset(node name $, tab width #)

Get or set the tab width for the XML.

text2xml, xml2text

xml string $ = text2xml(text data $)
text data $ = xml2text(xml string $)

Convert DreamFactory text to XML safe text, and back, by using references.

Example, the Dreamfactory string "I don't know..." will become the XML-safe string "I dont't know..."

titlehorget, titlehorset

title hor # = titlehorget(node name $)
titlehorset(node name $, title hor #)

Get or set the title horizontal offset of every line of text.

titleverget, titleverset

title ver # = titleverget(node name $)
titleverset(node name $, title ver #)

Get or set the title vertical offset of every line of text.

There must be some leading at the bottom of the line for the text to be moved down.

unload

unload(node name $)

Unload de-allocates temporary memory used for editing the XML.

When this happens you will loose the currrent outlining and hiliting information, and ID's may change.

Unload when you are finished with the XML, the default XML script unloads when the node is hidden.

validname

name looks good TF = validname(the name $, element style $)

Returns true if the name can be used for the given style of element. Example:

xml.validname("bad ]]> text", "CDATA")

This is to protect your XML's wellformedness while editing if desired.

See: elementstyleset, elementstyleget

validurl

URL looks good TF = validurl(url text $)

Returns true if the string looks like a URL. Example:

xml.validurl("http://www.DreamFactory.com/index.html")