## E[x]TENSIBLE [m]ARKUP [l]ANGUAGE This class is dedicated to the management of XML structures in Document Object Model (DOM) mode. ## Summary This class is intended to work with the [enhanced XPath support](https://blog.4d.com/enhanced-xpath-support) available since version 18R3. ### Properties |Properties|Type|Description|Initial value| |---------|:----:|------|:------:| |**.root**|Text|The DOM tree reference in memory of the document virtual structure|**Null**| |**.autoClose**|Boolean|Indicates whether the XML tree should be automatically closed after a call to one of the functions: `.getText()`, `.getContent()` or `. save()`|**True\*** 🚨| |**.file**|**4D**.File|The disk file of the last `.save()` or `.load()`call|**Null**| |**.success**|Boolean|Indicates whether a function call was successfully executed| |**.errors**|Collection|The list of errors encoutered, if so|[ ]| |**.xml**|Text|The XML tree as text generated during the last call to the `.getText()` function.|**Null**| |**.convert**|Boolean|When `True`, `.toObject()` converts element/attribute text values to their 4D type (boolean, number, JSON collection). When `False`, values are kept as text.|**True**| \* 🚨 If `.autoClose` is set to **False** (or if you don't call a function that automatically closes the structure), once you no longer need the structure, remember to call the function `.close()` in order to free up the memory. > πŸ“Œ With the exception of functions that return a specific result (getter function), each call returns the original `cs.xml` object, and you can include one call after another. ### Document functions |Function|Action| |--------|------| |.**newRef** ({root : `Text`} {; nameSpaceName : `Text`} {; nameSpaceName1 : `Text`; nameSpaceValue1 : `Text`} … {; nameSpaceNameN : `Text` ; nameSpaceValueN : `Text`} ) β†’ `cs.xml` | Create a new XML tree in memory |.**setDeclaration** ( {encoding : `Text`} {; standalone : `Boolean`} ) | Sets the XML declaration (encoding and `standalone`) of the tree. Called without parameters, defaults to `"UTF-8"` and `False`. |.**setOption** ( selector : `Integer` ; value : `integer` ) β†’ `cs.xml` | Modify the value of one XML option for the structure |.**setOptions** ( selector : `Integer` ; value : `integer` … {selectorN : `Integer` ; valueN : `integer`}) β†’ `cs.xml` | Modify the value of one or more XML options for the structure |.**parse** ( value : `Text` {; validate : `Boolean` {; schema : `Text`}} ) β†’ `cs.xml`
.**parse** ( value : `Blob` {; validate : `Boolean` {; schema : `Text`}} ) β†’ `cs.xml` | Parses a BLOB or Text type variable containing an XML structure |.**open** ( file : `4D.File` {; validate : `Boolean` {; schema : `Text`}} ) β†’ `cs.xml` | Parses a document containing an XML structure |.**load** ( source : `Text` \| `Blob` \| `4D.File` {; validate : `Boolean` {; schema : `Text`}} ) β†’ `cs.xml` | Loads an XML structure from a `Text`/`Blob` variable or a file. Releases the current tree (calls `.close()`) before loading. |.**save** () β†’ `cs.xml`
.**save** ( {file : `4D.File`} {; keepStructure : `Boolean`}) β†’ `cs.xml` | Saves the XML structure to a document. If no file is provided and no previous `.file` is available, a save dialog is opened. |.**close** ( ) β†’ `cs.xml` | Close the XML tree (Release the memory) |.**getText** ({keepStructure : `Boolean`}) β†’ `Text` | Returns the XML tree as text |.**getContent** ({keepStructure : `Boolean`}) β†’ `Blob` | Returns the XML tree as BLOB |.**toObject** ({withAdresses : `Boolean`}) β†’ `Blob` | Returns the XML structure as Object.
If withAdresses is True, an attribute `@` is populated for each element with it's XML reference. |.**toList** (counter : `Pointer` ; xpath : `Text`) β†’ `Integer`
.**toList** (counter : `Pointer` ; nodeRef : `Text`) β†’ `Integer`
.**toList** (counter : `Pointer` ; xpath : `Text` ; nodeRef : `Text`) β†’ `Integer` | Returns a hierarchical list from the XML tree.
Each item of the list includes as item parameters: its `value`, its `xpath` & its `dom` reference.
β€’ To ensure the uniqueness of the references of the list elements, you must initialize a counter and pass a pointer as the 1st parameter of the function.
β€’ The `xpath` parameter can be the root name of the XML tree or an absolute path. ### Elements functions |Function|Action| |--------|------| |.**create** ( XPath : `Text` {; attributes `Object | Collection`} ) β†’ `cs.xml`
.**create** ( target : `XML Ref`; XPath : `Text` {; attributes `Object | Collection`} ) β†’ `cs.xml` | Creates a new element in the `target` element or the `root` if omitted |.**copy** ( {target : `XML Ref`} ) β†’ `cs.xml` | Returns a new `cs.xml` object that is a deep copy of the `target` element (or the whole tree if omitted). |.**append** ( target : `XML Ref`; source : `XML Ref` ) β†’ `cs.xml` | Appends a source element to the `target` element |.**appendChild** ( target : `XML Ref`; type : `Integer`; value : `Variant` ) β†’ `XML Ref` | Appends a child node to the target (e.g. `XML DATA`, `XML comment`, processing instruction). Wrapper around DOM Append XML child node. |.**comment** ( target : `XML Ref`; comment : `Text` ) β†’ `XML Ref` | Appends a comment node to the `target` element. |.**insert** ( target : `XML Ref`; source : `XML Ref` {; index : `Integer`} ) β†’ `cs.xml` | Inserts a source element among the children elements of the `target` element. |.**clone** ( source : `XML Ref`; target : `XML Ref` {; index : `Integer`} ) β†’ `cs.xml` | Makes a copy of the `source` element in the `target` after the last child. |.**remove** ( node : `XML Ref`) β†’ `cs.xml` | Removes the element referenced by `node` |.**getName** ( node : `XML Ref`) β†’ `Text` | Returns the name of the element referenced by `node` |.**setName** ( node : `XML Ref` ; name : `Text`) β†’ `Text` | Sets the name of the element referenced by `node` |.**getValue** ( node : `XML Ref`) β†’ `Variant` | Returns the of the element referenced by `node` |.**setValue** ( node : `XML Ref` ; value : `Variant`{; inCDATA : `Boolean`}) β†’ `cs.xml` | Modifies the value of the element referenced by `node` |.**getAttribute** ( node : `XML Ref` ; attribute : `Text`) β†’ `Variant` | Returns the attribute value of the element referenced by `node`. **Null** if attribute doesn't exists |.**popAttribute** ( node : `XML Ref` ; attribute : `Text`) β†’ `Variant` | Returns an attribute value of the element referenced by `node` & remove it |.**getAttributes** ( node : `XML Ref` ) β†’ `Object` | Returns a node attributes as object |.**getAttributesCollection** ( node : `XML Ref` ) β†’ `Collection` | Returns the collection of attributes of an element (key/values objects) |.**setAttribute** ( node : `XML Ref` ; attribute : `Text` ; value :`Variant` ) β†’ `cs.xml` | Sets a node's attribute |.**setAttributes** ( node : `XML Ref` ; attribute : `Object`\|`Collection` ) β†’ `cs.xml` | Sets a node's attributes from an object or a collection (key/value pairs) |.**removeAttribute** ( node : `XML Ref` ; attribute : `Text` ; value :`Variant` ) β†’ `cs.xml` | Removes an attribute, if exists ### Naviguation functions |Function|Action| |--------|------| |.**parent** ( node : `XML Ref` {; name : `Text`}) β†’ `XML Ref`| Returns a reference to the parent of a node.
If a name is passed, goes up in the hierarchy to find the named element |.**firstChild** ( {node : `XML Ref`} {; name : `Text`}) β†’ `XML Ref`| Returns a reference to the first β€œchild”.
If the node's reference isn't passed, return the first child of the root.
If a name is passed, looks for the first child with that name |.**lastChild** ( {node : `XML Ref`} {; name : `Text`}) β†’ `XML Ref`| Returns a reference to the last β€œchild”.
If the node's reference isn't passed, return the last child of the root.
If a name is passed, looks for the last child with that name |.**childrens** ( {node : `XML Ref`} ) β†’ `Collection`| Returns the list of the childs' references of a node or root if omitted |.**descendants** ( {node : `XML Ref`} ) β†’ `Collection`| Returns descendant element references (children and deeper). Text/data child nodes are not returned. |.**nextSibling** ( node : `XML Ref` {; name: `Text`} ) β†’ `Collection`| Returns a reference to the next β€œsibling”.
If a name is passed, looks for the first sibling with that name |.**previousSibling** ( node : `XML Ref` {; name: `Text`} ) β†’ `Collection`| Returns a reference to the previous β€œsibling”.
If a name is passed, looks for the next previous sibling with that name ### Search |Function|Action| |--------|------| |.**findById** ( id : `Text`) β†’ `XML Ref` | Search for an element by its id |.**findByXPath** ( XPath : `Text` {; node : `Text`}) β†’ `XML Ref` | Looks for the 1st element corresponding to an XPath & returns its reference if success. |.**find** ( XPath : `Text`) β†’ `Collection`
.**find** ( node : `Text` ; XPath : `Text`) β†’ `Collection` | Searches for one or more elements corresponding to an XPath & returns a references collection if success. |.**findByName** ( name : `Text`) β†’ `Collection`
.**findByName** ( target : `Text` ; name : `Text`) β†’ `XML Ref` | Searches for elements by there name & returns a references collection if success. |.**findByAttribute** ( name : `Text`; attribute : `Text` {; value : `Text`}) β†’ `Collection`
.**findByAttribute** ( attribute : `Text` {; value : `Text`}) β†’ `Collection` | Searches for elements by there attribute. |.**findOrCreate** ( target : `XML Ref`; name : `Text`) β†’ `XML Ref`| Searches for an element by name and creates it if it is not found. ### Miscellaneous |Function|Action| |--------|------| |.**isReference** ( text : `Text`) β†’ `Boolean` | Returns **True** if text seams to be a XML Reference (8 coded characters in hexadecimal form) |.**isNull** ( reference : `XML Ref`) β†’ `Boolean` | Returns **True** if reference is a sequence of 32 zero "0" characters |.**isNotNull** ( reference : `XML Ref`) β†’ `Boolean` | Returns **True** if reference is not a sequence of 32 zero "0" characters ## πŸ”Έ cs.xml.new() The class constructor `cs.xml.new()` can be called without parameters to create an empty XML tree in memory. >`cs.xml.new() The class constructor also accepts an optional parameter, so you can create a XML tree by passing a 4D.File, a Blob variable or a Text variable. >`cs.xml.new(4D.file)` Loads & parses the file content >`cs.xml.new(Blob)` Parses the blob variable content >`cs.xml.new(Text)` Parses the text variable content ## πŸ”Ή .newRef() >. newRef() β†’ `cs.xml` >. newRef( rootName : `Text`) β†’ `cs.xml` ## πŸ”Ή .create() >.create( XPath : `Text` {; attributes `Object | Collection`} ) β†’ `cs.xml` Creates a new element in the root >.create( target : `XML Ref`; XPath : `Text` {; attributes `Object | Collection`} ) β†’ `cs.xml` Creates a new element in the target element `attributes` are attribute/value pairs. It can be an object or a collection. [see .setAttributes()] ## πŸ”Ή .appendChild() >.appendChild( target : `XML Ref`; type : `Integer`; value ) β†’ `XML Ref` Appends a child node to the target node. Typical `type` values are XML constants such as `XML DATA`, `XML comment`, or processing-instruction type values. This helper exists to avoid direct DOM command usage in subclasses when appending non-element child nodes. ## πŸ”Ή .save() >.save() β†’ `cs.xml` Saves the current XML tree. Behavior without parameter: - If `.file` is already defined (from `.open()` or a previous `.save()`), this file is reused. - If `.file` is not defined, a save dialog is displayed to let the user choose a destination file. - If the user validates the dialog, the selected file is stored in `.file` and used for saving. - If the user cancels, `.save()` returns with `.success = False` and an error entry (`File is not defined`). >.save(file : `4D.File` {; keepStructure : `Boolean`}) β†’ `cs.xml` Saves to the provided file directly, without opening a dialog. `keepStructure` controls whether the in-memory DOM remains open when `.autoClose` is enabled. ## πŸ”Ή .setAttributes() >.setAttributes( target : `XML Ref`; attribute : `Text` ; value ) β†’ `cs.xml` Set one attribute for the target element >.setAttributes( target : `XML Ref`; attributes : `Object` ) β†’ `cs.xml` Defines one or more attributes for the target element from a definition object.
Each property corresponding to an attribute name stores the value of the attribute. >.setAttributes( target : `XML Ref`; attributes : `Collection` ) β†’ `cs.xml` Defines one or more attributes for the target element from a collection.
Each element of the collection is an object with "key" and "value" properties.