A5.u.arraygroup Method

Syntax

Arguments

arrayarray

The array to group.

settingsobject

The settings to use for grouping the array.

bystringfunctionarray

How to group the objects in the passed in array. The value can be a string with the path to the property to use for grouping or a function that returns the group a given item is in. An array of strings and/or functions can be passed in to allow for recursive grouping.

dataobject

The current item to be grouped.

indexnumber

The current index of the item to be grouped.

groupsobject

The settings to control created groups.

requiredarray

Optional required groups.

excludearray

Optional groups to exclude.

missingstringarray

How to treat required groups that are missing from the passed in data. Values can be "include" (the default) or "exclude" which will leave missing groups out. An array of these values can be passed in to control missing groups at each level when recursive grouping is being used.

extrastringarray

How to treat groups that are not in the required groups. A value of "include" (the default) can be used to include the extra groups after the required groups. A value of "include-before" will include the extra groups before the required groups. A value of "exclude" will exclude the extra groups. An array of these values can be passed in to control extra groups at each level when recursive grouping is being used.

orderstringarrayfunction

The order to apply to the groups. See A5.u.array.order.

propertiesobject

The names of properties to output in the returned array of group objects.

namestringarray

The name of the group name property. The default value is "name". An array of these property names can be passed in to control the property name at each level when recursive grouping is being used.

itemsstringarray

The name of the property containing the items in the group. The default value is "items". An array of these property names can be passed in to control the property name at each level when recursive grouping is being used.

mapstringarray

The name of the property containing the mapping of the items in the group back to the original array indexes. The default value is "map". An array of these property names can be passed in to control the property name at each level when recursive grouping is being used.

groupsarray

An array of grouped objects.

Description

Group an array of object.

Discussion

The A5.u.array.group method can be used to turn a flat array of objects into an array of groups of object. Multiple levels of grouping can be used by passing in an array of grouping values to the "by" setting. A grouping value can be either a string containing the path to the property in each object that should be used for group, or a function that will return the group each item is in.

When a property name is being used, certain operations can be preformed on the property. These operations are included using a ":" after the property name. Operations include "first", "upper", "lower" and "round".

The "first" operator will return the first character of the property. If more then one character wants to be returned then the number of characters can be specified in parentheses. For example "company:first(3)" will return the first three characters of the "company" field.

The "upper" and "lower" operators can be used on fields that are strings to return the value in upper or lower case. They can also be compounded with the "first" operator. For example "company:first(3):upper" will return the first three characters of the "company" field in upper case.

The "round" operator will return the rounded number of a value. If the value wants to be rounded to a decimal then the number of decimals can be specified in parentheses. For example "score:round(2)" would return the value of the "score" field rounded to two decimal places.

For more complicated grouping a function can be used. This function will be passed the data for each item and must return the name of the group the item is in. If an array of names is returned then the item will be placed in each of the named groups.

Example

var arr = [
	{"Firstname":"John","Lastname":"Smith","City":"Boston","State":"MA"},
	{"Firstname":"Henry","Lastname":"Rhodes","City":"New York","State":"NY"},
	{"Firstname":"Allison","Lastname":"Richards","City":"New York","State":"NY"},
	{"Firstname":"Amanda","Lastname":"Sanders","City":"Burlington","State":"MA"},
	{"Firstname":"Nancy","Lastname":"Clark","City":"Boston","State":"MA"},
	{"Firstname":"Cecelia","Lastname":"Dawkins","City":"Buffalo","State":"NY"},
	{"Firstname":"Kathy","Lastname":"Morton","City":"New York","State":"NY"}
]
var grpArr = A5.u.array.group(arr,{
	by: ['State','Lastname:first(1)'],
	groups: {
		required: [['NY','CA','MA']],
		order: ['State','Lastname']
	},
	properties: {
		name: ['state','lastInitial']
	}
});
// grpArr = [
//	{
//		"state":"NY",
//		"items":[
//			{
//				"lastInitial": "R",
//				"items": [{"Firstname":"Henry","Lastname":"Rhodes","City":"New York","State":"NY"},{"Firstname":"Allison","Lastname":"Richards","City":"New York","State":"NY"}],
//				"map": [1,2]
//			},
//			{
//				"lastInitial": "D",
//				"items": [{"Firstname":"Cecelia","Lastname":"Dawkins","City":"Buffalo","State":"NY"}],
//				"map": [5]
//			},
//			{
//				"lastInitial": "M",
//				"items": [{"Firstname":"Kathy","Lastname":"Morton","City":"New York","State":"NY"}],
//				"map": [6]
//			}
//		],
//		"map": [1,2,5,6]
//	},
//	{
//		"state": "CA",
//		"items": [],
//		"map": []
//	},
//	{
//		"state": "MA",
//		"items": [
//			{
//				"lastInitial": "S",
//				"items": [{"Firstname":"John","Lastname":"Smith","City":"Boston","State":"MA"},{"Firstname":"Amanda","Lastname":"Sanders","City":"Burlington","State":"MA"}],
//				"map":[0,3]
//			},
//			{
//				"lastInitial":"C",
//				"items":[{"Firstname":"Nancy","Lastname":"Clark","City":"Boston","State":"MA"}],
//				"map": [4]
//			}
//		],
//		"map":[0,3,4]
//	}
// ]