Difference between revisions of "DOM guide: Creating documents"

From COLLADA Public Wiki
Jump to navigation Jump to search
Line 53: Line 53:
 
  modified->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 daeElement::setCharData is used to set the xml character content of an element.
 +
 
 +
Now just write the document with DAE::writeAll and we're done. We now have a complete Collada document, although it doesn't have any interesting content yet.
  
 
  // The whole program
 
  // The whole program

Revision as of 03:08, 9 April 2008

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.

Now just write the document with DAE::writeAll and we're done. We now have a complete Collada document, although it doesn't have any interesting content yet.

// 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);

This method returns a pointer to the element if it was successfully created, and null otherwise. 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->add("library_geometries geometry mesh");

instead of

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

Setting attributes

Setting attributes is done via the daeElement::setAttribute method.

virtual daeBool setAttribute(daeString name, daeString value);

This method returns true if the attribute with the given name was found and the value applied successfully, and false otherwise. You might use it like this.

// Create a <geometry> element and set the 'id' attribute.
daeElement* geom = root->create("library_geometries geometry");
geom->setAttribute("id", "myGeom");

// Create an <asset><unit> element and set the 'meter' and 'name' attributes.
daeElement* unit = root->create("asset unit");
unit->setAttribute("meter", "0.01");
unit->setAttribute("name", "centimeter");

Setting character data

Character data refers to the text contained within an element. For example, in the xml <translate>1 2 3</translate>, the text "1 2 3" is the character data.

In the DOM you set character data with the daeElement::setCharData method.

daeBool setCharData(const std::string& data);

Note that not all elements support character data. This method returns true if the element supports character data and the data was successfully changed, and returns false otherwise.

We've already seen daeElement::setCharData used when writing a valid document. Here's another example.

// Create a <node> with a <translate> element and set the translation's value
daeElement* translate = root->add("library_nodes node translate");
translate->setCharData("1 2 3");


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