Document dashboard widgets

[Brian Lewis]

Pull Request #240 and following have introduced over a dozen new components in the dashboard system; none of these contain any source code comments or documentation.

To support future maintenance, please can this code include:

1) in each component, a brief description of its purpose, and where it sits in the component hierarchy (ie what components consume it, what components it consumes)

2) details of the bindings used by these components, purpose; values expected

3) Where a component defines an object to be consumed by a subisdiary component, provide some brief description of the object, how it is intended to be used; if appropriate, why it is defined as it is.

Not expecting explanations of es6 language features or lodash functions, or formal structrued documentation but, something to enhance understandability. For example ,the intent of code such as the following could be clarified:

   private xReduce = _.memoize((tableName, ...inputs) => this.xFilter.xReduce.bind(this.xFilter)(...inputs))
    private groupReduceSum = _.memoize((groupName, dim, va) => dim.group().reduceSum(va));



   public toggle = _.memoize(
      (key) => ({ key: filterValue }) => {
        if (!filterValue) { return; }
        this.options[key] = filterValue === this.options[key] ? null : filterValue; 
      }
    );      

e.g.

// provide a function a dashboard client may use to toggle the value of an option. 
//This will be used on selecting a row ( in a table) or clicking a datum in a chart. 
// filterValue is the property of options to toggle.
// e.g. toggle('selectedDistrict')
  public toggle = _.memoize(
      (key) => ({ key: filterValue }) => {
        if (!filterValue) { return; }
        this.options[key] = filterValue === this.options[key] ? null : filterValue; 
      }
    );      

[Jeremy Kells]

I've documented the components used by the dashboards to ensure they can be reused easily. The dashboards themselves are primarily there to fetch the data and transform it to the expected shape expected by the components, and while I've used a lot of lodash to do this, I suspect you will prefer to do this in sql before fetching it from the server. Which is fine, there is room here for personal preference in shaping the data.

Beyond this, there is just one pattern that you will see everywhere for which the reason may not be apparent - the use of memoize in the dashboards. While there is some benefit in avoiding calculating the same thing over and over again, this is being used due to how equality of objects in javascript works, and how this impacts the angularjs digest cycle.

In the angularjs digest cycle all of a component's parameters are essentially polled, to see if they have changed - this is how angularjs components know if they need to rerender or not. If a parameter(binding) has changed, rerender. However if a binding is to the output of a function that returns an object, even if it returns an object that contains the all the same values, it's a different object - and the equality test fails. This causes the component to rerender, and as this will happen every digest cycle, hit a safety mechanism whereby if a value changes in 10 successive digest cycles, angularjs throws an exception and stops.

Luckily, simply memoizing the function will solve this, with potentially some saved calculation cycles as well.

However it's necessary to understand the limitations of lodash's memoize function - By default, the first argument provided to the memoized function is coerced to a string and used as the cache key. - It was often necessary to pass a resolver to calculate an alternative key as the second argument to memoize. Also there were times it was necessary to pass an extra argument (not passed to the function being memoized) to use as the key.

@softwords @ghachey As this both requires a longer explanation, and occurs in many, many places in the code It's probably best to move this to the wiki

[Ghislain Hachey]

Jeremy documented his components and the notes on memoize in this tickets was documented in the developer guide at http://docs.pacific-emis.org/doku.php?id=developer_manual#low_level_documentation_and_api for posterity