Revision: 9014
Author: [email protected]
Date: Mon Oct 11 09:52:54 2010
Log: Edited wiki page Editors through web user interface.
http://code.google.com/p/google-web-toolkit/source/detail?r=9014
Modified:
/wiki/Editors.wiki
=======================================
--- /wiki/Editors.wiki Mon Oct 11 06:27:34 2010
+++ /wiki/Editors.wiki Mon Oct 11 09:52:54 2010
@@ -45,5 +45,73 @@
== Definitions ==
- * _Bean-like object_: An object that supports retrieval of properties
through strongly-typed `Foo getFoo()` methods with optional `void
setFoo(Foo foo);` methods.
- * _Editor_: An object that supports editing zero or more properties of a
+ * _Bean-like object_: (henceforth "bean") An object that supports
retrieval of properties through strongly-typed `Foo getFoo()` methods with
optional `void setFoo(Foo foo);` methods.
+ * _Editor_: An object that supports editing zero or more properties of a
bean.
+ * An Editor may be composed of an arbitrary number of sub-Editors that
edit the properties of a bean.
+ * Most Editors are Widgets, but the framework does not require this.
It is possible to create "headless" Editors that perform solely
programmatically-driven changes.
+ * _Driver_: The "top-level" controller used to attach a bean to an
Editor. The driver is responsible for descending into the Editor hierarchy
to propagate data. Examples include the `SimpleBeanEditorDriver` and the
`RequestFactoryEditorDriver`.
+ * _Adapter_: One of a number of provided types that provide "canned"
behaviors for the Editor framework.
+
+== General workflow ==
+
+ * Instantiate and initialize the Editors.
+ * If the Editors are UI based, this is usually the time to call
`UiBinder.createAndBindUi()`
+ * Instantiate and initialize the driver.
+ * Drivers are created through a call to `GWT.create()` and the
specific details of the initialization are driver-dependent, although
passing in the editor instance is common.
+ * Because the driver is stateful, driver instances must be paired with
editor hierarchy instances.
+ * Start the editing process by passing the bean into the driver.
+ * Allow the user to interact with the UI.
+ * Call the `flush()` method on the driver to copy Editor state into the
bean hierarchy.
+ * Optionally check `hasErrors()` and `getErrors()` to determine if there
are client-side input validation problems.
+
+== Editor contract ==
+
+The basic `Editor` type is simply a parameterized marker interface that
indicates that a type conforms to the editor contract or informal
protocol. The only expected behavior of an `Editor` is that it will
provide access to its sub-Editors via one or more of the following
mechanisms:
+ * An instance field with at least package visibility whose name exactly
the property that will be edited or `propertyNameEditor`. For example:
+{{{
+class MyEditor implements Editor<Foo> {
+ // Edits the Foo.getBar() property
+ BarEditor bar;
+ // Edits the Foo.getBaz() property
+ BazEditor bazEditor;
+}
+}}}
+ * A no-arg method with at least package visibility whose name exactly is
the property that will be edited or `propertyNameEditor`. This allows the
use of interfaces for defining the Editor hierarchy. For example:
+{{{
+interface FooEditor extends Editor<Foo> {
+ // Edits the Foo.getBar() property
+ BarEditor bar();
+ // Edits the Foo.getBaz() property
+ BazEditor bazEditor();
+}
+}}}
+ * The `...@path` annotation may be used on the field or accessor method to
specify a dotted property path or to bypass the implicit naming
convention. For example:
+{{{
+class PersonEditor implements Editor<Person> {
+ // Corresponds to person.getManager().getName()
+ @Path("manager.name");
+ Label managerName;
+}
+}}}
+ * The `...@ignored` annotation may be used on a field or accessor method to
make the Editor framework ignore something that otherwise appears to be a
sub-Editor.
+ * Sub-Editors may be null. In this case, the Editor framework will
ignore these sub-editors.
+
+== Editor subtypes ==
+
+In addition to the `Editor` interface, the Editor framework looks for
these specific interfaces to provide basic building blocks for more
complicated Editor behaviors. This section will document these interfaces
and provide examples of how the Editor framework will interact with the API
at runtime. All of these core Editor sub-interface can be mixed at will.
+
+ * `LeafValueEditor` is used for non-object, immutable, or any type that
the Editor framework should not descend into.
+ 1 `setValue()` is called with the value that should be edited (e.g.
`fooEditor.setValue(bean.getFoo());`).
+ 1 `getValue()` is called when the Driver is flushing the state of the
Editors into the bean. The value returned from this method will be
assigned to the bean being edited (e.g.
`bean.setFoo(fooEditor.getValue());`).
+ * `HasEditorDelegate` provides an Editor with its peer `EditorDelegate`.
+ 1 `setEditorDelegate()` is called before any value initialization
takes place.
+ * `ValueAwareEditor` may be used if an Editor's behavior depends on the
value that it is editing, or if the Editor requires explicit flush
notification.
+ 1 `setEditorDelegate()` is called, per `HasEditorDelegate`
super-interface.
+ 1 `setValue()` is called with the value that the Editor is responsible
for editing. If the value will affect with sub-editors are or are not
provided to the framework, they should be initialized or nullified at this
time.
+ 1 If `EditorDelegate.subscribe()` has been called, the Editor may
receive subsequent calls to `onPropertyChange()` or `setValue()` at any
point in time.
+ 1 `flush()` is called in a depth-first manner by the driver, so
Editors generally do not flush their sub-Editors.
+ * `CompositeEditor` allows an unknown number of homogenous sub-Editors
to be added to the Editor hierarchy at runtime. In addition to the
behavior described for `ValueAwareEditor`, `CompositeEditor` has the
following additional APIs:
+ 1 `createEditorForTraversal()` should return a canonical sub-editor
instance that will be used by the driver for computing all edited paths.
If the composite editor is editing a Collection, this method solves the
problem of having no sub-Editors available to examine for an empty
Collection.
+ 1 `setEditorChain()` provides the `CompositeEditor` with access to the
`EditorChain`, which allows the component sub-Editors to be attached and
detached from the Editor hierarchy.
+ 1 `getPathElement()` is called by the Editor framework for each
attached component sub-Editor in order to compute the return value for
`EditorDelegate.getPath()`. A `CompositeEditor` that is editing an
indexable datastructure, such as a `List`, might return `[index]` for this
method.
+ * `HasEditorErrors` indicates that the Editor wishes to receive any
unconsumed errors reported by sub-Editors through
`EditorDelegate.recordError()`. The Editor may mark an `EditorError` as
consumed by calling `EditorError.setConsumed()`.
--
http://groups.google.com/group/Google-Web-Toolkit-Contributors
