DOM guide: Creating documents

From COLLADA Public Wiki
Revision as of 01:21, 9 April 2008 by SteveT (talk | contribs)
Jump to navigation Jump to search

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 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>



COLLADA DOM - Version 2.4 Historical Reference
List of main articles under the DOM portal.
User Guide chapters:  • Intro  • Architecture  • Setting up  • Working with documents  • Creating docs  • Importing docs  • Representing elements  • Working with elements  • Resolving URIs  • Resolving SIDs  • Using custom COLLADA data  • Integration templates  • Error handling

Systems:  • URI resolver  • Meta  • Load/save flow  • Runtime database  • Memory • StringRef  • Code generator
Additional information:  • What's new  • Backward compatibility  • Future work
Terminology categories:  • COLLADA  • DOM  • XML