SoftQuad michael@0: Inc.

michael@0: michael@0: michael@0: michael@0: michael@0: SoftQuad michael@0: Inc. michael@0:

michael@0: michael@0: michael@0: michael@0:

michael@0: Demo Product Documentation michael@0: SoftQuad Inc. michael@0: <Anchor michael@0: Id="SDK3"/>Element Overview michael@0: Introduction to Elements michael@0: By far the vast majority of objects (apart from text) that authors michael@0: encounter when traversing a document are Element nodes. michael@0: <Anchor Id="SDK273"/>Element Interfaces michael@0: <Anchor Id="SDK274"/>Elements and michael@0: Attributes michael@0: <Anchor Id="SDK279"/>Introduction to Attributes michael@0: michael@0: Elements may have attributes associated with them; since the Element michael@0: interface inherits from Node, the generic Node interface method michael@0: getAttributes may be used to retrieve the set of all michael@0: attributes for an element. michael@0: There are methods on the Element interface to retrieve either an Attr michael@0: object by name or an attribute value by name. In XML, where an attribute value michael@0: may contain entity references, an Attr object should be retrieved to examine michael@0: the possibly fairly complex sub-tree representing the attribute value. On the michael@0: other hand, in HTML, where all attributes have simple string values, methods to michael@0: directly access an attribute value can safely be used as a convenience. michael@0: michael@0: Before you can access an Attribute, you must first gain access to the michael@0: associated Element. michael@0: <Anchor Id="SDK378"/>Setting the Attribute michael@0: Values michael@0: Attr objects inherit the Node interface, but since they are not actually michael@0: child nodes of the element they describe, the DOM does not consider them part michael@0: of the document tree. Thus, the Node attributes parentNode, previousSibling, michael@0: and nextSibling have a null value for Attr objects. The DOM takes the view that michael@0: attributes are properties of elements rather than having a separate identity michael@0: from the elements they are associated with; this should make it more efficient michael@0: to implement such features as default attributes associated with all elements michael@0: of a given type. Furthermore, Attr nodes may not be immediate children of a michael@0: DocumentFragment. However, they can be associated with Element nodes contained michael@0: within a DocumentFragment. In short, users and implementors of the DOM need to michael@0: be aware that Attr nodes have some things in common with other objects michael@0: inheriting the Node interface, but they also are quite distinct. michael@0: The attribute's effective value is determined as follows: michael@0: michael@0: If this attribute has been explicitly assigned any value, that value is michael@0: the attribute's effective value michael@0: Otherwise, if there is a declaration for this attribute, and that michael@0: declaration includes a default value, then that default value is the michael@0: attribute's effective value michael@0: Otherwise, the attribute does not exist on this element in the structure michael@0: model until it has been explicitly added. michael@0: In XML, where the value of an attribute can contain entity references, michael@0: the child nodes of the Attr node provide a representation in which entity michael@0: references are not expanded. These child nodes may be either Text or michael@0: EntityReference nodes. Because the attribute type may be unknown, there are no michael@0: tokenized attribute values. michael@0: The following topics describe DOM attributes: michael@0: michael@0: michael@0: Interface michael@0: Attr michael@0: michael@0: michael@0: Interface Element michael@0: michael@0: <Anchor michael@0: Id="SDK48"/>DOM Level 1 Core: Element Functions michael@0: setAttribute michael@0: setAttribute michael@0: Sets the Attributes on the associated Element object michael@0: Fundamental michael@0: <Anchor Id="SDK85"/>Syntax michael@0: OMG IDL michael@0: void setAttribute (in michael@0: DOMString name, in DOMString michael@0: value) raises (DOMException); michael@0: <Anchor Id="SDK86"/>Java michael@0: public void setAttribute ( michael@0: String name, String michael@0: value) throws (DOMException); michael@0: <Anchor Id="SDK87"/>ECMA Script michael@0: michael@0: setAttribute (name, value michael@0: ) michael@0: <Anchor Id="SDK88"/>Parameters michael@0: name michael@0: michael@0: (IN) The name of the attribute to create or alter. michael@0: value michael@0: michael@0: (IN) Value to set in string form michael@0: <Anchor Id="SDK89"/>Exceptions michael@0: michael@0: These are the applicable exceptions. michael@0: michael@0: michael@0: michael@0: INVALID_CHARACTER_ERR michael@0: Raised if the specified name contains an invalid character. michael@0: michael@0: NO_MODIFICATION_ALLOWED_ERR michael@0: Raised if this node is readonly. michael@0: michael@0: <Anchor michael@0: Id="SDK90"/>Remarks michael@0: setAttribute adds a new attribute. If an attribute michael@0: with that name is already present in the element, its value is changed to be michael@0: that of the value parameter. This value is a simple string, it is not parsed as michael@0: it is being set. So any markup (such as syntax to be recognized as an entity michael@0: reference) is treated as literal text, and needs to be appropriately escaped by michael@0: the implementation when it is written out. michael@0: In order to assign an attribute value that contains entity references, michael@0: the user must create an Attr node plus any Text and EntityReference nodes, michael@0: build the appropriate subtree, and use setAttributeNode to michael@0: assign it as the value of an attribute. michael@0: