build-xml
Helper library for building XML DOMs
Example
import { DOMParser } from '@xmldom/xmldom';
import { buildXmlDom, makeElementCreator } from '@qdabra/build-xml';
const parser = new DOMParser();
// use an element creator to create elements in a given namespace
const makeCatElement = makeElementCreator('http://example.qdabra.com/catalog', 'cat');
const makeNoteElement = makeElementCreator('http://example.qdabra.com/notation', 'note');
const makeBook = (title, publishDate) => makeCatElement('Book', {
attributes: {
title,
author,
publishDate,
},
});
const doc = buildXmlDom((doc) =>
// root element
makeCatElement(doc, 'Catalog', {
children: [
// child element
makeCatElement(doc, 'Books', {
children: [
makeBook(doc, 'The Great Gatsby', 'F. Scott Fitzgerald', '1925'),
makeBook(doc, 'Où es-tu', 'Marc Levy', '2001'),
makeBook(doc, '君の名は。', '新海誠', '1996'),
],
}),
makeNoteElement(doc, 'Comment', {
text: 'Last updated: 2023-08-25',
}),
],
// namespace declarations
namespaces: {
'cat': 'http://example.qdabra.com/catalog',
'note': 'http://example.qdabra.com/notation',
},
}),
// pass any DOM compliant parser here
// can be omitted in browsers
{ parser },
);
Result
<cat:Catalog xmlns:cat="http://example.qdabra.com/catalog" xmlns:note="http://example.qdabra.com/notation">
<cat:Books>
<cat:Book title="The Great Gatsby" author="F. Scott Fitzgerald" publishDate="1925"/>
<cat:Book title="Où es-tu" author="Marc Levy" publishDate="2001"/>
<cat:Book title="君の名は。" author="新海誠" publishDate="1996"/>
</cat:Books>
<note:Comment>Last updated: 2023-08-25</note:Comment>
</cat:Catalog>
Functions
buildXmlDom
buildXmlDom(
buildRoot: (DOMDocument) -> Element | Node[],
options?: BuildDomOptions,
) -> DOMDocumentBuilds an XML DOM using the provided root creation function.
The provided function should either return a single DOMElement or an array of nodes including one DOMElement and other non-element nodes that are permitted at the root of an XML document (comments, processing instructions, etc.)
The element returned from the buildRoot function can contain further child nodes, etc., essentially representing an entire node tree, and this is the intended way to use this function.
This function will use the DOMParser provided in options to create the DOM document. If none is provided, it will attempt to create one with window.DOMParser.
Returns A DOM document containing the returned node(s)
Example:
const childNames = ['a', 'b', 'c'];
const makeChild = (dom) => (name) => createElement(
dom,
null,
name,
);
/*
<myDocument>
<a />
<b />
<c />
</myDocument>
*/
const myDocument = buildXmlDom(
(dom) => createElement(
dom,
null,
'myDocument',
{
children: childNames.map(makeChild(dom)),
},
),
);createElement
createElement(
dom: DOMDocument,
namespaceURI: string,
qualifiedName: string,
options? CreateElementOptions,
) -> DOMElementCreates a single DOM element with the specified namespace and name.
For elements that are not in a namespace, specify null for the namespaceURI.
If the name includes a prefix, include the prefix in the value specified for qualifiedName.
See below for more details about CreateElementOptions.
Returns: the created element
Example:
const NS_XSL = 'http://www.w3.org/1999/XSL/Transform';
/*
<xsl:template name="MyTemplate" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:text>Some Text</xsl:text>
</xsl:template>
*/
const xslTemplateElement = createElement(
dom,
NS_XSL,
'xsl:template',
{
attributes: {
name: 'MyTemplate',
},
children: [
createElement(
dom,
NS_XSL,
'xsl:text',
{
text: 'Some Text',
},
),
],
},
);makeElementCreator
makeElementCreator(
namespaceURI?: string,
prefix?: string,
) -> ElementCreatorCreates a function which is similar to createElement, but which allows omitting the namespace URI and prefix. Useful when you want to create different elements in the same namespace.
You can omit both arguments to make an element creator for elements with no namespace.
Returns: an element creation function
Example
const makeXslElement = makeElementCreator(
'http://www.w3.org/1999/XSL/Transform',
'xsl',
);
/*
<xsl:template name="MyTemplate" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:text>Some Text</xsl:text>
</xsl:template>
*/
const xslTemplateElement = makeXslElement(
dom,
'template',
{
attributes: {
name: 'MyTemplate',
},
children: [
makeXslElement(
'text',
{
text: 'Some Text',
},
),
],
},
);makeEmptyDom
makeEmptyDom(
parser?: DOMParser,
) -> DOMDocumentCreates a new DOMDocument with no nodes, using the given parser.
If no parser is given, will attempt to create one with window.DOMParser.
Returns: The created DOM document
Example:
const myDom = makeEmptyDom();makeProcessingInstruction
makeProcessingInstruction(
dom: DOMDocument,
name: string,
attributes: Record<string, string>,
) -> DOMProcessingInstructionCreates a new processing instruction with the provided pseudo-attributes.
Returns: The created processing instruction
Example:
/*
<?Book title="Love means never having to say "I'm sorry"" author="John Doe"?>
*/
const myPi = makeProcessingInstruction(
dom,
'Book',
{
title: `Love means never having to say "I\'m sorry"`,
author: "John Doe",
},
);parseXmlString
parseXmlString(
xmlString: string,
parser?: DOMParser,
) -> DOMDocumentParses the specified XML string into an XML document.
If no parser is given, will attempt to create one with window.DOMParser.
Returns: the parsed document
Example:
const myDoc = parseXmlString('<Books><Book>Lord of the Rings</Book><Book>The Prince and the Pauper</Book></Books>');Interfaces
CreateElementOptions
{
children?: Node[];
attributes?: Record<string, string>;
text?: string;
namespaces?: Record<string, string>;
nsAttributes?: Record<string, Record<string, string>>;
}Passed to createElement() or to element creators created using makeElementCreator.
children - array of children to append to the created element
attributes - a set of key-value pairs for the names and values of non-namespace attributes to add to the element
text - text content to add within the element. Any child nodes specified in children will be appended after the given text.
namespaces - a set of key value pairs for namespace prefixes and namespace URIs, to be added as namespace declarations on the element
nsAttributes - key value pairs where the keys are namespace URIs, and the values are key-value collections of attribute names and values.
Example:
const NS_XSI = "http://www.w3.org/2001/XMLSchema-instance";
const NS_XSD = "http://www.w3.org/2001/XMLSchema";
{
[NS_XSI]: {
'xsi:schemaLocation': './myschema.xsd',
'xsi:nil': 'true',
},
[NS_XSD]: {
'xsd:type': 'xsd:string',
},
}BuildDomOptions
{
parser?: DOMParser;
}Passed to buildXmlDom to indicate a parser to use when creating the DOM.
ElementCreator
(
dom: Document,
localName: string,
options?: CreateElementOptions,
) -> Element;The signature of functions created with makeElementCreator().
This is similar to the signature of makeElement(), but does not have a namespaceURI parameter, and has a localName parameter instead of a qualifiedName parameter.