datapointer (LzDatapointer)

datapointer (LzDatapointer)
Prev	Data	Next

Name

datapointer (LzDatapointer) — A cursor in a dataset.

Synopsis

LZX: datapointer
JavaScript: LzDatapointer
Type: Class
Access: public
Topic: LFC.Data
Declared in: WEB-INF/lps/lfc/data/LzDatapointer.lzs

Description

A datapointer is an object that represents a pointer to a node in a LzDataset. The datapointer can be repositioned using either cursor movements calls such as selectNext(), or by running an XPath request via 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 7. 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/>
     
     <button> Move forward with select
       <handler name="onclick">
         if (mydp.selectNext()) var s = 
         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 = 
           else var xp = 
            output.setText();
       </handler>
     </button>
   </view>
 
   <text name="output" width="200">Data will appear here.</text>
 </canvas>

Superclass Chain

node (LzNode) » datapointer (LzDatapointer)

Known Subclasses

Known Direct Subclasses: LzDataAttrBind, datapath (LzDatapath)

Details

Properties (14)

_closeChar: <attribute name="_closeChar" />

private var _closeChar = /;
_closeNode: <attribute name="_closeNode" />

private var _closeNode = >;
context: <attribute name="context" />

public var context = null;
data: <attribute name="data" />

public var data = null;
__LZdchanged: <attribute name="__LZdchanged" />

private var __LZdchanged = false;
__LZpchanged: <attribute name="__LZpchanged" />

private var __LZpchanged = false;
__LZtrackDel: <attribute name="__LZtrackDel" />

private var __LZtrackDel = null;
__LZtracking: <attribute name="__LZtracking" />

private var __LZtracking = null;
__LZupdateLocked: <attribute name="__LZupdateLocked" />

private var __LZupdateLocked = false;
_openNode: <attribute name="_openNode" />

private var _openNode = <;
p: <attribute name="p" type="lzDataNode" />

public var p : LzDataNode = null;

The LzDataNode that the datapointer is pointing to. Calling setAttribute on attribute calls LzDatapointer.setPointer.
pathSymbols: <attribute name="pathSymbols" value="{ ... }" />

public var pathSymbols = { ... };
ppcache: <attribute name="ppcache" value="{ ... }" />

public var ppcache = { ... };
rerunxpath: <attribute name="rerunxpath" type="boolean" />

public var rerunxpath : Boolean = false;

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.

Setters (5)

Setters for virtual properties, to be used with setAttribute. A setter may or may not have a corresponding getter method; consult the Methods list in this section.

context
p
pointer
rerunxpath
xpath

Methods (63)

addNode()

public function addNode(name : String, text : String, attrs : Dictionary) : LzDataElement;

Adds a new child node below the current context

addNodeFromPointer()

public function addNodeFromPointer(dp : LzDatapointer) : LzDatapointer;

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.

childOrSelf()

private function childOrSelf(p);

comparePointer()

public function comparePointer(ptr : LzDatapointer) : Boolean;

Determines whether this pointer is pointing to the same node as ptr.

_dbg_name()

private function _dbg_name();

deleteNode()

public function 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()

public function deleteNodeAttribute(name : String);

Removes the name attribute from the current node.

destroy()

private function destroy(recur);

dupePointer()

public function dupePointer() : LzDataPointer;

Return a new datapointer that points to the same node, has a nullxpath and a falsererunxpath attribute.

finishRootNode()

private function finishRootNode(n);

getContext()

private function getContext();

This is the shared interface between dataset and datapointer that allows one datapointer to function as the datacontext for another

getDataset()

public function getDataset() : LzDataset;

Returns a reference to the datapointer's dataset.

getLocalDataContext()

private function getLocalDataContext(pp);

Locates a local data context based on the parsed path

getNodeAttribute()

public function getNodeAttribute(name : String) : String;

Returns the value of the current node's name attribute.

getNodeAttributes()

public function getNodeAttributes() : Object;

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

getNodeCount()

public function getNodeCount() : Integer;

Counts the number of element nodes that are children of the node that the datapointer is pointing to.

getNodeName()

public function getNodeName() : String;

Gets the name of the node that the datapointer is pointing to.

getNodeOffset()

public function getNodeOffset() : Number;

Returns the number of the node that the datapointer is pointing to. Note that XPath indices are 1-based.

getNodeText()

public function getNodeText() : String;

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.

getOtherNodeText()

public function getOtherNodeText(n : LzDataNode) : String;

Returns a string that represents a concatenation of the text nodes beneath the node n. This is currently the only way to access non-element data nodes.

