[Laszlo-checkins] r7732 - openlaszlo/trunk/docs/src/developers

[lou@openlaszlo.org]

Author: lou
Date: 2008-01-04 13:37:28 -0800 (Fri, 04 Jan 2008)
New Revision: 7732

Added:
   openlaszlo/trunk/docs/src/developers/datareplication.dbk
Modified:
   openlaszlo/trunk/docs/src/developers/databinding.dbk
   openlaszlo/trunk/docs/src/developers/index.dbk
Log:
Change 20080104-lou-E by lou at loumac.local on 2008-01-04 14:36:06 AST
    in /Users/lou/src/svn/openlaszlo/trunk
    for http://svn.openlaszlo.org/openlaszlo/trunk

Summary: add explicit data replication to the dguide

New Features:

Technical Reviewer: tucker
QA Reviewer: (pending)
Doc Reviewer: (pending)

Details:

Create a new Data Replication chapter.
     http://localhost:8080/trunk/docs/developers/datareplication.html
Split out existing data replication doc from Data Access and Binding
     chapter, and add it to new chapter.
Add explicit replication to the new chapter.

Documentation for explicit replication comes from the wiki: http://wiki.openlaszlo.org/Explicit_Replication

This documentation was basically cut and pasted, with some reorganization,
and added intro material, from the wiki.
    



Modified: openlaszlo/trunk/docs/src/developers/databinding.dbk
===================================================================
--- openlaszlo/trunk/docs/src/developers/databinding.dbk	2008-01-04 21:20:18 UTC (rev 7731)
+++ openlaszlo/trunk/docs/src/developers/databinding.dbk	2008-01-04 21:37:28 UTC (rev 7732)
@@ -1,6 +1,7 @@
 <chapter id="databinding">
  
 <title>Data Access and Binding</title>
+<!-- the section on data replication has been moved to its own chapter. IORIO 20 jan 2008 -->
 <!-- remove commented out sample code that was ignored by the build. IORIO 20 nov 2007 -->
 <!-- change link for data-tutorial per LPP-4923, IORIO 17 oct 2007 -->
 <para>This chapter describes various methods of tying XML data structures into your LZX application.  See 
@@ -719,243 +720,4 @@
 </example>
 
 
