feat(formatter): add new arrayObjectToCsv Formatter

aurelia-slickgrid/src/aurelia-slickgrid/formatters/arrayObjectToCsvFormatter.ts

@@ -0,0 +1,35 @@
+import { Column } from './../models/column.interface';
+import { Formatter } from './../models/formatter.interface';
+
+export const arrayObjectToCsvFormatter: Formatter = (row: number, cell: number, value: any, columnDef: Column, dataContext: any) => {
+  const propertyNames = columnDef && columnDef.params && columnDef.params.propertyNames;
+  const parentObjectKeyName = columnDef && columnDef.field && columnDef.field.split('.')[0]; // e.g. "users.roles" would be "users"
+  if (!propertyNames || !Array.isArray(propertyNames) || !parentObjectKeyName) {
+    throw new Error(`Formatters.arrayObjectToCsv requires you to pass an array of "propertyNames" (declared in "params") that you want to pull the data from.
+      For example, if we have an array of user objects that have the property of firstName & lastName then we need to pass in your column definition:: { params: { propertyNames: ['firtName'] }}`);
+  }
+
+  // the dataContext holds all the data, so we can find the values we want even when "value" argument might be null
+  // e.g. if we want to use the propertyNames of ['firstName', 'lastName'] from the "users" array of objects
+  if (dataContext[parentObjectKeyName] && Array.isArray(dataContext[parentObjectKeyName])) {
+    // we will 1st get the object from the dataContext, then
+    if (Array.isArray(dataContext[parentObjectKeyName])) {
+      const outputStrings = [];
+      dataContext[parentObjectKeyName].forEach((data) => {
+        const strings = [];
+
+        // 2nd from that data loop through all propertyNames we want to use (e.g.: ['firstName', 'lastName'])
+        propertyNames.forEach((prop) => {
+          strings.push(data[prop]);
+        });
+        // we will join these strings with spaces (e.g. 'John Doe' where 'John' was firstName and 'Doe' was lastName)
+        outputStrings.push(strings.join(' '));
+      });
+
+      // finally join all the output strings by CSV (e.g.: 'John Doe, Jane Doe')
+      const output = outputStrings.join(', ');
+      return `<span title="${output}">${output}</span>`;
+    }
+  }
+  return '';
+};

aurelia-slickgrid/src/aurelia-slickgrid/formatters/index.ts

@@ -1,4 +1,5 @@
 import { Column } from './../models/index';
+import { arrayObjectToCsvFormatter } from './arrayObjectToCsvFormatter';
 import { arrayToCsvFormatter } from './arrayToCsvFormatter';
 import { boldFormatter } from './boldFormatter';
 import { checkboxFormatter } from './checkboxFormatter';
@@ -36,6 +37,14 @@ import { yesNoFormatter } from './yesNoFormatter';
 
 /** Provides a list of different Formatters that will change the cell value displayed in the UI */
 export const Formatters = {
+  /**
+   * Takes an array of complex objects converts it to a comma delimited string.
+   * Requires to pass an array of "propertyNames" in the column definition the generic "params" property
+   * For example, if we have an array of user objects that have the property of firstName & lastName then we need to pass in your column definition::
+   * { params: { propertyNames: ['firtName'] }}
+   */
+  arrayObjectToCsv: arrayObjectToCsvFormatter,
+
   /** Takes an array of string and converts it to a comma delimited string */
   arrayToCsv: arrayToCsvFormatter,
 
@@ -92,7 +101,8 @@ export const Formatters = {
 
   /**
    * Display the value as x decimals formatted, defaults to 2 decimals.
-   * You can pass "decimalPlaces" or "minDecimalPlaces" and/or "maxDecimalPlaces" to the generic "params" property, example:: `{ formatter: Formatters.decimal, params: { decimalPlaces: 3 }}`
+   * You can pass "decimalPlaces" or "minDecimalPlaces" and/or "maxDecimalPlaces" to the "params" property.
+   * For example:: `{ formatter: Formatters.decimal, params: { decimalPlaces: 3 }}`
    * The property "decimalPlaces" is an alias of "minDecimalPlaces"
    */
   decimal: decimalFormatter,
@@ -128,7 +138,9 @@ export const Formatters = {
   mask: maskFormatter,
 
   /**
-   * You can pipe multiple formatters (executed in sequence), use params to pass the list of formatters. For example::
+   * You can pipe multiple formatters (executed in sequence), use params to pass the list of formatters.
+   * Requires to pass an array of "formatters" in the column definition the generic "params" property
+   * For example::
    * { field: 'title', formatter: Formatters.multiple, params: { formatters: [ Formatters.lowercase, Formatters.uppercase ] }
    */
   multiple: multipleFormatter,