ENH: $().formhandler() exposes $().data('formhandler') data & methods

docs/formhandler.md

@@ -128,6 +128,7 @@ e.g., to render the export button somewhere else, use
 contents with the export button. (It searches within the table container for
 `.navbar-export` first, and if not found, searches everywhere.) Available
 targets are:
+
 - `tableTarget`
 - `countTarget`
 - `pageTarget`
@@ -139,6 +140,7 @@ targets are:
 **Advanced**: Each component's template string can be over-ridden. For example,
 `data-search-template="<input type='search'>"` will replace the search template
 with a simple input. Available template strings are:
+
 - `tableTemplate`
 - `table_gridTemplate`
 - `countTemplate`
@@ -148,11 +150,11 @@ with a simple input. Available template strings are:
 - `filtersTemplate`
 - `searchTemplate`
 - `rowTemplate`, which can be a string template or function
-  - function accepts an object with these keys:
-    - `row`: row data
-    - `index`: row index
-    - `data`: the dataset from `src`
-  - string template can use the above variables
+    - function accepts an object with these keys:
+        - `row`: row data
+        - `index`: row index
+        - `data`: the dataset from `src`
+    - string template can use the above variables
 
 Features to be implemented:
 
@@ -172,6 +174,30 @@ Features to be implemented:
 
 - `editmode` is fired on the source when the Edit button is clicked and table changes to edit mode.
 
+## $.formhandler data
+
+When you run `$(...).formhandler()` on an element, you can access
+FormHandler-related data and methods via `$(...).data('formhandler')`. This
+returns an object with these keys:
+
+- `data`: data currently displayed by the component (as an array of objects)
+- `meta`: metadata returned by the FormHandler (e.g. `meta['fh-data-count']` has the total # of rows)
+- `args`: args passed to the FormHandler
+- `options`: options passed to this component
+- `isEdit`: `true` if the component is editable
+- `isAdd`: `true` if new rows can be added to the component
+- `notify`: `notify('message')` displays a notification on this component
+
+For example:
+
+```js
+$('.formhandler').formhander()
+var data = $('.formhandler').data('formhandler')
+data.data   // data displayed by component
+data.meta   // metadata returned by the FormHandler
+data.args   // args passed to the FormHandler
+```
+
 ## $.formhandler examples
 
 ### Render from a FormHandler

src/formhandler.js

@@ -123,7 +123,9 @@ export function formhandler(js_options) {
         col_defaults: col_defaults,
         isEdit: false,
         isAdd: false,
-        templates: default_templates
+        templates: default_templates,
+        notify: notify.bind(this, $this, template),
+        failHandler: failHandler.bind(this, $this, template)
       }
       // Store template_data in $this
       $this.data('formhandler', template_data)

test/test-formhandler.html

@@ -1090,6 +1090,48 @@
       })
     })
 
+    $('.fhdata').formhandler()
+      .on('load', function () {
+        var data = $('.fhdata').data('formhandler')
+        // `data`: data currently displayed by the component (as an array of objects)
+        t.equals(data.data.length, data.meta.limit)
+        t.deepEquals(Object.keys(data.data[0]), _.map(data.meta.columns, 'name'))
+
+        // `meta`: metadata returned by the FormHandler (e.g. `meta['fh-data-count']` has the total # of rows)
+        t.equals(data.meta.offset, 0)
+        t.equals(data.meta.limit, 100)
+        t.ok(data.meta.count > 100)
+        t.ok(Array.isArray(data.meta.columns))
+        t.ok('name' in data.meta.columns[0])
+        t.ok('type' in data.meta.columns[0])
+        t.ok('hide' in data.meta.columns[0])
+        t.ok('hideable' in data.meta.columns[0])
+        t.ok('sort' in data.meta.columns[0])
+        t.ok('filters' in data.meta.columns[0])
+
+        // `args`: args passed to the FormHandler
+        t.equals(data.args._format, 'json')
+        t.equals(data.args._limit, 100)
+        t.equals(data.args._meta, 'y')
+        t.ok(Array.isArray(data.args.c))
+
+        // `options`: options passed to this component
+        t.ok(typeof data.options.add, 'boolean')
+        t.ok(typeof data.options.pageSize, 'number')
+
+        // `isEdit`: `true` if the component is editable
+        // `isAdd`: `true` if new rows can be added to the component
+        t.equals(typeof data.isEdit, 'boolean')
+        t.equals(typeof data.isAdd, 'boolean')
+
+        // `notify`: `notify('message')` displays a notification on this component
+        data.notify('message')
+        t.equals($('.fhdata .alert').get(0).childNodes[0].textContent.replace(/^\s+/, '').replace(/\s+$/, ''), 'message')
+
+        // Undocumented: but expose failHandler to allow subclassing
+        t.equals(typeof data.failHandler, 'function')
+        t.end()
+      })
   </script>
 </body>