public interface DevTools
This includes interfaces such as:
Dashboards & Tools provides a pattern for end user creation and configuration of UI components which enables the framework to store and re-create components exactly as the user configured them.
Unlike simple serialization, Dashboards & Tools is designed to capture only UI state created directly by end user actions, and not transient or derived state (for more on this behavior and how it is different from serialization, see "Stored vs Derived State" below).
To achieve this, user-editable components are created via a special pattern (not just the
and changes to user-editable components that are meant to be saved are likewise applied via
special APIs (not just direct calls to
The main components and behaviors involved in Dashboards & Tools are covered in brief below - each of these points is covered in more detail in further sections:
Palettescreate components from
PaletteNodes, which are
data recordscontaining the component's class and default settings. Some
Palettesprovide an end user UI for creating components (eg drag a node from a Tree).
Paletteis represented by an
EditNode, which tracks the created component along with the data necessary to save and re-create the component.
EditContextmanages a list or
EditNodes, and provides APIs for serializing and restoring
EditNodesto and from XML and JSON, and updating the nodes as users make changes.
"edit mode"behaviors. When "edit mode" is enabled, when an end user interacts with the component, the component will save changes to its
EditNodeor to child
EditContext. For example,
PortalLayoutcan track and persist changes to the placement and size of portlets made by end users.
EditModebehaviors are implemented by
EditProxies, and different edit mode behaviors can be turned on and off for different kinds of tools.
Palettesshowing components that the user can create
Paletteto create them. The editing area is just an ordinary UI component that has been placed into "edit mode" and provided with an
EditContext. Depending on the type of tool, the main editing area might be a
DrawPane(for diagrams), a
DynamicForm(for a form builder) or various other widgets.
built-in UIfor selecting one or more of the components being edited.
EditContext.getSelectedEditNode()provides the current edit node, and
EditContext.setNodeProperties()lets you manipulate its persisted state.
obtain XML or JSON Stringsrepresenting the data to be saved, as well as to
restore saved statefrom such Strings. DataSources can be used to store whatever is being edited: the serialized form is just an XML or JSON String, so it can be stored as an ordinary
Most types of
palettes provide a UI for an end user to create components from
paletteNodes. For example, a
presents a hierarchical
paletteNodes as a tree, and allows end users to drag nodes out in order
to create components. All
palettes also support
programmatic creation of components from
EditNode is added to an EditContext, typically it is immediately placed
"Edit Mode" (see
EditContext.autoEditNewNodes for how
this can be controlled). In Edit Mode, components introduce special behaviors, such as the
ability to directly edit the titles of
Tabs in a
TabSet by double-clicking, or
support for dragging new
FormItems into a
DynamicForm. Changes made while a
component is in Edit Mode are saved to the component's
Each component that has
editMode features has a corresponding
that implements those features. A component's
EditProxy is automatically
created when a component
goes into edit
mode, and overrides the
normal behavior of the component. By configuring the
EditProxy for a
component, you configure what behaviors the component will have when in edit mode, and which
specific actions on the component will cause changes to be saved to its
EditContext has the capability to manage a
EditNodes in order to enable tools that create a hierarchy of Smart GWT
components. When you use
EditContext.addNode() and add a new EditNode underneath
another EditNode, the EditContext will automatically try to determine how the parent and
child are related and actually call APIs on the widgets to establish a relationship, such as
a Tab being added to a TabSet, or a FormItem being added to a DynamicForm. The
EditContext uses the same approach as is used for Reify Drag and Drop - see
Reify overview for details.
Note that many if not most kinds of tools use only a flat list of EditNodes - for example,
in a collage editor, photos may sometimes be stacked on top of each other, but a
parent/child relationship in the sense of
Canvas.children is not established by doing
so. Likewise, although the Mockup
Editor sample allows end
users to create mockups using Smart GWT components, the components never truly become
children of other components. Instead, as is typical of most mockup tools, hierarchy is
achieved visually by simply placing a component on top of another and within its bounding
Most types of tools use a flat list of
EditNodes - generally speaking you will
only use the hierarchy management features of
Editcontext if you are creating a
tool that actually allows end users to build functioning Smart GWT screens, such as the
Builder example. For such applications, use
to enable drag and drop interactions that will allow end
users to place components inside of other components.
The purpose of having an
EditNode for each UI component is to maintain a
distinction between the current state of the live UI component and the state that should
be saved. For example:
EditContext.setNodeProperties()by application code
setCanvasDefaults()method (PaletteNode also has equivalent
Sometimes, however, your code does not directly create the PaletteNode itself. For
example, when you provide
TileRecords that will be
used in a
TilePalette, you provide the PaletteNode
defaults on the TileRecords, but your code does not actually create the PaletteNodes. In
this case, you create a properties object as described above, and then you call its
method to obtain a Map of properties suitable for specifying PaletteNode defaults. This
code, taken from the Collage Editor sample, demonstrates
Img img = new Img(); img.setTitle(title); img.setSrc("stockPhotos/" + photos.get(i)); TileRecord record = new TileRecord(); record.setAttribute("title", title); record.setAttribute("type", "Img"); record.setAttribute("defaults", img.getPaletteDefaults());
Optional Modulefor this framework.
Any tools that work with hierarchies of system components or derivations of them will also need the system schema which can be loaded by either of the following: