<datapointer>
Prev  Data  Next

<datapointer>
A cursor in a dataset.

JavaScript: lz.datapointer
extends <node> » lz.Eventable »

A datapointer is an object that represents a pointer to a node in a lz.dataset. The datapointer can be repositioned using either cursor movements calls such as LzDatapointer.selectNext(), or by running an XPath request via LzDatapointer.setXPath().

Datapointers support a subset of the XPath specification, which uses a notation similar to the UNIX file-system to refer to nodes within a dataset. Once a datapointer is bound to a node in a dataset it will keep pointing to that node until it is moved. If the dataset is edited, the behavior of the datapointer will be controlled by its rerunxpath attribute. If this attribute is true, it will continue pointing to its current node as long as it is valid.

The example below demonstrates the use of some of the features of datapaths to retrieve data from a dataset.

Example 11. Using a datapointer to retrieve data from a dataset

<canvas height="80">
   <simplelayout spacing="5"/>
   <dataset name="mydata">
     <record> This is some text 
       <deeper>
         <deeprecord> This is a deeper level </deeprecord>
         <deeprecord> It's dark down here! </deeprecord>
         <deeprecord> Last deep record </deeprecord>
       </deeper>
     </record>
     <record> This is more text </record>
     <record> Exciting no? </record>
     <record> The final line of text </record>
   </dataset>
 
   <view>
     <simplelayout/>
     <datapointer id="mydp" xpath="mydata:/record[1]"/>
     <button> Move forward with select
       <handler name="onclick">
         if (mydp.selectNext()) var s = mydp.getNodeText();
         else var s = "hit last record; reset with xpath";
         output.setText(s);
       </handler>
     </button>
     <button> Set with XPath
       <handler name="onclick">
           if (mydp.getNodeName() == "record")
             var xp = "mydata:/record[1]/deeper/deeprecord[1]";
           else var xp = "mydata:/record[1]";
           mydp.setXPath( xp ); output.setText(mydp.getNodeText());
       </handler>
     </button>
   </view>
 
   <text name="output" width="200">Data will appear here.</text>
 </canvas>
edit
Flash
edit
HTML5

Attributes

Name (CSS property) Type (tag) Type (js) Default Category
context   lz.ReplicationManager   readonly
  The reference to a clonemanager from a clone.
p   lz.DataNodeMixin   read/write
  The LzDataNodeMixin that the datapointer is pointing to. Calling setAttribute on p calls LzDatapointer.setPointer.
rerunxpath   Boolean   read/write
  This determines the behavior of the datapointer in response to notification that the dataset the datapointer is mapped to has changed. If rerunxpath is true, the datapointer will always rerun its remembered XPath (set with the xpath property). If it is false, the datapointer will only verify that the node it is pointing to is still in the dataset. If it isn't, the datapointer will rerun its remembered xpath (if it has one) or will print a debug message if any further attempt is made to use its current node as the basis for a relative XPath query.
xpath string String   read/write
   

Attributes inherited from <node>

classroot, cloneManager, data, datapath, defaultplacement, id, ignoreplacement, immediateparent, inited, initstage, name, nodeLevel, options, parent, placement, styleclass, subnodes, transition

Methods

addNode()
datapointer.addNode(name : String, text : String, attrs : Dictionary);
Adds a new child node below the current context
Parameter Name Type Description
name String The name of the new node.
text String The text of the new node.
attrs Dictionary An object containing the name : value pairs of attributes for this node.
Returns Type Description
  lz.DataElement the new node
addNodeFromPointer()
datapointer.addNodeFromPointer(dp : lz.datapointer);
Duplicates the node that dp is pointing to, and appends it it to the node pointed to by this datapointer, making the added node the last on the list.
Parameter Name Type Description
dp lz.datapointer A pointer to the node to add
Returns Type Description
  lz.datapointer A pointer to the new node
comparePointer()
datapointer.comparePointer(ptr : lz.datapointer);
Determines whether this pointer is pointing to the same node as ptr.
Parameter Name Type Description
ptr lz.datapointer The datapointer to compare to this one.
Returns Type Description
  Boolean True if the datapointers are pointing to the same node.
deleteNode()
datapointer.deleteNode();
Removes the node pointed to by the datapointer. If rerunxpath is true and xpath has been set, it will be re-evaluated. Otherwise, if the deleted node has a following sibling, the pointer is repositioned at that sibling. Otherwise the pointer is set to null.
deleteNodeAttribute()
datapointer.deleteNodeAttribute(name : String);
Removes the name attribute from the current node.
Parameter Name Type Description
name String The name of the attribute to delete.
dupePointer()
datapointer.dupePointer();
Return a new datapointer that points to the same node, has a null xpath and a false rerunxpath attribute.
Returns Type Description
  lz.datapointer A new datapointer that points to the same spot as this one
getDataset()
datapointer.getDataset();
Returns a reference to the datapointer's dataset.
Returns Type Description
  lz.dataset The datapointer's dataset
getNodeAttribute()
datapointer.getNodeAttribute(name : String);
Returns the value of the current node's name attribute.
Parameter Name Type Description
name String The attribute to retrieve.
Returns Type Description
  String The value of the attribute.
getNodeAttributes()
datapointer.getNodeAttributes();
Returns the attributes of the node pointed to by the datapointer in an Object whose keys are the attribute names and whose values are the attribute values
Returns Type Description
  Object An Object which represents the keys and values of the node attributes
getNodeCount()
datapointer.getNodeCount();
Counts the number of element nodes that are children of the node that the datapointer is pointing to.
Returns Type Description
  Integer The number of child nodes for the current node
