Author: jsundman
Date: 2007-11-15 17:31:57 -0800 (Thu, 15 Nov 2007)
New Revision: 7302
Modified:
openlaszlo/trunk/docs/src/developers/data-overview.dbk
openlaszlo/trunk/docs/src/developers/two-way-databinding.dbk
Log:
random cleanup of data chapters
Modified: openlaszlo/trunk/docs/src/developers/data-overview.dbk
===================================================================
--- openlaszlo/trunk/docs/src/developers/data-overview.dbk 2007-11-15
23:41:36 UTC (rev 7301)
+++ openlaszlo/trunk/docs/src/developers/data-overview.dbk 2007-11-16
01:31:57 UTC (rev 7302)
@@ -4,7 +4,7 @@
<section><title>Overview</title>
<para>
-In this chapter we introduce key concepts about data and databinding at a high
level. There is little code, but a fair amount of diagramware to illustrate
databinding and replication.
+In this chapter we introduce key concepts about data and databinding at a high
level. There is little code, but a fair amount of illustrations to illustrate
databinding and replication.
</para>
<para>
LZX is designed to make it easy to manipulate data and tie that data to a user
interface. In particular, LZX provides for:
@@ -18,18 +18,18 @@
In OpenLaszlo, we work with data in XML format, and navigate through it using
XPath syntax. So, this chapter goes over some fundamental concepts about XML
and Xpath.
</para>
<para>
-Databinding marries the content of an XML datastructure with the OpenLaszlo
objects (such as nodes, or views). Databinding allows separation of content
from presentation, using datapaths which are objects that connect views to
data. Attribute values of nodes and views update automatically when the data to
which they are bound changes. There are two related "families" of APIs in LZX,
a declarative one that uses the <datapointer>, <datapath> and
<dataset> tags, a declarative API based on the LzDataNode, LzDataElement
and LzDataText classes, which have methods based on the Document Object Model,
or DOM.</para>
+Databinding marries the content of an XML datastructure with the OpenLaszlo
objects (such as nodes, or views). Databinding allows separation of content
from presentation, using datapaths, which are objects that connect views to
data. Attribute values of nodes and views update automatically when the data to
which they are bound changes. There are two related "families" of APIs in LZX,
a declarative one that uses the <datapointer>, <datapath> and
<dataset> tags, a declarative API based on the LzDataNode, LzDataElement
and LzDataText classes, which have methods based on the Document Object Model,
or DOM.</para>
<para>
In this chapter we give a conceptual overview of the logical differences
between the DOM-based and datapointer/datapath-based ways of manipulating data,
with a preview of how these approaches will be reconciled in later chapters.
</para>
<para>
-Datareplication is introduced, and the difference between implicit and
explicit replication.
+Datareplication means the use of pattern matching to create zero, one, or more
LZX objects according to the contents of a dataset. In this chapter
datareplication is introduced, as is the difference between implicit and
explicit replication.
</para>
<para>
We then explain some useful design patterns involving datasets, both locally
on the client, and between client and server.
</para>
<para>
-Finally, we introduce the abstract concept of the dataprovider.
+Finally, we introduce the concept of the dataprovider, which is an abstraction
that allows advanced developers to implement protocols other than HTTP for
client-server data exchange, while keeping intact the syntax of all other data
operations.
</para>
</section>
<section><title>What is XML?</title>
@@ -40,7 +40,7 @@
</para>
<para>
-If you don't already know what the words
+A brief refresher follows, but if you don't already know what the words
<glossterm>document</glossterm>, <glossterm>element</glossterm> and
<glossterm>attribute</glossterm> mean in the context of XML, you
should probably read one of the following decent introductions or grab
Modified: openlaszlo/trunk/docs/src/developers/two-way-databinding.dbk
===================================================================
--- openlaszlo/trunk/docs/src/developers/two-way-databinding.dbk
2007-11-15 23:41:36 UTC (rev 7301)
+++ openlaszlo/trunk/docs/src/developers/two-way-databinding.dbk
2007-11-16 01:31:57 UTC (rev 7302)
@@ -1,34 +1,35 @@
-
<chapter id="two-way-databinding">
<title>Two-way databinding</title>
+<section><title>Introduction</title>
<para>
-Mixing static and dynamic databinding, and also updating datasets based on
user action.
+Until now, we've looked mostly at the case where changes in a dataset update
the visible LZX nodes to which the data is bound. Now we'll take a look at the
opposite direction, that is, when changes in the views—for example, when
an application user types something into a text field— get propagated
back into the dataset. This is often accomplished by mixing static and dynamic
databinding.
</para>
<para>
-This chapter explains the "funhouse mirror" quasi-equivalence of the
datapath/datapointer APIs. There are two goals for the chapter:
-(1) at a minimum, make clear the distinction between the two kinds of
approaches; that is, between moving nodes and moving pointers to nodes.
-(2) hopefully, give enough explanation and examples such that people can mix
and match between the two approaches without getting hopelessly confused.
+Therefore, as part of this discussion, we'll take a closer look at the
correspondence between the datapath/datapointer APIs and their equivalence in
DOM/LzNode APIs.
</para>
<para>
-If the data changes, the data-bound object will update.
+As we have seen, once a view has been bound to a dataset, if the data changes,
the data-bound object also updates.
Sometimes, with input controls, you need to bind back into the data.
- To trigger two-way databinding:
- Call datapath.updateData().
- Optionally, define an updateData() method at the root of
the control.
- This method is called automatically.
- Returns the value to put back into the data.
</para>
<para>
-Outline:
-A comparison of datapath/datapointer APIs and DOM APIs
--- How to do equivalent action using either technique
----A table showing equivalent and quasi-equivalent methods
--- Explanation of actions that can be performed using only one or the other
approach.
-The .p property -- the gateway between static and dynamic APIs
--- Every datapath/datapointer has a .p property, which is the node to which it
points.
---- therefore, you can use the DOM APIs on the .p attribute of datapaths and
datapointers
+To trigger two-way databinding:
</para>
-<article lang="">
+<itemizedlist spacing="compact">
+ <listitem><para>
+ Call datapath.updateData().
+ </para></listitem>
+ <listitem><para>
+ Optionally, define an updateData() method at the root of the control. This
method is called automatically and returns the value to put back into the data.
+ </para></listitem>
+</itemizedlist>
+
+<para>
+Explanation of actions that can be performed using only one or the other
approach.
+
+</para>
+</section>
+<section><title>Equivalence of Static and Dynamic APIs</title>
+<!--article lang=""-->
<informaltable frame="all">
<tgroup cols="3">
<tbody>
@@ -234,7 +235,7 @@
</tgroup>
</informaltable>
-</article>
+<!--/article-->
<para>
Datapointer and DataElement
@@ -244,6 +245,7 @@
---Using a LzDataelement
---Destroying a Node
</para>
+</section>
<section>
<title>
Changing Data Binding with Attribute p</title>
@@ -256,6 +258,13 @@
<para>
parent.firstview.datapath.setAttribute("p",
parent.secondview.datapath.p);
</para>
+</section>
+<section>
+<title>The "p" attribute of datapointers</title>
+<para>
+The .p property is the gateway between static and dynamic APIs.
+Every datapath and datapointer has a .p property, which is the LzNode to which
it points. Therefore, you can use the DOM APIs on the .p attribute of datapaths
and datapointers.
+</para>
<example role="live-example">
<title>Changing Data Binding with Attribute p </title>
<programlisting language="lzx">
@@ -291,11 +300,12 @@
<para>
parent.lastnameedit.datapath.updateData();
</para>
-</section><title>
+</section>
+<section><title>
The .data property</title>
<para>
-- .data is shorthand for datapath.p
-- Objects like views have a .data property when they are databound and
replicated. Otherwise .data is null.
</para>
-
+</section>
</chapter>
_______________________________________________
Laszlo-checkins mailing list
[email protected]
http://www.openlaszlo.org/mailman/listinfo/laszlo-checkins
