~~Title: Data Collection API Components~~

<html><font color=#990000 size="+2"><b>Data Collection API</b></font></html>

The application environment offers allows users to work with several native and embedded //Javascripr// libraries for managing data structures.  These //Data Collections// shoudl be considered client side extensions of the //Data Fabric// collection model.  Where appropriate the same teminology, concepts and behavior is implemented.  //Data Collections// are useful for managing data on a client application (or device) and are intended for use as client-side data caching.  This can be very useful in situations where large amounts of local data are needed.  

<color #00a2e8>Knowledge Works™</color> supports a cached mode of operations wherein data are dowloaded to the client application or device as part of standard function.  THos means no futher access to the back-end system is requried in order for the application to function.  //Data Collections// may be used to extract and slide the data from the cache as necessary to affect client-side analytics if necessary.  It is also a good general approach for handling special cases with controls that may need to present data in a differnt sorted or filterd order. 

\\

=== Build an Array of Objects from Another Array ===

Working with JSON data collections in //Triggers//, //Formatters// and //Dashboard Scene// initialization scripts
often includes searching and processing collections of objects found in ''Query Result'' objects or ''Controls'', such 
as ''Choice'' or ''Grid''.  

//Array// and //Map// are common and useful collections that are often returned as part of a result data Object (SDO). In this
example an array of strings is converted into a map with key and value that are the same.  Other map value initialization 
is possible using various techniques.

<sxh DSQL; gutter: true;>
// assign your array here using copied path:
var arrayOfStringCodes = foundData.enAspects.someKey; 
// now you can map your array of strings into array of choice objects
var choices = arrayOfStringCodes.map(function(code){
    return {
      label: code,
      value: code,
      selected: code == event.data.name
    };
  });
</sxh>

\\

=== Lodash Object Find ===

[[wp>Lodash]] is a popular javascript library that allows users to work with data collections such as
map, array and list.  It alows users to easily search and manipulate JSON data.  This can be very
useful when working with large objects returned form the data fabric and may be used to perform additional
sorting or filtering of cached result sets. A Map object is provided as part of the API an included in the
functional script of the RTAI environment.  It provides standard methods for random key data manipulation
and search as welas other convenience methods.

<sxh DSQL; gutter: true;>
   // lodash example of find(.) by key
   var fElement = _.find(sourceData.rtaiKnowledgeGraph.kEngrams,['refKeyPredicate', event.data.name]);
   console.log('Found Data:', fElement);
   // get Aspect icd code array..
   var ICD_Codes = fElement.enAspects.ICD10_cdes; 
   // create Choices object from array of Codes
   var choices = ICD_Codes.map( function(code) {
      return {
      	 label: code,
      	 value: code,
         selected: code == event.data.name
       };
    });
</sxh>

\\

=== Iterating and Working With Maps ===

You can use the ''map()'' method to iterate over //Array// objcts or //Data Grid// rows. The example below
On each iteration additional logic can be performed and a composite result can also be returned if necesary.
This approach is similar to the ''forEach'' function that performs a similar function.  However the //map//
element does not provide an implicit //index// value, which can be used to match //Data Grid// row elements 
or lookup //Array// entries.

<sxh DSQL; gutter: true;>
  
   // Get an array variable 
   var choices = component.getVariable('choices');
  
   // Iterate over an Array via MAP object 
   var count = 0;
   const selectCount = choices.map(obj => {
    
     console.log('Mapped: ', obj);
    
     if(obj.selected === true) {
        count++;
        console.log('Selected: ' + obj.label);
        ..
       }
    
      return count;
   });
  
   console.log('Selected #: ' + count);
  ..
</sxh>

The example below illustrates how to use a ''forEach()'' method to iterate over //Array// objects and populate //Data Grid// row objects.
This approach can also be used to iterate over the ''grid.data'' internal data array. This can be very useful for cross-grid datta lookups
or matches to emulate //JOIN// behavior in the client.

<sxh DSQL; gutter: true;>
  
  var keyList = component.getControl('grd_keyList');
  var keyWords = (component.getControl('chs_keyWords')).value;
  // add to the Key Term grid
  keyWords.forEach( function(row, idx) {
     var kWord = keyWords[idx];
     var row = { cells: [ {value: null}, {text: kWord.value}] };
     keyList.addRow(row);
     });
  ..
</sxh>

This example loads a popular ''cmOptions'' name/value pair collection returned by an RTAI result object into a
//Map// object by turning them into //Map Entries//.

<sxh DSQL; gutter: true;>

function(html, component) { 
  // verify that data component initialized, since all 
  // queries are asynchronouse and reults are non-preemptive..
  if(component.data != null) {
    // convert object to Map
    var ttypes = new Map(Object.entries(component.data.rtaiOptionCollections.cmOptions));
    // get map element - Type Description
    return ttypes.get(component.getVariable('resourceType'));
    }
  return component.getVariable('resourceType');
}
</sxh>

Sometimes its useful to access //Map// elements by their index.  The //Keys// are returned in the
order they were inserted into a map.  JSON objects returned from the data fabric may be sorted
prior to being sent.  The order in which the elements appear in a JSON objec is considerd absolute
order in whcih the entries are insterted int a //Map//.


<sxh DSQL; gutter: true;>
  
  var appMap = new Map(Object.entries(component.data.rtaiMultiSeriesGrid.cmOptions));
  console.log('First App Item: ' + Array.from(appMap.keys())[0]);
  ..
</sxh>