-<para/></section></section><section id="databinding.replication"><title>Data replication</title>
-
-<para>As shown in some of the examples above, datapaths that match
-multiple nodes cause their nodes to be <indexterm significance="preferred"><primary>replicated</primary></indexterm><glossterm>replicated</glossterm>. By
-"replicated", we mean that for each match of the XPath expression one
-instance of the mapped view is created. This is one of the most
-important features of the databinding facilities in LZX.</para>
-
-<para/><section><title>Replication Manager</title>
-
-<para>A <indexterm significance="preferred"><primary>replication manager</primary></indexterm><glossterm>replication manager</glossterm> is a runtime object that is
-created automatically whenever data replication occurs as a result of
-a datapath matching more than once. When that happens, the
-<indexterm><primary>name</primary></indexterm><sgmltag class="attribute">name</sgmltag> or <indexterm><primary>id</primary></indexterm><sgmltag class="attribute">id</sgmltag> attribute of
-the replicated view (if the view is named) is taken over by the
-replication manager, and from then on referring to that name will
-access the replication manager object, and not the view. In order to
-reference the replicated views, known as <indexterm significance="preferred"><primary>clones</primary></indexterm><glossterm>clones</glossterm>, you should
-use the <indexterm><primary>LzReplicationManager</primary></indexterm><classname>LzReplicationManager</classname> API.</para>
-
-<para/><section><title>The <indexterm><primary>replication</primary></indexterm><sgmltag class="attribute">replication</sgmltag> attribute</title>
-
-<para>If a datapath matches multiple nodes, it will create a replication
-manager.  If <indexterm><primary>replication</primary></indexterm><sgmltag class="attribute">replication</sgmltag> is <literal>normal</literal>
-(the default), then the replication manager will be a direct instance
-of <indexterm><primary>LzReplicationManager</primary></indexterm><classname>LzReplicationManager</classname>.  If it is
-<literal>lazy</literal>, it will instead create a
-<indexterm><primary>LzLazyReplicationManager</primary></indexterm><classname>LzLazyReplicationManager</classname>.</para>
-
-<para/></section><section><title>Clones and the <indexterm><primary>onclones event</primary></indexterm><literal>onclones</literal> event</title>
-
-<para>As mentioned above, when a view is replicated, its copies are
-managed by the replication manager object.  Once clones are created,
-the instance of the replication manager contains references to them in
-the <indexterm><primary>clones</primary></indexterm><sgmltag class="attribute">clones</sgmltag> property, which is an array of
-views. Note that <indexterm><primary>LzReplicationManager</primary></indexterm><classname>LzReplicationManager</classname> extends
-<indexterm><primary>LzDatapath</primary></indexterm><classname>LzDatapath</classname>, and a cloned view along with its
-datapath is replaced with the replication manager object. Armed with
-this knowledge, we have a technique for determining when a view is
-cloned. The example below demonstrates the use of the clones property
-by declaring a handler for the <indexterm><primary>onclones event</primary></indexterm><literal>onclones</literal> event on the
-view's datapath.</para>
-<example role="live-example">
-   <title>Using clones and the onclones event</title>
-   <programlisting language="lzx">
-   <textobject><textdata fileref="programs/databinding-$25.lzx"/></textobject> 
-   </programlisting>
-</example>
-
-<para>Because the <indexterm><primary>onclones event</primary></indexterm><literal>onclones</literal> event is sent when the
-<indexterm><primary>clones</primary></indexterm><sgmltag class="attribute">clones</sgmltag> attribute is set, it only signals the
-start of view replication, but in this example it is used to determine
-the exact moment when replication is finished. Since replicated views
-are initialized in the same order they are in inserted in the clones
-array, we only need to wait for the oninit event for the last clone in
-the list. This is necessary because initialization of the
-<indexterm><primary>tab</primary></indexterm><classname>tab</classname> elements takes a non-zero amount of time,
-and an attempt to perform an operation on their container — tab
-slider — before it is completed will leave the component in an
-inconsistent state. For illustration purposes, the second
-<indexterm><primary>tabslider</primary></indexterm><classname>tabslider</classname> has this problem, whereby
-selecting the first <indexterm><primary>tab</primary></indexterm><classname>tab</classname> element too soon
-renders its parent unusable (the other
-<indexterm><primary>tabelement</primary></indexterm><classname>tabelement</classname>s are gone).</para>
-
-<para>This example also takes advantage of the fact that, by default, views
-become visible when they consume data (see section on visibility of
-datamapped views above). Before the button is clicked, there is a
-single <indexterm><primary>tabelement</primary></indexterm><classname>tabelement</classname> object within the
-tabslider. However, it is kept invisible until it receives data, at
-which point its replication occurs, and its clones are displayed.</para>
-
-<para/></section><section><title>Nodes and the <indexterm><primary>onnodes event</primary></indexterm><literal>onnodes</literal> event</title>
-
-<para>Similarly to the <indexterm><primary>clones</primary></indexterm><sgmltag class="attribute">clones</sgmltag> property,
-<indexterm><primary>LzReplicationManager</primary></indexterm><classname>LzReplicationManager</classname> maintains a list of
-matched data nodes in the <indexterm><primary>nodes</primary></indexterm><sgmltag class="attribute">nodes</sgmltag> property. It is
-an array of <indexterm><primary>LzDataElement</primary></indexterm><classname>LzDataElement</classname> objects that are
-mapped to the replicated views, and is available before any clones are
-created. And as with the <indexterm><primary>onclones event</primary></indexterm><literal>onclones</literal> event, a handler
-for <indexterm><primary>onnodes event</primary></indexterm><literal>onnodes</literal> may be declared to respond to data
-replication in a custom way. The code below qualifies the value of
-<indexterm><primary>name</primary></indexterm><sgmltag class="attribute">name</sgmltag> attribute of each replicated data node
-with the value of the text field, if any.</para>
-<example role="live-example">
-   <title>Using the nodes property</title>
-   <programlisting language="lzx">
-   <textobject><textdata fileref="programs/databinding-$26.lzx"/></textobject> 
-   </programlisting>
-</example>
-
-
-
-<para/></section></section><section id="databinding.pooling"><title>Pooling</title>
-
-<para>If your application uses data replication and the data backing
-replicated views changes at runtime, by default the replication
-manager destroys and re-creates the replicated views whose data has
-changed. The typical scenarios when this will occur are a change in
-the datapath of the replicated view, or deletion/addition of rows to
-the dataset. Because the dataset may contain many data elements, this
-adjustment is often an expensive operation that results in a
-noticeable flicker of the user interface while view removal/creation
-takes place.</para>
-
-<para>In order to make updates to datamapped elements more efficient, you can declare the datapath that will match multiple
-nodes with the <indexterm><primary>pooling</primary></indexterm><sgmltag class="attribute">pooling</sgmltag> attribute set to
-<literal>true</literal>. The effect of this is that the views that have already been
-created as a result of replication will be reused internally, instead
-of re-created. Since the replication manager only needs to remap the
-changed data to the existing clones, data updates are reflected in UI
-much faster than they would be if the runtime had to create new views. 
-Consider the following example.</para>
-<example role="live-example">
-   <title>Using pooling to optimize data updates</title>
-   <programlisting language="lzx">
-   <textobject><textdata fileref="programs/databinding-$27.lzx"/></textobject> 
-   </programlisting>
-</example>
-
-
-<para>In the code above, we handle data removal by going through the list of data nodes, and deleting the nodes whose 
-<indexterm><primary>checked</primary></indexterm><sgmltag class="attribute">checked</sgmltag> attribute is set to "true". Note how this attribute is controlled by and mapped to the value of 
-the corresponding checkbox. Any change in the state of the checkbox results in an update to the data node attribute, 
-and vice versa — when views are created or reused (due to deletion), the appearance of their checkboxes is unchecked 
-because initially the attribute is not set.</para><para>This kind of syncing to the underlying data is generally required
-when pooling is in effect and the state of the visual elements can be changed as a result of a user interaction. 
-In a simpler case, the UI would not be modifiable by the user, so the data flow is one way only and the views are 
-completely data-driven, and therefore consistency of data with its presentation would be maintained automatically.</para> 
-
-<para/><section><title>When not to use pooling</title>
-
-<para>Pooling is generally a good optimization in cases where
-the data completely informs the state of a replicated view. If the
-view has additional state which can change through user interaction or
-depends on setting attributes at init time, then this option cannot
-usually be used. The default value for the <indexterm><primary>pooling</primary></indexterm><sgmltag class="attribute">pooling</sgmltag> on <indexterm><primary>dataset</primary></indexterm><sgmltag class="element">&lt;dataset&gt;</sgmltag> is "false", except when
-replication is set to <literal>lazy</literal>, in which case it must be
-true, as described below.
-</para>
-
-<para/></section></section><section id="databinding.lazy-replication"><title>Lazy replication</title>
-<?ignore Needs work
-?>
-<para>If a datapath's <indexterm><primary>replication</primary></indexterm><sgmltag class="attribute">replication</sgmltag> attribute is set
-to <literal>lazy</literal>, then a match to multiple nodes will create an
-<indexterm><primary>LzLazyReplicationManager</primary></indexterm><classname>LzLazyReplicationManager</classname> instead of an
-<indexterm><primary>LzReplicationManager</primary></indexterm><classname>LzReplicationManager</classname>. This kind of replication manager is called "lazy" because it doesn't do the work of creating a view until it has to, and it does the bare minimum of work. The lazy replication
-manager creates only enough replicated views necessary to display the
-data, so there is not a view for each data node. This enables the
-display of very large datasets.</para>
-
-<para>Because the <indexterm><primary>LzLazyReplicationManager</primary></indexterm><classname>LzLazyReplicationManager</classname> is relatively specialized, there are several restrictions on its use:</para>
-
-<itemizedlist spacing="compact"><listitem><para>The replicated views should be contained in a view which is not the view that clips. The replicated views can be positioned by moving this container. This container will be sized to the size of the replicated list.</para></listitem><listitem><para>The parent of the container must be a view that clips (that is, its <indexterm><primary>clip</primary></indexterm><sgmltag class="attribute">clip</sgmltag> attribute is set to "true".</para></listitem><listitem><para>The replicated view cannot change its size in the replication axis, and the size cannot be a constraint. If the replicated view is sized by its contents, then lazy replication may not work in all cases.</para></listitem><listitem><para>The data should completely inform the display of the view. Any attributes that are changed through interaction with a replicated view should be stored in the dataset.</para></listitem><listitem><para>Selection within the replicated views should be controlled by a <indexterm><primary>LzDataSelectionManager</primary></indexterm><classname>LzDataSelectionManager</classname>.</para></listitem></itemizedlist>
-<para>This example shows use of the lazy replication manager to display a large dataset.  The replication does not create a view for each node in the dataset; rather it only creates enough views to fill the clipping view that contains it.
-As you click the "Make it bigger" button, you will see that more items from the list are shown.  Notice also that these views are actually being created when you press the button, as you can see by then "number of subviews" value at the top of the canvas.
-</para>
-<example role="live-example">
-   <title>Using a lazyreplicationmanager to display a large dataset</title>
-   <programlisting language="lzx">
-   <textobject><textdata fileref="programs/databinding-$28.lzx"/></textobject> 
-   </programlisting>
-</example>
-
-
-
-<para>See the <ulink url="../../examples/paging.lzx" type="">paging.lzx example</ulink> for
-another example of lazy replication.</para>
-<para/></section><section><title>$path bindings and replication</title>
-<para>
-Only a datapath can cause replication. Although it might seem that $path might be used to implicitly force replication, it will not. A $path expression will only yield a single value. If it matches multiple values, it is an error and it will act as if it matched none.  In the example below, note that The $path constraint does not update when the enclosing datapath is set.
-</para>
-<example role="live-example">
-   <title>$path does not replicate</title>
-   <programlisting language="lzx">
-   <textobject><textdata fileref="programs/databinding-$29.lzx"/></textobject> 
-   </programlisting>
-</example>
-
-
-<para/></section><section><title>$path syntax to determine order of replicated views</title>
-<para>
-Sometimes you want to know the position of a view; for example, say you wanted to alternate background colors. You might think of checking for the position of the view in its <indexterm><primary><literal>oninit()</literal></primary></indexterm><methodname>oninit()</methodname> method.
-</para>
-<para>
-However, if you're using datapath pooling (you'll probably want to for long lists), the <literal>oninit</literal> events for views created by data replication don't necessarily fire because the views may be reused. In that case, the <literal>ondata</literal> event will fire, so you might consider using the <indexterm><primary><literal>ondata()</literal></primary></indexterm><methodname>ondata()</methodname> handler. However, incrementing a counter isn't the most reliable way to determine order because views may not instantiate in linear order. </para>
-<para>
-That's why it's better to use a datapath expression. Add attribute like this inside your replicated node:
-</para>
-<programlisting>
-&lt;attribute name="pos" value="$path{'position()'}"/&gt;
-</programlisting>
-<para>
-This will tie the pos attribute to the physical position in the data. You can then then tie the background color like so:
-</para>
-<programlisting>
-&lt;attribute name="bgcolor" value="${this.pos % 2 == 0 ? 0x00EEEE : 0x00DDDD}"/&gt; 
-</programlisting>
-
-<para/></section><section id="databinding.procedural_and_replicated"><title>Be careful of mixing replication and classes declared procedurally</title>
-<para>
-Views that you create procedurally are not the same as "clones" created by data replication. In fact, data replication overrides procedurally created views. For example:
-</para>
-<orderedlist spacing="compact"><listitem><para>Declare a view.</para></listitem><listitem><para>Add subviews to it (procedurally), and alter its properties.</para></listitem><listitem><para>Set a datapath on the view (from step 1) that would make it replicate.</para></listitem></orderedlist>
-<para>
-Changes made in step 2 will be ignored after replication.
-</para>
-
-<?ignore <h4>Lazy replication gotchas</h4>
-<todo>Sizing, required structure, attribute resetting</todo>
-
-<h4>Using a dataselectionmanager</h4>
-
-        
-<h2>Tags/APIs discussed in this chapter</h2>
-<ul>
-    <li><classname link="true">LzDataElement</classname></li>
-    <li><classname link="true">LzDataNode</classname></li>
-    <li><classname link="true">LzDataText</classname></li>
-    <li><classname link="true">LzDatapointer</classname></li>
-    <li><classname link="true">LzDatapath</classname></li>
-    <li><classname link="true">LzReplicationManager</classname></li>
-    <li><classname link="true">LzLazyReplicationManager</classname></li>
-    <li><classname link="true">LzDataSelectionManager</classname></li>
-</ul>
-
-<fixme>
-..  Cleanup structure a bit and add nicer intro
-
-..  There should be a discussion early of LzNodes and LzDatanodes as well as the special 'datapath' attribute of LzNodes that takes an XPath expression and binds the LzDatanodes to LzNodes (and replicates the LzNodes if the XPath matches multiple LzDatanodes).  (edb: this is my defn of what Laszlo databinding *is*.)
-
-..  move/splice descrition of datasource/dataset with data transport chapter
-
-.. Add description of '/', '.', and '..' in XPath
-
-.. Possibly simplify examples where possible (avoid use of ?lzt=xml).
-</fixme>
-?>
 <para/></section></section></chapter>

Added: openlaszlo/trunk/docs/src/developers/datareplication.dbk


Property changes on: openlaszlo/trunk/docs/src/developers/datareplication.dbk
___________________________________________________________________
Name: svn:mime-type
   + text/plain
Name: svn:eol-style
   + native

Modified: openlaszlo/trunk/docs/src/developers/index.dbk
===================================================================
--- openlaszlo/trunk/docs/src/developers/index.dbk	2008-01-04 21:20:18 UTC (rev 7731)
+++ openlaszlo/trunk/docs/src/developers/index.dbk	2008-01-04 21:37:28 UTC (rev 7732)
@@ -89,6 +89,7 @@
     <xi:include href="data-structures.dbk"/>
     <!-- xi:include href="data-overview.dbk"/-->
     <xi:include href="databinding.dbk"/>
+    <xi:include href="datareplication.dbk"/>
     <xi:include href="data_app.dbk"/>
     <!-- xi:include href="static-databinding.dbk"/ -->
     <!-- xi:include href="dynamic-databinding.dbk"/ -->