You are not logged in Log in Join
You are here: Home » Members » jim » ZDOM-save » Attachment
Log in
Name

Password

 
Link icon Forgot your password?
 
Print

Attachment

DOM Interface Specification

Introduction

This file will serve as an interface guide to DOM support in Zope. It will document the interfaces provided by the DOM implementation, required functionality, default behaviors, and error conditions for each method.

General Note: The python binding for the DOM has defined attribute access to be in the following forms:

  1. For accessing attributes, the attribute can be read as an instance variable, and through the function get_attrName(). Ex.

    attribute readonly nodeType;

    Maps to the following definitions

    self.nodeType
    self.get_nodeType()

  2. For mutating attributes, the attribute can be set as an instance varible, or through the function set_attrName(value);

    attribute nodeName;

    Maps to the following definition

    self.nodeName

    self.set_nodeName(value)

As a general rule, read attribute access will be performed through computed attribute values. It will be explicitly noted when this is not the case.

Developers Note: Outstanding issues will be flagged with !!ISSUE!!

!!ISSUE The DOM spec defines special operations for DocumentFragments?. Are DocumentFragments? defined in Zope??? I don't see how they really fit in.

Exceptions

!!ISSUE How do these map into Zope? Do we want to raise DOM Exceptions, or Zope Exceptions?

Node level interfaces

Node level interfaces are define basic actions for every node in a DOM tree. All Zope objects will support the Node interface to its fullest extent.

Node Type Definitions

Interface

!!ISSUE are these needed at this level? All Zope Objects are Elements.
!!If they are used, should they be stored in string format so they are more readable?
!!dtml-if nodeType=ELEMENT_NODE
!!is prettier then
!!dtml-if nodeType=1
!!However, in the future we may inherit from this Node in XMLDocument?.

The constants define what the type of the node a node is. The nodeType (get_nodeType()) accessor of a Node will return one of these constants.

ELEMENT_NODE = 1;
ATTRIBUTE_NODE = 2;
TEXT_NODE = 3;
CDATA_SECTION_NODE = 4;
ENTITY_REFERENCE_NODE = 5;
ENTITY_NODE = 6;
PROCESSING_INSTRUCTION_NODE = 7;
COMMENT_NODE = 8;
DOCUMENT_NODE = 9;
DOCUMENT_TYPE_NODE = 10;
DOCUMENT_FRAGMENT_NODE = 11;
NOTATION_NODE = 12;

Design Notes

All Zope Objects will have a node type of ELEMENT_NODE

Parameter Definition

Return Value Definition

Default Implementation

Extending Notes

nodeName

Interface

readonly attribute DOMString? nodeName

!!ISSUE is this the same as an object's title? Originally the title was mapped to a DOM attribute, maybe it should be moved to the nodeName. The node name is defined as constants for certain nodes, but it is the tagName for Elements.

!! This won't work if we use this class as a base class for XML Document objects

Parameter Definition

None

Return Value Definition

The value of the nodeName attribute depends on the type of node being queried.

nodeType nodeName
Attrname of attribute
CDATASection?#cdata-section
Comment#comment
Document#document
DocumentFragment?#document-fragment
DocumentType?document type name
Elementtag name
Entityentity name
EntityReference?name of entity referenced
Notationnotation name
ProcessingInstruction?target
Text#text

Default Implementation

The default implementation will return the tagName of the Z Object.

!!ISSUE see previous issue, is this the objects title?

Extending Notes

None

nodeValue

Interface

attribute DOMString? nodeValue;

!!ISSUE This is defined as None for an element, should we support this interface?

!!Same note on subclassing

Parameter Definition

None

Return Value Definition

The nodeValue of an attribute is defined based on the nodeType.

nodeType nodeValue
Attrvalue of attribute
CDATASection?Content of the CDATA Section
CommentContent of the comment
DocumentNULL
DocumentFragment?NULL
DocumentType?NULL
ElementNULL
EntityNULL
EntityReference?NULL
NotationNULL
ProcessingInstruction?entire content including target
Textcontent of the text node

Default Implementation

!!!ISSUE See previous issue

Extending Notes

None

nodeType

Interface

readonly attribute int nodeType;

Parameter Definition

None

Return Value Definition

The type of the current node as defined by the node type definitions.

