What is xmlcreate?
The xmlcreate npm package is a lightweight library for creating XML documents in a programmatic way. It provides a simple API to build XML structures, making it easy to generate XML content dynamically.
What are xmlcreate's main functionalities?
Creating XML Documents
This feature allows you to create a new XML document with a specified version and encoding. You can then add elements to the document, including nested elements.
const { document } = require('xmlcreate');
const doc = document({ version: '1.0', encoding: 'UTF-8' });
const root = doc.element({ name: 'root' });
root.element({ name: 'child', text: 'Hello, World!' });
console.log(doc.toString());
Adding Attributes to Elements
This feature allows you to add attributes to XML elements. In this example, an 'id' attribute is added to the 'child' element.
const { document } = require('xmlcreate');
const doc = document({ version: '1.0', encoding: 'UTF-8' });
const root = doc.element({ name: 'root' });
const child = root.element({ name: 'child', text: 'Hello, World!' });
child.attribute({ name: 'id', value: '1' });
console.log(doc.toString());
Pretty Printing XML
This feature allows you to output the XML document in a pretty-printed format, making it more readable.
const { document } = require('xmlcreate');
const doc = document({ version: '1.0', encoding: 'UTF-8' });
const root = doc.element({ name: 'root' });
root.element({ name: 'child', text: 'Hello, World!' });
console.log(doc.toString({ pretty: true }));
Other packages similar to xmlcreate
xmlbuilder
xmlbuilder is another popular library for building XML documents in a programmatic way. It offers a more extensive API and additional features like DTD support and namespace handling. Compared to xmlcreate, xmlbuilder is more feature-rich but also slightly more complex to use.
xml2js
xml2js is primarily used for converting XML to JavaScript objects and vice versa. While it can also create XML documents, its main strength lies in parsing XML. It is more versatile in terms of data manipulation but less focused on XML creation compared to xmlcreate.
fast-xml-parser
fast-xml-parser is known for its high performance in parsing XML to JSON and vice versa. It also supports XML building, but its primary focus is on fast and efficient parsing. It is a good choice if performance is a critical factor.
xmlcreate
Overview
xmlcreate is a Node.js module that can be used to easily build XML using a
simple API.
Features
xmlcreate uses a DOM-style API to build XML. Each construct in XML, including
elements, attributes, and even the document itself, is represented as a node
in a tree with a document node at the root.
Each node has a set of properties corresponding to the node's properties in
XML. For example, the element node has a name property, while the CDATA node
has a character data property.
Each node also has a set of children corresponding to the node's value,
children or attributes in XML, depending on the context. For example, the XML
declaration and document type declaration are represented as child nodes of the
root document node, while sub-elements and element attributes are represented
as child nodes of element nodes.
xmlcreate performs some basic validation during tree building to ensure that
the resulting XML is well-formed. Nodes can only have certain types or
quantities of nodes as children, while node properties are checked to ensure
that they do not contain characters disallowed in XML for that node or in
general.
However, xmlcreate does not perform comprehensive validation. For example, it
does not match the tree structure against a schema or confirm that entity
references are valid. You should use a XML parser for this purpose instead.
Once the tree is built, the tree itself or any of its subtrees can be
serialized to text. The formatting of the text is customizable.
Installation
The easiest way to install xmlcreate is using npm:
npm install xmlcreate
You can also build xmlcreate from source using npm, gulp, and typings:
git clone https://github.com/michaelkourlas/node-xmlcreate.git
npm install
typings install
gulp
You'll need to install gulp and typings first if you don't have them:
npm install -g gulp
npm install -g typings
You can then copy the folder into your node_modules directory.
The default
target will build the production variant of xmlcreate, run all
tests, and build the documentation.
You can build the production variant without running tests using the target
prod
. You can also build the development version using the target dev
. At
the moment, the only difference between the two is that the development version
includes source maps.
Usage
The documentation for the current version is available here.
You can also build the documentation using gulp:
gulp docs
Examples
The following example illustrates the basic usage of xmlcreate:
var xmlcreate = require("xmlcreate");
var document = xmlcreate.document("html");
document
.decl({encoding: "UTF-8"})
.up()
.dtd("html", "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd",
"-//W3C//DTD XHTML 1.0 Strict//EN")
.up()
.root()
.attribute("xmlns", "http://www.w3.org/1999/xhtml")
.up()
.attribute("xml:lang", "en")
.up()
.attribute("lang", "en")
.up()
.element("head")
.element("title")
.text("My page title")
.up()
.up()
.up()
.element("body")
.element("h1")
.text("Welcome!")
.up()
.up()
.element("p")
.text("This is some text on my website.");
console.log(document.toString({doubleQuotes: true}));
This example produces the following XML:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>My page title</title>
</head>
<body>
<h1>Welcome!</h1>
<p>This is some text on my website.</p>
</body>
</html>
Additional examples can be found in examples/example.js.
Tests
xmlcreate includes a set of tests to verify core functionality. You can run
the tests using gulp:
gulp test
The test
target builds the production variant of xmlcreate before running
the tests. The test-prod
target does the same thing, while the test-dev
target builds the development variant first instead.
License
xmlcreate is licensed under the Apache License 2.0.
Please see the LICENSE.md file for more information.