config-ip-filter: Documentation and linting.

Author: benloh

build/app/assets/templates/_default.template

@@ -1,10 +1,14 @@
 {
 
-  "_comments":  [ "/// NetCreate Template File ///",
-                  "/// IMPORTANT: As of 8/7/2020, the following funcationality is available:               ///",
+  "_comments":  [ "/// NetCreate Template File                                                             ///",
+                  "/// RELEASE NOTES: As of 8/13/2020, a 'type' specification needs to added to each       ///",
+                  "///     nodePrompt and edgePrompt for filters to work.  Valid types are:                ///",
+                  "///     "string", "number", "select", and "node".  The "node" type is only valid for    ///",
+                  "///     "source" and "target" objects for edges.                                        ///",
+                  "/// RELEASE NOTES: As of 8/7/2020, the following functionality is available:            ///",
                   "///  * `requireLogin: true` will require users to login to view graphs.  If the         ///",
                   "///     parameter is `false` or missing, graphs are public, and login is not required   ///",
-                  "/// IMPORTANT: As of 1/31/2019, the following functionality is available:               ///",
+                  "/// RELEASE NOTES: As of 1/31/2019, the following functionality is available:           ///",
                   "///  * `label` parameter for each field may be customized                               ///",
                   "///  * `hidden` parameter may be used to hide fields                                    ///",
                   "///  * changing the order of the `options` WILL change their order on selections        ///",

build/app/view/netcreate/components/filter/FilterEnums.js

@@ -1,5 +1,6 @@
 const FILTER = {};
 
+// Types of filters definable in template files.
 FILTER.TYPES = {};
 FILTER.TYPES.STRING = 'string';
 FILTER.TYPES.NUMBER = 'number';
@@ -14,10 +15,6 @@ FILTER.KEY = {};
 FILTER.KEY.SOURCE = "source";
 FILTER.KEY.TARGET = "target";
 
-FILTER.ACTIONS = {};
-FILTER.ACTIONS.CLEAR = "clear";
-FILTER.ACTIONS.FILTER_NODES = "filter-nodes";
-FILTER.ACTIONS.FILTER_EDGES = "filter-edges";
 
 FILTER.OPERATORS = {};
 FILTER.OPERATORS.NO_OP = "no-op";
@@ -38,25 +35,28 @@ FILTER.OPERATORS.NUMBER.LT_EQ = "lt-eq";
 FILTER.OPERATORS.NUMBER.EQ = "eq";
 FILTER.OPERATORS.NUMBER.NOT_EQ = "not-eq";
 
-/*/
+
+/*/ UDATA MESSAGES ////////////////////////////////////////////////////////////
 
 Filter UDATA Messages
 
-All Filters operations
 
-  FILTERDEFS      Set the FILTERDEFS data object
-                  FILTERDATA?  FILTER_DATA?
-                  FDATA? FLTRDATA
+Affects ALL Filters
+===================
 
-  FILTER_RESET    Resets filter form to blank state
+  FDATA           Sets the FDATA data object
+                  Triggers AppStateChange
 
-Individual Filter Operations
+  FILTER_CLEAR    Unhides all objects on the graph
+                  Resets filter form to blank state
 
-  FILTER_DEFINE   Define a new individual filter
 
+Affects Individual Filters
+==========================
 
-/*/
+  FILTER_DEFINE   Define a single new filter
 
 
+/*/
 
 module.exports = FILTER;

build/app/view/netcreate/components/filter/FilterGroup.jsx

@@ -12,22 +12,23 @@ export default function FilterGroup({
   return (
     <div className="filter-group" style={{margin:'5px 5px 5px 0',padding:'10px',backgroundColor:'rgba(0,0,0,0)'}}>
       <div className="small text-muted" style={{fontWeight:'bold',textTransform:'uppercase',marginBottom:'0.4em'}}>{label}</div>
-      {filters.map(filterData => {
-        switch (filterData.type) {
+      {filters.map(filter => {
+        switch (filter.type) {
           case FILTER.TYPES.STRING:
           case FILTER.TYPES.NODE:
-            return <StringFilter key={filterData.id} group={group} filter={filterData} />
+            return <StringFilter key={filter.id} group={group} filter={filter} />
             break;
           case FILTER.TYPES.NUMBER:
-            return <NumberFilter key={filterData.id} group={group} filter={filterData} />
+            return <NumberFilter key={filter.id} group={group} filter={filter} />
             break;
           case FILTER.TYPES.SELECT:
-            return <SelectFilter key={filterData.id} group={group} filter={filterData} />
+            return <SelectFilter key={filter.id} group={group} filter={filter} />
             break;
           default:
-            console.error(`FilterGroup: Filter Type not found ${filterData.type}`)
+            console.error(`FilterGroup: Filter Type not found ${filter.type} for filter`, filter);
             break;
         }
+        return '';
       })}
     </div>
   );

build/app/view/netcreate/components/filter/FiltersPanel.jsx

@@ -1,3 +1,19 @@
+/*//////////////////////////////// ABOUT \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\*\
+
+  FILTERSPANEL
+
+  This is the base UI component that displays filters in the InfoPanel.
+
+  FiltersPanel
+  |-- FiltersGroup
+      |-- StringFilter
+      |-- NumberFilter
+      |-- SelectFilter
+
+  FiltersPanel reads data directly from FDATA.
+
+\*\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ * //////////////////////////////////////*/
+
 import FILTER from './FilterEnums';
 import FilterGroup from './FilterGroup';
 import React from 'react';
@@ -9,13 +25,7 @@ const { Button, Input, Label } = ReactStrap;
 const UNISYS = require('unisys/client');
 var UDATA  = null;
 
-
-// Storybook has problems with loading unisys without relative ref
-// but even with relative ref, it can't load submodules
-// const UNISYS = require('../../../../unisys/client');
-// class FiltersPanel extends React.Component {
-
-
+/// CLASS /////////////////////////////////////////////////////////////////////
 class FiltersPanel extends UNISYS.Component {
   constructor({ filterGroups, onFiltersChange, tableHeight }) {
     super();
@@ -26,22 +36,18 @@ class FiltersPanel extends UNISYS.Component {
      /// Initialize UNISYS DATA LINK for REACT
     UDATA = UNISYS.NewDataLink(this);
 
-
-console.error('######## fieldPanel Constructor')
     // Load Templates
-    // The intial `OnAppStateChange("FILTERDEFS")` event when the template is
+    // The intial `OnAppStateChange("FDATA")` event when the template is
     // first loaded is called well before FiltersPanel is
     // even constructed.  So we need to explicitly load it here.
     let FDATA = UDATA.AppState("FDATA");
-    console.error('####### FDATA', FDATA)
     this.state = FDATA;
 
     UDATA.OnAppStateChange("FDATA", this.UpdateFilterDefs);
   } // constructor
 
 
   UpdateFilterDefs(data) {
-    console.log('FiltersPanel: Updating filter defs', data);
     this.setState(data);
   }
 
@@ -50,7 +56,7 @@ console.error('######## fieldPanel Constructor')
   }
 
   componentWillUnmount() {
-    console.error('gracefully unsubscribe!')
+    console.error('TBD: gracefully unsubscribe!')
   }
 
   render() {
@@ -80,7 +86,11 @@ console.error('######## fieldPanel Constructor')
   }
 }
 
-module.exports = FiltersPanel;
+/// EXPORT CLASS DEFINITION ///////////////////////////////////////////////////
+/// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 
-// storyboard wants a regular export?!?!
+// Storybook export
 // export default FiltersPanel;
+
+// Brunch export
+module.exports = FiltersPanel;

build/app/view/netcreate/components/filter/NumberFilter.js

@@ -1,3 +1,46 @@
+/*//////////////////////////////// ABOUT \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\*\
+
+  NUMBERFILTER
+
+  NumberFilter provides the UI for entering search strings for numeric-based
+  node and edge properties.
+
+  Seven Numeric  operators are supported:
+  * >
+  * >=
+  * <
+  * <=
+  * =
+  * !=
+
+  Matches will SHOW the resulting node or edge.
+  Any nodes/edges not matching will be hidden.
+
+  The filter definition is passed in via props.
+
+    props
+      {
+        group       // "nodes" or "edges"
+        filter: {
+          id,       // numeric id used for unique React key
+          type,     // filter type, e.g "string" vs "number"
+          key,      // node field key from the template
+          keylabel, // human friendly display name for the key.  This can be customized in the template.
+          operator, // the comparison function, e.g. 'contains' or '>'
+          value     // the search value to be used for matching
+        },
+        onChangeHandler // callback function for parent component
+      }
+
+  The `onChangeHandler` callback function is not currently used.  Instead,
+  selection changes directly trigger a UDATA.LocalCall('FILTER_DEFINE',...).
+
+  The `id` variable allows us to potentially support multiple search filters
+  using the same key, e.g. we could have two 'Label' filters.
+
+\*\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ * //////////////////////////////////////*/
+
+
 import FILTER from './FilterEnums';
 import React from 'react';
 const ReactStrap = require('reactstrap');
@@ -16,26 +59,8 @@ const OPERATORS = [
   { value: FILTER.OPERATORS.NUMBER.NOT_EQ, label: `\u2260`},
 ]
 
-/*/
-
-  NumberFilter
 
-  props
-      {
-        group       // node or edge
-        filter: {
-          id,
-          type,     // filter type, e.g "string" vs "number"
-          key,      // node field key from the template
-          keylabel, // human friendly display name for the key.  This can be customized in the template.
-          operator,
-          value
-        },
-        onChangeHandler // callback function
-      }
-
-
-/*/
+/// CLASS /////////////////////////////////////////////////////////////////////
 class NumberFilter extends React.Component {
 
   constructor({
@@ -71,10 +96,6 @@ class NumberFilter extends React.Component {
 
   TriggerChangeHandler() {
     const { id, type, key, keylabel } = this.props.filter;
-
-    // Allow NO_OP so user can reset operator to blank
-    // if (this.state.operator === FILTER.OPERATORS.NUMBER.NO_OP) return;
-
     const filter = {
       id,
       type,
@@ -112,4 +133,6 @@ class NumberFilter extends React.Component {
   }
 }
 
+/// EXPORT CLASS DEFINITION ///////////////////////////////////////////////////
+/// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 export default NumberFilter;

build/app/view/netcreate/components/filter/ReadMe.md

@@ -0,0 +1,85 @@
+# Filters
+
+Filtering provides the ability to show and hide nodes and edges based on filter criteria.
+
+* Matches will SHOW the resulting node or edge.
+* Any nodes/edges not matching will be hidden.
+
+Filters are set via the "Filters" tab panel.
+
+The graph will immediately update with any changes made by the user to a filter.
+
+
+## Specifying Filters via the Template Spec
+
+The groups of available filters are drawn directly from the current database's template file, e.g. `tacitus.template`.  It will reflect any customizations made to the labels and hidden/shown status.
+
+
+### Filter Types
+
+In order for a filter to be defined for any given object key, it must have a "type" specified, e.g.
+
+`_default.template`
+```json
+    "notes": {
+                "type":     "string",
+                "label":    "Significance",
+                ...
+             },
+```
+
+
+The available types are:
+
+* "string"
+* "number"
+* "select" -- Drop down menu
+* "node" -- Special type for edge "source" and "target" setting.
+
+Each type has specific operations associated with it, e.g. "string" supports "contains" and "not contains", whereas "number" supports ">" and "!=" etc. 
+
+* Any prompt without a "type" specification will be ignored (e.g. no filter setting will be shown for it).
+* `"hidden": true` prompts will not show as a filter.
+* Alternatively, you can set the `"type": "hidden"` to have the filter not show and retain the value in the database.
+
+
+## How Filtering Works
+
+
+#### How are filters applied?
+
+Filters are applied via an implicit `AND`: An item matches the filter if EVERY filter that is active matches.  For example, if we have:
+
+Node: `Label contains ab`
+Node: `Type contains Person`
+
+...then **person** `Abraham Lincoln` will be displayed, but **event** `Abolition` will not.
+
+A few notes:
+
+* Search is case insensitive.
+
+* This works across both node and edge filters.  So ALL node and ALL edge filters must pass.
+
+* Any inactive filter is ignored (e.g. the operator is `--` or the value is `...`).
+
+* Any edge that is connected to a hidden node is automatically hidden, overriding any filter match.
+
+
+#### How are Nodes/Edges hidden?
+
+Programmatically, any node or edge that is filtered is marked with a `isFilteredOut` flag.  If `isFilteredOut` is true, the object is hidden.  If `isFilteredOut` is absent or is false, the object is displayed.
+
+Hiding is simply done by setting the opacity of the node or edge.  Nodes and edges are not actually removed from the graph.
+
+
+
+### Storyboard
+
+With the Filtering system, we introduce a new development toolkit [storybook.js](https://storybook.js.org/).  This is primarily used for the basic component development and data architecture design.  
+
+* It is not yet fully integrated with the UNISYS architecture.
+* It is not yet fully integrated with bootstrap/css, so components are not displayed using the site's settings.
+
+To run storybook, use `npm run storybook`.
+