Default Implementation

ISSUE See issue for node types above. This will return whatever an Element Node is defined as, either an int or the string.

Extending Notes

This method should probably not be overridden, as changing what type of node the Z Object is requires a lot more then changin the results of this attribute access.

parentNode

Interface

readonly attribute Node parentNode;

Parameter Definition

None

Return Value Definition

A node reference that is the paraent of the current node in the document tree. If the current node is the document itself, return None.

Default Implementation

The default implementation will be to return getattr(self,aq_parent,None)

Extending Notes

This method should probably not be overridden. It should return the Z Object's parent.

childNodes

Interface

readonly attribute NodeList? childNodes;

!!ISSUE Should we bring the idea of NodeLists? into Zope, or should NodeLists? be replaced with collection?

Parameter Definition

None

Return Value Definition

!!See previous issue

Returns a list (Nodelist or otherwise) of Z Objects that are the children objects of the current node.

Default Implementation

!!See previous issue

!!The current implemetation in ZDOM returns the objectValue of self? I am unable to determine what this means.

!!I am unable to determine how to retrieve an Object's children. I thought I saw reference to aq_children but am unable to locate it again.

Extending Notes

This method should not be overridden

firstChild

interface

readonly attribute Node firstChild;

!!ISSUE currently in 4DOM we cache this, and modify on the write methods (such as insertBefore, appendChild, removeChild, etc). Is this possible in ZDOM? Can we override all ways that the object tree is modified? We have found this to be a large performance bost.

Parameter Definitions

None

Return Value Definition

The child object that is first in our list of children

!!ISSUE DOM defines this through "Document order", is there such an ordering in Zope. I assuem yes.

Default Implementation

!!See previous issue

Without optimization, This will return self.childNodes[0]?

Extending Notes

It is not recommended that this method is extended.

lastChild

interface

readonly attribute Node lastChild;

!!ISSUE same ISSUE as firstChild

Parameter Definitions

None

Return Value Definition

The child object that is last in our list of children

!!Same ordering issue as firstChild

Default Implementation

!!See previous issue

Without optimization. This will return self.childNodes[-1]?

Extending Notes

It is not recommended that this method is extended.

previousSibling

Interface

readonly attribute Node previousSibling;

!!ISSUE same caching and ordering issues for firstChild

Parameter Definitions

None

Return Value Definitions

