Overview

The dgrid Laboratory is built using dgrid and provides a UI for defining and configuring your own dgrid.
The configuration will be rendered in a demo grid and if you click the "Code" button you can see source code for
creating the grid in your own application. While the Laboratory can be helpful in getting started creating and
configuring your own grid, you will definitely want to read dgrid's documentation and
tutorials.

The documentation below gives some information on the overall architecture of the Laboratory and some more detailed
information on some of its more prominent modules.

Module hierarchy

• Laboratory
  • ColumnEditor
    • ColumnGrid
    • ColumnConfigForm
  • FeatureEditor
    • FeatureGrid
    • ConfigForm subclasses

Widget communication

In addition to the typical parent-child widget communication, and occasional cross-widget communication,
the Laboratory listens at the top level (Laboratory.js) for data update events in order to keep the demo grid and
generated code updated in real time.

Pub-sub topics

• /configuration/changed: Indicates that some data directly related to the display of the demo grid or
  generated code has changed

  • Publishers:
    • ColumnGrid: Published when the grid's store is modified
    • FeatureEditor: Published when the FeatureGrid's store is modified
    • ConfigForm: Published when the form's value property changes
  • Subscribers:
    • Laboratory: Keeps the demo grid or generated code updated (depending on which is visible)

• /column/changed: Indicates that column configuration data has been updated in the UI

  • Publishers:
    • ColumnConfigForm: Published when the form's value property changes
  • Subscribers:
    • ColumnGrid: Keeps the store data constantly in sync with the UI form values

• /store/columns/update: Indicates that column configuration data has been updated in the store

  • Publishers:
    • ColumnGrid: Published when the grid's store is modified
  • Subscribers:
    • configForms/Tree: Updates the list of columns names so the user can select which one should render the
      tree expando

• /feature/select: Indicates that a feature (dgrid mixin) has been selected (or de-selected)

  • Publishers:
    • FeatureGrid: Published when the grid's editable fields change (dgrid-datachange event)
  • Subscribers:
    • ColumnConfigForm: Updates which column features are visible for configuration

• /columnConfig/hidden: Indicates changes to the hidden state of fields in the column configuration form.
  Passes an object hash whose keys correspond to the names of currently hidden fields.

  • Publishers:
    • ColumnConfigForm: Published in reaction to the /feature/select topic
  • Subscribers:
    • ColumnGrid: Updates column configurations to prune any properties which are no longer applicable

Modules

Laboratory

This is the top-level widget. It provides the full-page UI layout and manages child widgets. While the functionality of most components is encapsulated in child widgets, Laboratory directly manages some items itself:

• Tab navigation
• Updating the demo grid (_showDemoGrid) or generated code (_generateCode), depending on which is visible
  • Both the _showDemoGrid and _generateCode methods rely on the _generateGridOptions method to read the current
    configuration from the UI and calculate a dgrid options object to pass to the grid constructor function
• The "About" dialog

ColumnEditor

This widget is initially visible when the page is loaded in the far left pane in the tab titled "Columns". It is a lightweight container for the ColumnGrid and ColumnConfigForm widgets.

API

• get('columns'): Returns an array of objects from the store that represent the user-defined columns; proxies to
  ColumnGrid#get('columns')
• addColumn and removeColumn: Provide the ability to add and remove user-defined columns; these methods proxy to
  the respective methods on ColumnGrid

ColumnGrid

This widget is a little more than just a grid - it's a templated widget that contains a grid, but it also manages
the grid's store and the new column entry field in the UI (visible directly above the grid).

API

• get('columns'): Returns an array of objects from the store that represent the user-defined columns
• addColumn(label): Adds a new column to the grid with the specified label, and auto-generates a field name based on
  that label
• removeColumn(target) (where target can be any value supported by dgrid's
  row method): Removes the associated column definition
  from the store (and grid)

ColumnConfigForm

This widget provides the UI for editing user-defined columns. Some sections are hidden or visible depending on
which mixins are enabled (e.g. Editor, ColumnHider, etc.). It extends dijit/form/_FormMixin for basic
form management and the get/set('value') methods. As a result, when the widget's value is set,
any values in the object provided that do not map directly to fields in the form are discarded.

In order to correctly update items in the store, whenever the value is set, the id property (which is
not represented by any of the form fields) is persisted by the custom setter method. The custom getter method restores
the id property to the object returned by ColumnConfigForm#get('value').

FeatureEditor

This widget encapsulates the functionality in the "Grid Features" and "Column Features" tabs. It extends
dijit/layout/StackContainer and contains one FeatureGrid and multiple widgets that extend configForms/ConfigForm.
The config form widgets are defined by two components:

1. An item in the array defined in the data/features module
2. (Optional) If the feature has configurable properties, the UI to edit them should be provided in a module that
   extends configForms/ConfigForm. The module ID of the config form module should be indicated via the item's
   configModule property in the data/features module.

API

• getModuleConfig(moduleId): Returns an object representing the configured options for the specified dgrid module ID
• isSelected(moduleId): Returns a boolean value indicating if the specified dgrid mixin module ID is selected
• filter(query): Filters the FeatureGrid by the specified query
• get('expandoColumn'): If the dgrid/Tree mixin has been enabled, this method returns the name of the column that has been configured to render the tree expando icon
• set('featureType', featureType) (where featureType is 'grid' or 'column'): Filters the FeatureGrid by the
  specified type; proxies to FeatureGrid#set('featureType'). The same grid is displayed in both the "Grid Features"
  and "Column Features" tabs using this method to filter which rows are displayed.

FeatureGrid

Like the ColumnGrid widget, this is a templated widget that encapsulates not only the grid but also its store.
Logic is also included to prevent incompatible configurations (e.g. OnDemandGrid with dgrid/extensions/Pagination).

API

• set('featureType', featureType) (where featureType is 'grid' or 'column'): Filters the grid by the specified
  type
• set('gridModule', gridModule) (where gridModule is 'Grid' or 'OnDemandGrid'): sets the base grid module of the
  user-defined grid and prevents incompatible combinations

ConfigForm

This module should not be instantiated directly. It provides the basic functionality for
grid feature configuration forms (e.g. Selection, Tree, etc.).

• Renders a "Done" button to return to dismiss the form and return to the grid
• Extends dijit/form/_FormMixin with custom accessor/mutator methods
  • set('value', value): Unspecified properties will be set to their default value
  • get('value'): Properties whose values match the default value will be omitted

Each subclassing module should provide an object on the defaultsObject property that defines default values for
configuration properties. This can typically be achieved by providing the dgrid module's prototype, since these modules
define their configurable properties and their default values. The default values are used both to initially populate
the form and to filter values - if the user has not changed the value from the default, it will be omitted from the
generated code. defaultsObject is never modified.

Each subclass should also specify moduleName and documentationUrl properties to be displayed in the
config form's UI.

All currently-implemented subclasses of ConfigForm are located under widgets/configForms.