getXPath()

public function getXPath(p : Object);

Returns the result of an XPath query without changing the pointer. The result can be:

a string -- the result of an operator such as name or attribute
a single datapointer -- if the query resolves to a single node
an array of datapointers -- if the query resolves to multiple nodes

gotError()

private function gotError(msg);

Called when the datapointer receives an onerror event from the dataset it's pointing to.

gotTimeout()

private function gotTimeout(msg);

Called when the datapointer's dataset's request times out...

isValid()

public function isValid() : Boolean;

Tests whether or not this datapointer is pointing to a valid node.

__LZcheckChange()

private function __LZcheckChange(chgpkg);

__LZcheckDotDot()

private function __LZcheckDotDot(chgpkg);

__LZdoSelect()

private function __LZdoSelect(selector, amnt);

__LZgetLast()

private function __LZgetLast();

__LZgetNodes()

private function __LZgetNodes(pathobj, p, startpoint);

__LZgetPosition()

private function __LZgetPosition();

__LZHandleDocChange()

private function __LZHandleDocChange(chgpkg);

__LZHandleMultiNodes()

private function __LZHandleMultiNodes(n);

__LZHandleNoNodes()

private function __LZHandleNoNodes();

__LZHandleSingleNode()

private function __LZHandleSingleNode(n);

__LZneedsOpUpdate()

private function __LZneedsOpUpdate(chgpkg);

__LZprocessOperator()

private function __LZprocessOperator(p, pp, depends);

__LZsendUpdate()

private function __LZsendUpdate(upd, upp);

__LZsetData()

private function __LZsetData();

__LZsetRerunXPath()

private function __LZsetRerunXPath(rrx);

__LZsetTracking()

private function __LZsetTracking(who, force : Boolean);

This method registers the datapointer delegate to listen for onDocumentChange events that are sent by the top of the DOM of which the datapointer's node is a member.

__LZsetupDotDot()

private function __LZsetupDotDot(p);

__LZsimpleOperatorUpdate()

private function __LZsimpleOperatorUpdate();

makeElementNode()

private function makeElementNode(attrs, name, par);

makeRootNode()

private function makeRootNode();

makeTextNode()

private function makeTextNode(text, par);

nodeByName()

private function nodeByName(name, range, p);

Select node by name at the current level. Returns null, an offset, or an array of offsets.

parsePath()

private function parsePath(pa);

Parses a fully qualified XPath and yields an object with the components listed below. These are cached. Canonical xpath: ../nodea/nodeb[2]/@foo Canonical xpath: nodea/nodeb[2]/@* Canonical xpath: ./nodea/nodeb[2-]/text() Canonical xpath: /nodea/nodeb[8]/* Canonical xpath: dset:/nodea/nodeb[-8] Canonical xpath: dsrc:dset:/nodea/nodeb[2-8]

runXPath()

private function runXPath();

selectChild()

public function selectChild(amnt : Number) : Boolean;

Moves down the data hierarchy to the next child node in the dataset if possible.

selectNext()

public function selectNext(amnt : Number) : Boolean;

Selects the next sibling node in the dataset if possible.

selectNextParent()

private function selectNextParent();

selectParent()

public function selectParent(amnt : Number) : Boolean;

Moves up the data hierarchy to the next parent node in the dataset if possible.

selectPrev()

public function selectPrev(amnt : Number) : Boolean;

Selects the previous sibling node in the dataset if possible.

sendDataChange()

private function sendDataChange(chgpkg);

serialize()

public function serialize() : String;

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.

setDataContext()

private function setDataContext(dc);

setFromPointer()

public function setFromPointer(dp : LzDataPointer);

Sets this datapointer to the location of the given datapointer

setNodeAttribute()

public function setNodeAttribute(name : String, val : String);

Set the name attribute of the current node to the val.

setNodeName()

public function setNodeName(name : String);

Sets the name of the current element to the name.

setNodeText()

public function 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.

setPointer()

public function setPointer(p : LzDataNode);

Points this datapointer at p.

setXPath()

public function 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.

xpathQuery()

public function xpathQuery(p : Object) : any;

Returns the result of an XPath query without changing the pointer.

Events (6)

ondata: <attribute name="ondata" />

public event ondata;

Sent when the data selected by this datapointer's xpath changes. For XPaths which select a datanode, this means that the datapointer is pointing to a new node. For XPaths which select text data, this means that the datapointer is pointing to a new node, or that the text selected by the xpath has changed. Note that a datapointer mapped to a data node will not receive ondata when the node, say, changes one of its attributes.
onDocumentChange: <attribute name="onDocumentChange" />

public event onDocumentChange;
onerror: <attribute name="onerror" />

public event onerror;

Sent when the dataset that the datapointer is pointing to generates an error.
onp: <attribute name="onp" />

public event onp;
onrerunxpath: <attribute name="onrerunxpath" />

public event onrerunxpath;
ontimeout: <attribute name="ontimeout" />

public event ontimeout;

Sent when a request by the dataset that the datapointer is pointing to times out.

Prototype Properties (1)

defaultattrs: <attribute name="defaultattrs" value="{ ... }" />

public var defaultattrs = { ... };

LZX Synopsis

</class>

JavaScript Synopsis

public LzDatapointer extends LzNode {

private var _closeChar = /;

private var _closeNode = >;

public var context = null;

public var data = null;

private var __LZdchanged = false;

private var __LZpchanged = false;

private var __LZtrackDel = null;

private var __LZtracking = null;

private var __LZupdateLocked = false;

private var _openNode = <;

public var p : LzDataNode = null;

public var pathSymbols = { ... };

public var ppcache = { ... };

public var rerunxpath : Boolean = false;

prototype public function addNode (name : String, text : String, attrs : Dictionary) : LzDataElement;

prototype public function addNodeFromPointer (dp : LzDatapointer) : LzDatapointer;

prototype private function childOrSelf (p);

prototype public function comparePointer (ptr : LzDatapointer) : Boolean;

prototype private function _dbg_name ();

prototype public var defaultattrs = { ... };

prototype public function deleteNode ();

prototype public function deleteNodeAttribute (name : String);

prototype private function destroy (recur);

prototype public function dupePointer () : LzDataPointer;

prototype private function finishRootNode (n);

prototype private function getContext ();

prototype public function getDataset () : LzDataset;

prototype private function getLocalDataContext (pp);

prototype public function getNodeAttribute (name : String) : String;

prototype public function getNodeAttributes () : Object;

prototype public function getNodeCount () : Integer;

prototype public function getNodeName () : String;

prototype public function getNodeOffset () : Number;

prototype public function getNodeText () : String;

prototype public function getOtherNodeText (n : LzDataNode) : String;

prototype public function getXPath (p : Object);

prototype private function gotError (msg);

prototype private function gotTimeout (msg);

prototype public function isValid () : Boolean;

prototype private function __LZcheckChange (chgpkg);

prototype private function __LZcheckDotDot (chgpkg);

prototype private function __LZdoSelect (selector, amnt);

prototype private function __LZgetLast ();

prototype private function __LZgetNodes (pathobj, p, startpoint);

prototype private function __LZgetPosition ();

prototype private function __LZHandleDocChange (chgpkg);

prototype private function __LZHandleMultiNodes (n);

prototype private function __LZHandleNoNodes ();

prototype private function __LZHandleSingleNode (n);

prototype private function __LZneedsOpUpdate (chgpkg);

prototype private function __LZprocessOperator (p, pp, depends);

prototype private function __LZsendUpdate (upd, upp);

prototype private function __LZsetData ();

prototype private function __LZsetRerunXPath (rrx);

prototype private function __LZsetTracking (who, force : Boolean);

prototype private function __LZsetupDotDot (p);

prototype private function __LZsimpleOperatorUpdate ();

prototype private function makeElementNode (attrs, name, par);

prototype private function makeRootNode ();

prototype private function makeTextNode (text, par);

prototype private function nodeByName (name, range, p);

prototype public event ondata ;

prototype public event onDocumentChange ;

prototype public event onerror ;

prototype public event onp ;

prototype public event onrerunxpath ;

prototype public event ontimeout ;

prototype private function parsePath (pa);

prototype private function runXPath ();

prototype public function selectChild (amnt : Number) : Boolean;

prototype public function selectNext (amnt : Number) : Boolean;

prototype private function selectNextParent ();

prototype public function selectParent (amnt : Number) : Boolean;

prototype public function selectPrev (amnt : Number) : Boolean;

prototype private function sendDataChange (chgpkg);

prototype public function serialize () : String;

prototype private function setDataContext (dc);

prototype public function setFromPointer (dp : LzDataPointer);

prototype public function setNodeAttribute (name : String, val : String);

prototype public function setNodeName (name : String);

prototype public function setNodeText (val : String);

prototype public function setPointer (p : LzDataNode);

prototype public function setXPath (p : String);

prototype public function xpathQuery (p : Object) : any;

}

Copyright © 2002-2007 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.