WebCGM Document Object Model (DOM) Specification
Version 1.0
Working Draft June 3, 2004
This version:
Latest version:
Previous version:
Editors:
Authors:
Abstract
Status of this document
Table of contents
Expanded Table of Contents
Copyright Notice
1. WebCGM Document Object Model
Appendix A: Changes
Appendix B: IDL Definitions
Appendix C: ECMAScript Language Binding
Appendix D: Acknowledgements
Glossary
References
Index
1. WebCGM Document Object Model
1.1 Overview of the WebCGM DOM Interfaces
This section defines a set of objects and interfaces for accessing and manipulating WebCGM documents. The functionality specified in this section is to allow script writers to manipulate WebCGM documents and to access information found in WebCGM XML companion files. The WebCGM DOM API does not allow for the creation of Pictures but instead provides methods to update a WebCGM Picture based on external metadata (XML companion file).
1.1.1 Relationship with XML companion file
The WebCGM DOM is designed to provide access to XML metadata found in XML companion files. Practice has shown that some CGM illustrations are easier to maintain if some of the non graphical information remains outside the illustration. An example of such information could be for example; language sensitive tooltips. A scaled down DOM is then required to 'attach' the information from the XML companion file into the WebCGM document. For more information on XML companion files, please refer to the WebCGM XML companion file section.
Another benefit of the XML companion file is to carry application specific data (or metadata) concerning a WebCGM illustration. This information is expressed using namespace attributes and elements in the XML companion file. The WebCGM DOM provides method to load the XML metadata into the user agent's (viewer's) object model. Using the DOM, a user can gain access to the metadata. Here is an example to better illustrate the concept, let us assume we are working with the following WebCGM document (expressed in clearText encoding):
BEGMF 'example.cgm';
...
BEGPIC 'Picture 1';
...
BEGAPS 'L1' 'layer' STLIST;
APSATTR 'layername' "14 1 'Standard layer'";
BEGAPSBODY;
BEGAPS 'G1' 'grobject' STLIST;
BEGAPSBODY;
LINE 210,265 210,200 300,200;
LINE 300,200 300,265 210,265;
ENDAPS;
ENDAPS;
...
ENDPIC;
...
ENDMF;
|
The in memory tree representation of this illustration should be similar to the illustration found below. It is a simple tree structure with a root element Metafile, one of the children of the root is a Picture; the Picture contains a Layer and the layer contains an Application Structure of type grobject.
Now let us assume example.cgm has the following XML companion file for...
<cgmCompanion id="example" xmlns:wiring="http://namespace_declaration">
<grobject apsId="G1" screentip="A new screentip">
<wiring:data color="rgb(255,0,0)"/>
</grobject>
</cgmCompanion>
|
As mentioned above, the WebCGM provides methods to 'apply' an XML companion file to a WebCGM document. A comforming user agent is expected to load and parse the XML companion file and possibly 'apply' the XML companion file to the user agent's object model. The purpose of applying a companion file is to:
1) Replace standard Application Structure Attributes in the WebCGM document with new values (if any) found in the XML companion file (e.g., screentip="A new screentip").
2) Add XML metadata to the user agent's object model so that it can be retrieved using DOM APIs at a later stage (e.g., the <wiring:data> element is added as a child node of grobject G1; for example; the data could be of use to an interactive -scripted- wiring application).
Once the user agent has loaded the XML companion file into its memory model, the tree should resemble this:
1.1.2 Data types and interfaces
1.1.3 Coordinate values
Need wording to say: Origin at lower left corner, width and height represent the VDC extent, coordinate axes x to the right, y up. Coordinate values are the resulting values after having read the WebCGM.
1.2 Fundamental Interfaces
Summary will go here.
Exception DOMException
WebCGM operations only raise exceptions when an operation is impossible to perform.
IDL Definition
exception DOMException {
unsigned short code;
};
// ExceptionCode
const unsigned short INDEX_SIZE_ERR = 1;
const unsigned short DOMSTRING_SIZE_ERR = 2;
const unsigned short HIERARCHY_REQUEST_ERR = 3;
const unsigned short WRONG_DOCUMENT_ERR = 4;
const unsigned short INVALID_CHARACTER_ERR = 5;
const unsigned short NO_DATA_ALLOWED_ERR = 6;
const unsigned short NO_MODIFICATION_ALLOWED_ERR = 7;
const unsigned short NOT_FOUND_ERR = 8;
const unsigned short NOT_SUPPORTED_ERR = 9;
const unsigned short INUSE_ATTRIBUTE_ERR = 10;
const unsigned short INVALID_STATE_ERR = 11;
const unsigned short SYNTAX_ERR = 12;
const unsigned short INVALID_MODIFICATION_ERR = 13;
const unsigned short NAMESPACE_ERR = 14;
const unsigned short INVALID_ACCESS_ERR = 15;
|
Definition group ExceptionCode
An integer indicating the type of error generated
Defined Constants
DOMSTRING_SIZE_ERR; if the specified range of text does not fit into a DOMString
HIERARCHY_REQUEST_ERR; if any node is inserted somewhere it doesn't belong
INDEX_SIZE_ERR; if index or size is negative, or greater than the allowed value
INUSE_ATTRIBUTE_ERR; if an attempt is made to add an attribute that is already in use elsewhere
INVALID_ACCESS_ERR; if a parameter or an operation is not supported by the underlying object.
INVALID_CHARACTER_ERR; if an invalid or illegal character is specified, such as in a name. See production 2 in the XML specification for the definition of a legal character, and production 5 for the definition of a legal name character.
INVALID_MODIFICATION_ERR; if an attempt is made to modify the type of the underlying object.
INVALID_STATE_ERR; if an attempt is made to use an object that is not, or is no longer, usable.
NAMESPACE_ERR; if an attempt is made to create or change an object in a way which is incorrect with regard to namespaces.
NOT_FOUND_ERR; if an attempt is made to reference a node in a context where it does not exist
NOT_SUPPORTED_ERR; if the implementation does not support the requested type of object or operation.
NO_DATA_ALLOWED_ERR; if data is specified for a node which does not support data
NO_MODIFICATION_ALLOWED_ERR; if an attempt is made to modify an object where modifications are not allowed
SYNTAX_ERR; if an invalid or illegal string is specified.
WRONG_DOCUMENT_ERR; if a node is used in a different document than the one that created it (that doesn't support it)
Interface GetWebCGMDocument
Since WebCGM documents are often embedded within a host document such as XHTML, WebCGM user agents are required to implement the GetWebCGMDocument interface for the element which references the WebCGM document (e.g., the 'object' tag).
IDL Definition
interface GetWebCGMDocument {
Metafile getWebCGMDocument ( )
raises ( DOMException );
};
|
Methods
getWebCGMDocument
Returns the Metafile object for the referenced WebCGM document.
No parameters
Return value
Metafile; The Metafile object for the referenced WebCGM document.
Exceptions
DOMException; NOT_SUPPORTED_ERR: No Metafile object is available.
Interface Metafile
The Metafile interface is the entry point to the entire WebCGM document. The interface expose information regarding the metafile and provides access to the first Picture of the WebCGM document.
IDL Definition
interface Metafile {
readonly attribute DOMString cgmDescription;
readonly attribute Picture firstPicture;
readonly attribute DOMString cgmID;
readonly attribute integer cgmVersion;
};
|
Attributes
cgmDescription of type DOMString, readonly
Returns the Metafile Descriptor of the WebCGM document (e.g., "ProfileId:WebCGM,ProfileEd:1.0,Source:A software vendor,Date:20040602,ColourClass:monochrome" ). The cgmDescription must contain the ProfileId: and the ProfileEd:, other information such as Source, ColourClass etc... is considered optional.
firstPicture of type Picture, readonly
Returns the first Picture element of the WebCGM document. Subsequent Pictures can be accessed using the Picture interface. A WebCGM document contains at least one Picture.
cgmID of type DOMString, readonly
Returns the cgm filename.
Why do we expose the filename of the cgm (cgmID), won't the application already know this? |
cgmVersion of type integer, readonly
Returns the Metafile Version of the WebCGM document.
Interface Node
The Node interface is the base datatype of the WebCGM Document Object Model. The Node object is the basis of several other interfaces; XMLElements and WebCGM specific elements (i.e., AppStructure & Picture). The Node interface specifies the attributes and methods to perform simple and generic tree traversal routines.
IDL Definition
interface Node {
const unsigned short PICTURE_NODE = 1;
const unsigned short APP_STRUCTURE_NODE = 2;
const unsigned short XML_ELEMENT_NODE = 3;
const unsigned short TEXT_NODE = 4;
readonly attribute DOMString nodeName;
readonly attribute DOMString nodeValue;
// raises(DOMException) on retrieval
readonly attribute unsigned short nodeType;
readonly attribute Node parentNode;
readonly attribute NodeList childNodes;
readonly attribute Node firstChild;
readonly attribute Node lastChild;
readonly attribute Node previousSibling;
readonly attribute Node nextSibling;
readonly attribute Picture ownerPicture;
boolean hasChildNodes();
boolean hasAttributes();
boolean hasAttributeNS(in DOMString namespaceURI,
in DOMString localName);
readonly attribute NamedNodeMap attributes; // should attributes be here or in another interface?
readonly attribute DOMString namespaceURI;
attribute DOMString prefix;
// raises(DOMException) on setting
readonly attribute DOMString localName;
DOMString getAttributeNS(in DOMString namespaceURI,
in DOMString localName);
NodeList getElementsByTagNameNS(in DOMString namespaceURI,
in DOMString localName);
NodeList getElementsByAttrNameValueNS(in DOMString namespaceURI,
in DOMString attrName,
in DOMString attrValue);
};
|
Definition group NodeType
An integer indicating which type of node this is.
Defined Constants:
PICTURE_NODE; the node is a Picture.
APP_STRUCTURE_NODE; the node is an AppStructure.
XML_ELEMENT_NODE; the node is XML companion information attached to a CGM element.
TEXT_NODE; the node is a Text.
The values of nodeName and nodeValue vary according to the node type as follows:
| Interface | nodeName | nodeValue |
| AppStructure | AppStructure type | null |
| Picture | #picture | null |
| Text | #text | content of the text node |
| XMLElement | tag name | null |
Attributes
nodeName of type DOMString, readonly
The name of this node, depending on its type; see the table above.
nodeValue of type DOMString, readonly
The value of this node, depending on its type; see the table above.
Exceptions on retrieval
DOMException; DOMSTRING_SIZE_ERR: Raised when it would return more characters than fit in a DOMString variable on the implementation platform.
nodeType of type unsigned short, readonly
A code representing the type of the underlying object, see the table above.
parentNode of type Node, readonly
The parent (immediate ancestor node of a node) of this node. All nodes, except Picture may have a parent.
childNodes of type NodeList, readonly
A NodeList that contains all children of this node. If there are no children, this returns an empty NodeList.
firstChild of type Node, readonly
The first child of this node. If there is no such node, this returns null.
lastChild of type Node, readonly
The last child of this node. If there is no such node, this returns null.
previousSibling of type Node, readonly
The node immediately preceding this node. If there is no such node, this returns null.
nextSibling of type Node, readonly
The node immediately following this node. If there is no such node, this returns null.
ownerPicture of type Picture, readonly
The Picture object associated with this node. When the node is a Picture node, this returns null.
namespaceURI of type DOMString, readonly
The namespace URI of this node (e.g., elementName xmlns="http://www.example.org/2004", returns "http://www.example.org/2004"). This returns null if the Node is not of type XML_ELEMENT_NODE.
prefix of type DOMString, readonly
The namespace prefix of this node (e.g., foo:elementName, returns "foo"). This returns null if the Node is not of type XML_ELEMENT_NODE.
localName of type DOMString, readonly
Returns the local part of the qualified name of this node (e.g., foo:elementName, returns "elementName"). This returns null if the Node is not of type XML_ELEMENT_NODE.
Methods
hasChildNodes
Returns whether this node has any children.
No Parameters
Return Value
boolean; true if this node has any children, false otherwise.
No Exceptions
hasAttributes
Returns whether this node (if of type XML_ELEMENT_NODE) has any attributes.
No Parameters
Return Value
boolean; true if this node has any attributes, false otherwise.
Exceptions INVALID_ACCESS_ERR if called on a non XML_ELEMENT_NODE object.
hasAttributeNS
Returns true when an attribute with a given local name and namespace URI is specified on this Node (must be of type XML_ELEMENT_NODE), returns false otherwise.
No Parameters
Return Value
boolean; true if this node has any children, false otherwise.
Exceptions INVALID_ACCESS_ERR if called on a non XML_ELEMENT_NODE object.
getAttributeNS
Returns the node (must be of type XML_ELEMENT_NODE) attribute value by local name and namespace URI.
Parameters
namespaceURI of type DOMString
The namespace URI of the attribute to retrieve.
localName of type DOMString
The local name of the attribute to retrieve.
Return Value
DOMString; The Attr value as a string, or the empty string if that attribute does not have a specified value.
Exceptions INVALID_ACCESS_ERR if called on a non XML_ELEMENT_NODE object.
getElementsByTagNameNS
Returns a NodeList of all the descendant XML element (companion information) with a given local name and namspace URI in the order in which they are encountered in a preorder traversal of the Node tree.
Parameters
namespaceURI of type DOMString
The namespace URI of the XML elements to match on.
localName of type DOMString
The local name of the XML elements to match on.
Return Value
NodeList; A list of matching XML element nodes.
No Exceptions
getElementsByAttrNameValueNS
| Need Dave on this one! On which interface do you need this functionality? |
No Parameters
Return Value
No Exceptions
Interface Picture
The Picture interface allows for access to the application structures of the WebCGM document. It also specifies how to load an XML companion file into a WebCGM document.
IDL Definition
interface Picture : Node {
readonly attribute number width;
readonly attribute number height;
boolean applyCompanionFile(in DOMString fileURI,
in boolean loadOnly,
in boolean refresh);
Node getAppStructureById(in apsId);
NodeList getAppStructuresByType(in apsType);
void setStyleAttr(in DOMString style,
in DOMString value);
void clearStyleAttr(in DOMString style);
void clearData();
};
|
Attributes
width of type number, readonly
Represents the Picture width in millimeters. Please refer to Coordinate Values section for more information.
height of type number, readonly
Represents the Picture height in millimeters. Please refer to Coordinate Values section for more information.
Methods
applyCompanionFile
The applyCompanionFile reads an XML companion file into the user agent's object model. If companion information is found in the companion file (in the form of namespace attributes and namespace children elements), the user agent will create new namespace application structures as children of existing WebCGM Application Structures within it's object model. This information will then be accessible using methods found on the Picture, AppStructure and Node interfaces. Depending on the parameters, the applyCompanionFile method may or may not 'apply' the XML companion file. Please refer to the Relationship with XML companion file section for more detail.
Parameters
fileURI of type DOMString
The file name and location of the XML companion file to load and apply into the object model.
refresh of type boolean
When set to true, the method will delete any additional companion information that was added to the object model from a previous call to applyCompanionFile; a value of false implies that the caller may be loading companion information in addition to already loaded companion information.
Return value
boolean; true if the implementation was able to load and parse the XML companion file into memory as requested; false otherwise.
Exceptions FILE_NOT_FOUND_ERR; if the reference document could not be accessed.
Exceptions FILE_INCOMPATIBILITY_ERR; if the reference document was not well-formed or in error.
getAppStructureById
Returns the Application Structure whose ID is given by apsId. If no such Application Structure exists, returns null. Behavior is not defined if more than one element has this ID. The method does not apply to XML companion file information.
Parameters
apsId of type DOMString
The unique id value for an Application Structure.
Return value
Node; the matching Application Structure.
No Exceptions
| Do we need a getAppStructuresByName method? |
getAppStructuresByType
Returns a NodeList of all Application Structures of the given type in the order in which they are encountered in a preorder traversal of the Picture tree. Possible values for WebCGM 1.0 Application Structure types are 'layer','grobject', 'para', 'subpara'.
Parameters
apsType of type DOMString
The name of the Application Structure type to match on.
Return value
NodeList; A new NodeList object containing all the matched Application Struture Nodes.
No Exceptions
setStyleAttr
Set a style attribute at the picture level by name. The following table describes in more details each style attribute, their scope and allowed values:
| Style Attribute Name | Picture level | APS level | Attribute value(s) | Example |
| character-height | allowed | allowed | absolute mm or relative scale (> 0) | "3mm" or "2.25" |
| edge-color | allowed | allowed | absolute RGB or relative intensity (0..1) | "rgb(255,0,0)" or "0.75" |
| edge-weight | allowed | allowed | absolute mm or relative scale (> 0) | "3mm" or "2.25" |
| fill-color | allowed | allowed | absolute RGB or relative intensity (0..1) | "rgb(255,0,0)" or "0.75" |
| line-color | allowed | allowed | absolute RGB or relative intensity (0..1) | "rgb(255,0,0)" or "0.75" |
| line-weight | allowed | allowed | absolute mm or relative scale (> 0) | "3mm" or "2.25" |
| marker-color | allowed | allowed | absolute RGB or relative intensity (0..1) | "rgb(255,0,0)" or "0.75" |
| text-color | allowed | allowed | absolute RGB or relative intensity (0..1) | "rgb(255,0,0)" or "0.75" |
| raster-intensity | allowed | allowed | relative intensity (0..1) | "0.75" |
Note: Descriptions of all style attributes have to be provided.
| Anything missing from the style attributes? |
| Are there any style attribute that are only available at the Picture or APS level? |
| What kind of syntax do we want to allow for colors - rgb(255,0,0); #FF0000, #F00, red-? |
| What kind of syntax do we want to allow for intensity - 75%, 0.75 -? |
Parameters
style of type DOMString
The name of the style attribute to modify.
value of type DOMString
The new value for the given style.
No Return value
No Exceptions
clearStyleAttr
Restores a style attribute to its original value (load time).
Parameters
style of type DOMString
The name of the style attribute. The special value "*" matches all style attributes.
No Return value
No Exceptions
clearData
Removes all XML companion information that was loaded into the user agent's object model from one or multiple applyCompanionFile calls. The method clearData does not reset Application Structure attributes to their inital values if they were modified by an applyCompanionFile call, the purpose of this method is to remove additional companion information from the object model.
No Parameters
No Return value
No Exceptions
Interface AppStructure
The AppStructure interface offers method for setting and retrieving Application Structure attributes. The general methods for accessing Application Structure attributes are getAppStructureAttr and setAppStructureAttr, however; since some attributes are allowed to be set multiple times (e.g., linkuri), specific methods are offered for certain attributes. The following table identifies the attributes which can get access using getAppStructureAttr and setAppStructureAtt:
| APS Attribute Name | getAppStructureAttr | setAppStructureAttr | Return/parameter type | Example |
| content | allowed | allowed | DOMString | "car engine transmission" |
| interactivity | allowed | allowed | interactive | none | "interactive" |
| layerdesc | allowed | allowed | DOMString | "This layer contains English instructions" |
| layername | allowed | no, readonly | DOMString | "English instructions" |
| linkuri | use getLinkuris | use setLinkuris | NamedNodeMap | see getLinkuris method |
| name | use getNames | no, readonly | NamedNodeMap | see getNames method |
| region | allowed | allowed | DOMString (coma delimited SDR) | "1,0,0,100,100" |
| screentip | allowed | allowed | DOMString | "This is a screentip" |
| viewContext | allowed | allowed | DOMString (two corner points) | "0,0,100,100" |
| virtualViewContext | allowed | no, readonly | DOMString (two corner points) | "0,0,100,100" |
| visibility | allowed | allowed | visible | hidden | "visible" |
Note: Descriptions of all Application Structure attributes have to be provided.
The AppStructure interface, like the Picture interface, provides methods for modifying style attributes at the Application Structure level. For more information about available style attribute, refer to the Style Attributes Table.
IDL Definition
interface AppStructure : Node {
readonly attribute DOMString apsId;
DOMString getAppStructureAttr(in DOMString name);
DOMString setAppStructureAttr(in DOMString name,
in DOMString value);
DOMString removeAppStructureAttr(in DOMString name);
NodeList getLinkuris();
NodeList setLinkuris();
NodeList getNames();
DOMString setStyleAttr(in DOMString style,
in DOMString value);
void clearStyleAttr(in DOMString style);
NodeList getAppStructuresByType(in apsType);
};
|
Attributes
apsId of type DOMString, readonly
The unique identifier of the Application Structure.
Methods
getAppStructureAttr
Gets an Application Structure attribute by name. Please refer to the Application Structure Attributes table for more detailed information on retrievable and modifiable Application Structure attributes.
Parameters
name of type DOMString
The name of the Application Structure attribute to retrieve.
No Return value
No Exceptions
setAppStructureAttr
Sets an Application Structure attribute by name. Please refer to the Application Structure Attributes table for more detailed information on retrievable and modifiable Application Structure attributes.
Parameters
name of type DOMString
The name of the Application Structure attribute to set.
value of type DOMString
The new value for the given attribute.
No Return value
No Exceptions
removeAppStructureAttr
Removes an Application Structure attribute by name. Please refer to the Application Structure Attributes table for more detailed information on retrievable and modifiable Application Structure attributes.
Parameters
name of type DOMString
The name of the Application Structure attribute to remove.
No Return value
No Exceptions
getLinkuris
Need wording.
Parameters
style of type DOMString
The name of the style attribute to modify.
value of type DOMString
The new value for the given style.
No Return value
No Exceptions
setLinkuris
Need wording.
Parameters
style of type DOMString
The name of the style attribute to modify.
value of type DOMString
The new value for the given style.
No Return value
No Exceptions
getNames
Need wording.
Parameters
style of type DOMString
The name of the style attribute to modify.
value of type DOMString
The new value for the given style.
No Return value
No Exceptions
setStyleAttr
Set a style attribute at the picture level by name. Please refer to the Style Attributes Table for more detailed information on style attributes.
Parameters
style of type DOMString
The name of the style attribute to modify.
value of type DOMString
The new value for the given style.
No Return value
No Exceptions
clearStyleAttr
Restores a style attribute to its original value (load time).
Parameters
style of type DOMString
The name of the style attribute. The special value "*" matches all style attributes.
No Return value
No Exceptions
getAppStructuresByType
Returns a NodeList of all Application Structures of the given type in the order in which they are encountered in a preorder traversal of the AppStructure tree. Unlike the same method on the Picture interface, the valid types are defined by the current Application Structure type.
Parameters
apsType of type DOMString
The name of the Application Structure type to match on.
Return value
NodeList; A new NodeList object containing all the matched Application Struture Nodes.
No Exceptions SHOULD THROW AN EXCEPTION.
TODO: NodeList interface, Attr interface (???), Text interface and Event interfaces.
