Move documentation from the GH wiki into the repository

Based on @edhager's work of similar nature for 0.4
SitePen · May 30, 2014 · dfd3a80 · dfd3a80
1 parent 4e77184
commit dfd3a80
Show file tree

Hide file tree

Showing 30 changed files with 2,528 additions and 8 deletions.
diff --git a/CHANGES.md b/CHANGES.md
@@ -1,12 +1,15 @@
-This document outlines changes since 0.3.0.  For older changelogs, see the
-[dgrid wiki](https://github.com/SitePen/dgrid/wiki).
+**Note:** Going forward, release notes will be maintained on the GitHub repository's
+[releases page](https://github.com/SitePen/dgrid/releases).  This file will likely be
+removed in the future.
 
 # master (0.3.15-dev)
 
 ## Significant changes
 
 ### General/Core
 
+* Documentation has been moved out of the wiki and into the repository under the
+  doc folder, to facilitate maintaining relevant documentation for both 0.3 and 0.4.
 * Fixed a regression in `List` which could cause errors in certain situations
   due to a feature test being performed before the document is ready. (#907)
 

diff --git a/README.md b/README.md
@@ -58,13 +58,11 @@ on APIs new to 1.8 or 1.9, so as to maintain compatibility with 1.7.
 
 # Documentation
 
-Documentation for dgrid components is available in the
-[dgrid GitHub project wiki](https://github.com/SitePen/dgrid/wiki).
-The wiki's content may still be obtained for offline reading by cloning
-the wiki repository, as indicated under the "Git Access" tab.
+The [doc folder](./doc) contains documentation for dgrid components.
+In addition, the website hosts a number of [tutorials](http://dgrid.io/#tutorials).
 
-In addition to the documentation on the wiki, if upgrading from a previous
-dgrid release, please be sure to read the changelog, found in CHANGES.md.
+If upgrading from a previous dgrid release, please be sure to read the
+[release notes](https://github.com/SitePen/dgrid/releases).
 
 # Testing
 

diff --git a/doc/README.md b/doc/README.md
@@ -0,0 +1,51 @@
+# dgrid Documentation
+
+This folder contains the official dgrid documentation. It includes
+information on dgrid's core components, as well as information on various
+mixins, plugins, and extensions that are available to further expand dgrid's
+default functionality. 
+
+## Components
+
+* Core Components
+    * [List](components/core-components/List.md)
+    * [Grid](components/core-components/Grid.md)
+    * [GridFromHtml](components/core-components/GridFromHtml.md)
+    * [OnDemandList and OnDemandGrid](components/core-components/OnDemandList-and-OnDemandGrid.md)
+* Mixins
+    * [Keyboard](components/mixins/Keyboard.md)
+    * [ColumnSet](components/mixins/ColumnSet.md)
+    * [Selection](components/mixins/Selection.md)
+    * [CellSelection](components/mixins/CellSelection.md)
+* Column Plugins
+    * [editor](components/column-plugins/editor.md)
+    * [tree](components/column-plugins/tree.md)
+    * [selector](components/column-plugins/selector.md)
+* Extensions
+    * [ColumnReorder](components/extensions/ColumnReorder.md)
+    * [ColumnResizer](components/extensions/ColumnResizer.md)
+    * [ColumnHider](components/extensions/ColumnHider.md)
+    * [CompoundColumns](components/extensions/CompoundColumns.md)
+    * [Pagination](components/extensions/Pagination.md)
+    * [DijitRegistry](components/extensions/DijitRegistry.md)
+    * [DnD](components/extensions/DnD.md)
+* Utilities
+    * [mouse](components/utilities/mouse.md)
+    * [touch](components/utilities/touch.md)
+    * [misc](components/utilities/misc.md)
+
+## Usage
+
+* [Working with Events](usage/Working-with-Events.md)
+* [Working with Widgets](usage/Working-with-Widgets.md)
+* [Styling dgrid](usage/Styling-dgrid.md)
+* [Limitations](usage/Limitations.md)
+
+## Migrating from dojox/grid
+
+* [API Comparison](migrating/API-Comparison.md)
+* [Usage Comparison](migrating/Usage-Comparison.md)
+
+## Tutorials
+
+Various tutorials are available on [dgrid.io](http://dojofoundation.org/packages/dgrid/#tutorials).
diff --git a/doc/components/column-plugins/editor.md b/doc/components/column-plugins/editor.md
@@ -0,0 +1,118 @@
+# editor
+
+The editor plugin provides the ability to render editor controls within cells
+for a column. When used in conjunction with a store-backed grid such as an
+[OnDemandGrid](../core-components/OnDemandList-and-OnDemandGrid.md#ondemandgrid), edited fields are directly
+correlated with the dirty state of the grid; changes can then be saved back to
+the store based on edits performed in the grid.
+
+```js
+require([
+    "dojo/_base/declare", "dgrid/OnDemandGrid","dgrid/editor", "dgrid/Keyboard", "dgrid/Selection"
+], function(declare, OnDemandGrid, editor, Keyboard, Selection){
+    var editGrid = new (declare([OnDemandGrid, Keyboard, Selection]))({
+        store: myStore,
+        columns: [
+            editor({
+                label: "Name",
+                field: "name",
+                editor: "text",
+                editOn: "dblclick"
+            }),
+            // ...
+        ]
+    }, "editGrid");
+});
+```
+
+For more examples of editor in use, see the various `editor` test pages, as well
+as the `GridFromHtml_editors` test page for declarative examples.
+
+## Additional Column Definition Properties
+
+The editor plugin supports the following additional column definition properties.
+
+Property | Description
+-------- | -----------
+`editor` | The type of component to use for editors in this column; either a string specifying a type of standard HTML input to create, or a Dijit widget constructor to instantiate.
+`editOn` | A string containing the event (or multiple events, comma-separated) upon which the editor should activate.  If unspecified, editors are always displayed in this column's cells.
+`editorArgs` | An object containing input attributes or widget arguments.  For HTML inputs, the object will have its key/value pairs applied as node attributes via `put-selector`; for widgets, the object will be passed to the widget constructor.
+`canEdit(object, value)` | A function returning a boolean value indicating whether or not the cell for this column should be editable in a particular row.  Receives the item for the current row, and the value to be rendered (i.e. the return from the column's `get` function if any, or the value of the `field` specified in the column).
+`autoSave` |If `true`, the grid's `save` method will be called as soon as a change is detected in an editor in this column.  Defaults to `false`. **Note:** if an error is encountered as a result of a store operation triggered by `autoSave`, a `dgrid-error` event will be emitted.
+`dismissOnEnter` | By default, pressing enter will store the current value in the grid's dirty data hash.  This can be undesirable particularly for textarea editors; setting this property to `false` will disable the behavior.
+
+For convenience, the `editor` and `editOn` properties may also be specified as
+the second and third arguments to the `editor` function. For example, both of
+the following would result in an editor which presents a text field when a cell
+in the column is double-clicked:
+
+```js
+// long version, everything in column def object
+editor({
+    editor: "text",
+    editOn: "dblclick",
+    /* rest of column definition here... */
+})
+
+// shorthand version, editor and editOn as arguments
+editor({ /* rest of column definition here... */ }, "text", "dblclick")
+```
+
+## Additional Grid APIs
+
+When the editor plugin is applied to a column in a grid, the grid is augmented with
+the following method.
+
+Method | Description
+------ | -----------
+`edit(cell)` | Activates/focuses the specified cell (which can be a cell object from `grid.cell()`, or a DOM node or event resolvable to one).
+
+## Events
+
+The editor plugin emits a `dgrid-datachange` event whenever an editor field
+loses focus after its value is changed. This event includes the following
+properties:
+
+* `grid`: The Grid instance in which the edit occurred
+* `cell`: The `cell` object to which the edit applied, as reported by the
+  `grid.cell` method
+* `oldValue`: The value before the edit occurred
+* `value`: The value after the edit occurred
+
+This event bubbles and is cancelable; if the event is canceled, the modification
+will be reverted.
+
+Editors with `editOn` set also emit `dgrid-editor-show` and `dgrid-editor-hide`
+events when the editor is shown and hidden, respectively. These events also
+include `grid` and `cell` properties and bubble; however, they are not
+cancelable. If an editor should not be shown under specific circumstances,
+include a `canEdit` function in the column definition.
+
+## Recommendations for the editOn property
+
+If attempting to trigger an editor on focus (to accommodate keyboard and mouse),
+it is highly recommended to use dgrid's custom event, `dgrid-cellfocusin`
+instead of `focus`, to avoid confusion of events. Note that this requires also
+mixing the Keyboard module into the Grid constructor.
+
+If touch input is a concern for activating editors, the easiest solution is to
+use the `click` event, which browsers on touch devices tend to normalize to fire
+on taps as well. If a different event is desired for desktop browsers, it is
+possible to do something like the following:
+
+```js
+require(
+    ["dgrid/OnDemandGrid", "dgrid/editor", "dojo/has" /*, ... */],
+    function(OnDemandGrid, editor, has /*, ... */){
+        var columns = [
+            /* ... more columns here ... */
+            editor({ name: "name", label: "Editable Name" }, "text",
+                has("touch") ? "click" : "dblclick")
+        ];
+        /* ... create grid here ... */
+    }
+);
+```
+
+There are also a couple of useful simple gesture implementations available in
+the `util/touch` module, namely `tap` and `dbltap`.
diff --git a/doc/components/column-plugins/selector.md b/doc/components/column-plugins/selector.md
@@ -0,0 +1,39 @@
+# selector
+
+Used in conjunction with the [Selection](../mixins/Selection.md) mixin, the selector plugin dedicates
+a column to the purpose of rendering a selector component, providing alternate
+means for selecting and deselecting rows in a grid.
+
+```js
+require([
+    "dojo/_base/declare", "dgrid/OnDemandGrid", "dgrid/Selection", "dgrid/selector"
+], function(declare, OnDemandGrid, Selection, selector){
+    var grid = new (declare([OnDemandGrid, Selection]))({
+        store: myStore,
+        selectionMode: "single",
+        columns: {
+            col1: selector({ label: "Select", selectorType: "radio" }),
+            col2: "Column 2"
+        }
+    }, "grid");
+    // ...
+});
+```
+
+## Usage 
+
+A selector column can be used to allow selection even in a grid where
+`selectionMode` is set to `none`, in which case the controls in the selector
+column will be the only means by which a user may select or deselect rows.
+
+## Additional Column Definition Properties
+
+The selector plugin supports the following additional column definition properties.
+
+Property | Description
+-------- | -----------
+`disabled(item)` | A function which, provided the item for a particular row, should return `true` if the selector control should be disabled for that row.  Returning `true` will also prevent the row in question from being directly selected via the [Selection](../mixins/Selection.md) mixin.
+`selectorType` | Specifies the type of selector component to use.  Defaults to `"checkbox"`, but `"radio"` may also be specified, as a more appropriate choice for grids in single-selection mode.
+
+Alternatively, `selectorType` may be specified as the second argument to the
+`selector` function instead of including it within the column definition.
diff --git a/doc/components/column-plugins/tree.md b/doc/components/column-plugins/tree.md
@@ -0,0 +1,75 @@
+# tree
+
+The tree plugin enables expansion of rows to display children. 
+
+```js
+require([
+    "dojo/_base/declare", "dgrid/OnDemandGrid", "dgrid/tree", "dgrid/Keyboard", "dgrid/Selection"
+], function(declare, OnDemandGrid, tree, Keyboard, Selection){
+    var treeGrid = new (declare([OnDemandGrid, Keyboard, Selection]))({
+        store: myStore,
+        columns: [
+            tree({ label: "Name", field: "name" }),
+            { label:"Type", field: "type", sortable: false},
+            { label:"Population", field: "population" },
+            { label:"Timezone", field: "timezone" }
+        ]
+    }, "treeGrid");
+});
+```
+
+## Store Considerations
+
+The tree plugin expects to operate on a store-backed grid, such as an
+[OnDemandGrid](../core-components/OnDemandList-and-OnDemandGrid.md#ondemandgrid) or a grid with the [Pagination](../extensions/Pagination.md)
+extension mixed in.
+
+The store connected to the grid is expected to provide a `getChildren(object, options)`
+method to return the children for a given item. Note that for best results,
+`getChildren` should return results with an `observe` function as well
+(like `query`), so that changes to children can also be reflected as they occur.
+
+When calling `getChildren`, dgrid will include an `originalQuery` property in
+the `options` argument, containing the value from the grid's `query` property.
+This allows `getChildren` implementations to perform the same filtering on
+child levels if desired.
+
+The following is a simple example of what a `getChildren` implementation could
+look like in an extension to `dojo/store/Memory`, where hierarchy is indicated
+by a `parent` property on child items:
+
+```js
+getChildren: function(parent, options){
+    // Support persisting the original query via options.originalQuery
+    // so that child levels will filter the same way as the root level
+    return this.query(
+        lang.mixin({}, options && options.originalQuery || null,
+            { parent: parent.id }),
+        options);
+}
+```
+
+The store may also (optionally) provide a `mayHaveChildren(object)` method which
+returns a boolean indicating whether or not the row can be expanded. If this
+is not provided, all items will be rendered with expand icons.
+
+## Additional Column Definition Properties
+
+The tree plugin supports the following additional column definition properties.
+
+Property | Description
+-------- | -----------
+`shouldExpand(row, level, previouslyExpanded)` | an optional function which returns a boolean indicating whether the given row should be expanded when rendered.  The default implementation simply returns the value of `previouslyExpanded`, which denotes whether the row in question was previously expanded before being re-rendered.
+`renderExpando()` | an optional function which can be overridden to customize the logic for rendering the expando icon beside each tree cell's content.
+`indentWidth` | the number of pixels to indent each nested level of children; the default is `9`.
+`collapseOnRefresh` | a boolean indicating whether to collapse all parents (essentially "forgetting" expanded state) whenever the grid is refreshed; the default is `false`.
+`allowDuplicates` | If this is set to `true`, a single object (and single id) can be used in multiple places in a tree structure. However, enabling this means that `grid.row(id)` will only return top-level objects (since it can't disambiguate other levels). The default is `false`.
+
+## Additional Grid APIs
+
+When the tree plugin is applied to a column in a grid, the grid is augmented with
+the following method.
+
+Method | Description
+------ | -----------
+`expand(row, expand)` | Expands or collapses the row indicated by the given Row object (from `grid.row(target)`) or a `dgrid-row` element. The optional `expand` argument specifies whether the row should be expanded (`true`) or collapsed (`false`); if unspecified, the method toggles the current expanded state of the row.  Returns a promise which resolves after data for the children has been retrieved.