DOM guide: Creating documents

Creating a simple document

All interaction with the DOM begins with the DAE object. The DAE object provides a container within which documents can cross-reference each other, and provides state settings needed by several other objects.

DAE dae;

To add a document, call the DAE::add method with a file name.

dae.add("simple.dae");

Now write the document using one of the DAE::write* methods.

dae.writeAll();

DAE::writeAll writes all open documents to the paths originally given. In our case we only have one document, so this will create a Collada file "simple.dae" in the current directory.

The entire program is quite simple:

#include <dae.h>

int main() {
	DAE dae;
	dae.add("simple.dae");
	dae.writeAll();
	return 0;
}

as is the output Collada file:

<?xml version="1.0" encoding="UTF-8"?>
<COLLADA xmlns="http://www.collada.org/2005/11/COLLADASchema" version="1.4.1"/>

Creating a valid document

The previous code outputs an xml document, but it isn't a valid Collada document according to the Collada schema. See schema validation for more info.

Let's create a full Collada document. Collada requires an <asset> element be present as a child of <COLLADA>.

daeElement* root = dae.add("valid.dae");
daeElement* asset = root->add("asset");

We create a document just as we did before, but this time we receive the output into a daeElement object. In the DOM, daeElement is the root class of all Collada element objects. The DAE::add method returns a pointer to the <COLLADA> element, which is the root element of all Collada documents, or null if creating the document fails for some reason.

Then we use the daeElement::add method to add a new child node to the <COLLADA> element. Just as the DAE::add method adds new documents to the DOM, the daeElement::add method adds new child elements to an already existing element. daeElement::add returns a daeElement pointer, which is the newly created element.

According to the schema, the <asset> element must have child elements <contributor>, <created>, and <modified>. Let's create those elements.

daeElement* contributor = asset->add("contributor");
daeElement* created = asset->add("created");
daeElement* modified = asset->add("modified");

The <contributor> element can be empty according to the schema, so we'll leave it empty for now. The <created> and <modified> elements must contain valid xs:dateTime strings. We'll set them appropriately.

const char* date = "2008-04-08T13:07:52-08:00";
created->setCharData(date);
modified->setCharData(date);

The daeElement::setCharData is used to set the xml character content of an element. That's it, we're done. Now just write the document with DAE::writeAll.

// The whole program
#include <dae.h>
#include <dom/domCOLLADA.h>

int main() {
	DAE dae;
	daeElement* root = dae.add("valid.dae");
	daeElement* asset = root->add("asset");
	daeElement* contributor = asset->add("contributor");
	daeElement* created = asset->add("created");
	daeElement* modified = asset->add("modified");
	const char* date = "2008-04-08T13:07:52-08:00";
	created->setCharData(date);
	modified->setCharData(date);
	dae.writeAll();
	return 0;
}

<!-- The resulting (schema conforming!) xml document -->
<?xml version="1.0" encoding="UTF-8"?>
<COLLADA xmlns="http://www.collada.org/2005/11/COLLADASchema" version="1.4.1">
	<asset>
		<contributor/>
		<created>2008-04-08T13:07:52-08:00</created>
		<modified>2008-04-08T13:07:52-08:00</modified>
	</asset>
</COLLADA>

Creating xml data

At its core, the DOM is just a library for creating xml data, with some added support for implementing concepts specific to Collada. When creating xml data, there are three basic operations to consider: creating elements, setting attributes, and setting character data.

Creating elements

As we saw in the example code, creating new elements is done with the daeElement::add method: daeElement* add(daeString name, int index = -1);. daeElement::add also takes an optional integer index which specifies the location in the child list to put the new element. In practice this is rarely used because when the schema requires elements to appear in a certain order, the DOM handles this automatically for you.

One additional nicety of daeElement::add is that you can pass it a whitespace separated list of element names. The DOM will create each element in the list as a child of the previous element, and return the last element created. So, for example, if you have an empty <COLLADA> element and you want to create a new <geometry> containing a <mesh>, you could do that as follows (recall that a <geometry> must appear in a <library_geometries>)

daeElement* mesh = root->create("library_geometries geometry mesh");

instead of

daeElement* geomLib = root->create("library_geometries");
daeElement* geom = geomLib->create("geometry");
daeElement* mesh = geom->create("mesh");