getNodeName()
datapointer.getNodeName();
Gets the name of the node that the datapointer is pointing to.
Returns Type Description
  String The name of the datapointer's node
getNodeText()
datapointer.getNodeText();
Returns a string that represents a concatenation of the text nodes beneath the current element. getNodeText and getOtherNodeText are the only way to access non-element data nodes.
Returns Type Description
  String The text in the node pointed to by the datapointer.
getNodeType()
datapointer.getNodeType();
Gets the nodeType of the node that the datapointer is pointing to.
Returns Type Description
  Integer one of LzDataElement.ELEMENT_NODE, LzDataElement.TEXT_NODE, LzDataElement.DOCUMENT_NODE or undefined if this datapointer does not point to a valid node
getXPathIndex()
datapointer.getXPathIndex();
Returns the number of the node that the datapointer is pointing to. If the datapointer does not point to a valid node, 0 is returned. Note that XPath indices are 1-based.
Returns Type Description
  Number The offset of the node or 0
isValid()
datapointer.isValid();
Tests whether or not this datapointer is pointing to a valid node.
Returns Type Description
  Boolean True if the current node is valid.
selectChild()
datapointer.selectChild(amnt : Number);
Moves down the data hierarchy to the next child node in the dataset if possible.
Parameter Name Type Description
amnt Number If given, the number of nodes to go down. If null, amnt is 1.
Returns Type Description
  Boolean True if the pointer was able to move down amnt nodes.
selectNext()
datapointer.selectNext(amnt : Number);
Selects the next sibling node in the dataset if possible.
Parameter Name Type Description
amnt Number If given, the number of nodes to advance. If null, amnt is 1.
Returns Type Description
  Boolean True if the pointer was able to move forward amnt nodes.
selectParent()
datapointer.selectParent(amnt : Number);
Moves up the data hierarchy to the next parent node in the dataset if possible.
Parameter Name Type Description
amnt Number If given, the number of nodes to go up. If null, amnt is 1.
Returns Type Description
  Boolean A Boolean indicating if the pointer was able to move up amnt nodes.
selectPrev()
datapointer.selectPrev(amnt : Number);
Selects the previous sibling node in the dataset if possible.
Parameter Name Type Description
amnt Number If given, the number of nodes to move back. If null, amnt is 1.
Returns Type Description
  Boolean True if the pointer was able to move back amnt nodes.
serialize()
datapointer.serialize();
Serialize the current element and its children to an XML string. Note that even if this datapointer's XPath ends in a terminal selector (such as @attribute or text()) this method will return the serialized text of the element that the datapointer points to.
Returns Type Description
  String A string of XML that represents all of the datapointer's contents.
setFromPointer()
datapointer.setFromPointer(dp : lz.datapointer);
Sets this datapointer to the location of the given datapointer
Parameter Name Type Description
dp lz.datapointer The datapointer which has the desired location for this datapointer.
setNodeAttribute()
datapointer.setNodeAttribute(name : String, val : String);
Set the name attribute of the current node to the val.
Parameter Name Type Description
name String The name of the attribute to set
val String The value for the attribute
setNodeName()
datapointer.setNodeName(name : String);
Sets the name of the current element to the name.
Parameter Name Type Description
name String The new name for the datapointer's node
setNodeText()
datapointer.setNodeText(val : String);
Sets the current node's text to value. When this node is serialized, the text will be represented as the first child node of this node. If the node already has one or more text children, the value of the first text node is set to the val.
Parameter Name Type Description
val String The new string for the node's text
setPointer()
datapointer.setPointer(p : lz.DataNodeMixin);
Points this datapointer at p.
Parameter Name Type Description
p lz.DataNodeMixin The new target for this datapointer.
setXPath()
datapointer.setXPath(p : String);
Sets the xpath attribute to param, and sets the current node to the node that it refers to. If the XPath contains a terminal selector such as text(), the datapointer's data property is set to that value. It is error to set a datapointer to an XPath that matches multiple nodes.
Parameter Name Type Description
p String An XPath.
Returns Type Description
  Boolean|Undefined true if the path matches a single node, false if no or multiple nodes are matched, undefined if the path is invalid.
xpathQuery()
datapointer.xpathQuery(p : Object);
Returns the result of an XPath query without changing the pointer.
Parameter Name Type Description
p Object the xpath
Returns Type Description
  any
null
if the query is invalid or matches nothing
a String
the result of an operator such as name or attribute
an LzDataElement
if the query resolves to a single node
an array of LzDataElement
if the query resolves to multiple nodes

Methods inherited from <node>

animate, applyConstraintMethod, applyData, childOf, completeInstantiation, construct, createChildren, dataBindAttribute, destroy, determinePlacement, getOption, getUID, init, lookupSourceLocator, releaseConstraint, releaseConstraintMethod, searchImmediateSubnodes, searchSubnodes, setOption, setSelected, updateData

Methods inherited from lz.Eventable

destroy, setAttribute

Events

Name Description
onerror Sent when the dataset that the datapointer is pointing to generates an error.
ontimeout Sent when a request by the dataset that the datapointer is pointing to times out.

Events inherited from <node>

onconstruct, ondata, oninit

Events inherited from lz.Eventable

ondestroy

Copyright © 2002-2010 Laszlo Systems, Inc. All Rights Reserved. Unauthorized use, duplication or distribution is strictly prohibited. This is the proprietary information of Laszlo Systems, Inc. Use is subject to license terms.

Prev  Up  Next
<datapath>  Home  lz.DataProvider