This function must return the previous sibling (parent's child) in the object tree.

Default Implementation

Without Optimization, This will return self.parentNode.childNodes[self.parentNode.childNodes.index(self)-1]?

Extending Notes

None

nextSibling

Interface

readonly attribute Node nextSibling;

!!ISSUE same caching and ordering issues for firstChild

Parameter Definitions

None

Return Value Definitions

This function must return the next sibling (parent's child) in the object tree.

Default Implementation

Without Optimization, This will return self.parentNode.childNodes[self.parentNode.childNodes.index(self)+1]?

Extending Notes

None

attributes

Interface

readonly attribute NamedNodeMap? attributes;

Parameter Definitions

None

Return Value Definitions

This function will return a NamedNodeMap? of the attributes of this node

!!ISSUE Do we want to introduce NamedNodeMaps? into Zope? Does Zope know about dictionaries?

Default Implementation

This needs to work with the PropertyManager? to get the currently defined properties for this objects and present them as a Mapping (eith NamedNodeMap? of python dict

Extending Notes

None

ownerDocument

Interface

readonly attribute Document ownerDocument;

!!ISSUE, what defines the document. I believe it is the "system" but what exactly is that?

Parameter Definitions

None

Return Value Definitions

This function will return the defining document of this node.

!!See previous ISSUE

Default Implementation

!!ISSUE should we cache this? Is it possible?

The default implementation without caching will return the ancestor node that has a parentNode of None

Extending Notes

None

insertBefore

interface

Node               insertBefore(in Node newChild, 
                                         in Node refChild)
                                         raises(DOMException);

Parameter Definitions

newChild: The new object to add to the Tree
refChild: The current child that the new object should be added before. Note is reChild is None, this interface will function exactly like appendChild.

!!ISSUE Should this be implemented in ZDOM or XMLDocument?? From the ZDOM interface, can node be added?

Return Value

The node that is being inserted is returned. This node will have correct parent information.

Default Implementation

If implementated in ZDOM, the new child will inserted into the list of children previous to the refChild.

!!ISSUE See Exception ISSUE

!!ISSUE The proxy for the node being inserted will be invalid. References to the node should be through the return value.

Extending Notes

None

replaceChild

Interface

Node               replaceChild(in Node newChild, 
                                         in Node oldChild)
                                         raises(DOMException);

!ISSUESame implemetation issue as insertBerfore

Parameter Definitions

newchild: The object that will replace what is already in the tree.
refChild: The object to be replaced.

!!ISSUE The reference to the node that is now a part of the tree (newchild) will be broken. Any other references (except the one returned) of the refChild will be broken. The returned refChild will be correct.

!ISSUE Exception issue. What is thrown if refChild is not a child of the current object.

Return Value Definition

The node that is being replaced is returned. It will be updated to show proper parent informatiom.

Default Implementation

The default implementation will find the refChild in the list of children. If it does not exist, an exception will be raised. If it does exist, then it will be replaced in the list of children and returned.

Extending Notes

None

removeChild

Interface

Node               removeChild(in Node oldChild)
                                        raises(DOMException);

Parameter Definitions

oldChild: The child that is to be removed. oldChild must be a child of this node.

Return value Definition

The child that was replaced. Note an references to oldChild before the call is made will be out of date. The reference to oldChild that is returned will correctly represent the Object in the tree.

Default Implementation

The oldchild will be located in the list of the current node's children. If oldChild is not a child then an exception will be raised. If it is, it will be removed. The child will be returned.

Extending Notes

None

appendChild

Interface

Node               appendChild(in Node newChild)
                                        raises(DOMException);

Parameter Definitions

newChild: The child to be added to the current node's children list.

Return Value Definition

A new reference to the newChild is returned. Note all references to the newChild obtained before this function call will be invalid. The returned reference will correctly represent the object in the tree.

Default Implementation

The new child will be added to the end of this objects child nodes.

Extending Notes

None

hasChildNodes

Interface

boolean hasChildNodes();

Parameter Definitions

None

Return Value Definition

True if the object has child nodes, false otherwise

Default Implementation

return len(self.childNodes) > 0

Extending Notes

None

cloneNode

!!ISSUE CloneNode? does not make sense in the realm of Zope. At least not until XMLDocument? is finished.

normalize

Interface

void normalize();

!!ISSUE Does this make sense in ZDOM. I see it more in XMLDocument?.

Parameter Definitions

None

Return Value Definitions

None

Default Implementation

The default implementation will combine should combine all adjacent text nodes. There are currently no text nodes in ZDOM.

Extending Notes

This method should be extended in XMLDocument? when text nodes are used.

supports

Interface

boolean supports(in DOMString? feature, in DOMString? version);

!!ISSUE I don't see how this is useful in Zope.

namespaceURI

Interface

readonly attribute DOMString? namespaceURI;

Parameter Definitions

None

Return Value Definition

A string that represents the namespace of the current object.

Default Implementation

!!ISSUE How are namespaces for objects defined. I understand how namespaces of properties are defined, but not objects

Extending Notes

prefix

Interface

attribute DOMString? prefix;

Parameter Definitions

None

Return Value Definition

A string that alaises the namespaceURI of the current node.

Default Implementation

!!ISSUE I am unclear as to where the prefix is stored. As I currently understand it is not stored. Should prefixes be generated??

Extending Notes

When an object is created from XMLDocument?, we should store internally its prefix so it is not lost.

localName

Interface

readonly attribute DOMString? localName;

Parameter Definition

None

Return Value Definition

A string that represents the local portion of the objects QName?.

!!ISSUE Is this the objects title? Can titles have spaces, <, etc?

Default Implementation

In the DOM this is the part of the nodeName to the right of the :. I am not 10% sure where this fits into Zope.

Extending Notes

None

Last modified: Fri Mar 24 20:15:43 MST 2000

Copyright (c) 2011 Zope Foundation. All rights reserved. Legal | Contact
If you can read this text, it means you are not experiencing the Plone design at its best. Plone makes heavy use of CSS, which means it is accessible to any internet browser, but the design needs a standards-compliant browser to look like we intended it. Just so you know ;)