JavaScript SDK for built.io

Class: Group

Group

A Group is special type of field in Built.io Backend. The reason its named such is that its a set of fields grouped together. Each group field has its own schema and can contain sub-groups.

new Group(fieldUid, data){Group}

group.js, line 6
This should be used to represent a 'group field' in your class. This representation can then be passed to methods that accept a Built.Group structure as argument.
Name Type Description
fieldUid String The Uid of the field in your class schema.
data object | Built.Group | Built.GroupMultiple Can be 1] Plain JavaScript object representing intial values 2] Instance of Built.Group (sub-group) 3] Instance of Built.GroupMultiple (sub-group)
Example
Constructor accepting Plain JavaScript Object

var person = Built.Group('person', {
   name: 'John',
   age: 22
});

Constructor accepting instance of Built.Group

// To construct structure in which a group field contains a sub-group use syntax shown below
var address = Built.Group('address', {
   city: 'Mumbai',
   state: 'Maharashtra'
});
var person = Built.Group('person', address);
console.log(person.toJSON())

Methods

staticGroup.setReferenceWhere(field_uid, query){Group}

group.js, line 243
Fires a query on Built.io Backend and the object that fulfills the query condition is assigned in the reference field. Note: 'query' should be such that only one object should satisfy it, as Built.io Backend doesn't allow multipe references to be set using a 'query'
Name Type Description
field_uid String The uid of the reference field
query object JavaScript object specifying the conditions
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'Class('class_name').Object returns an 'Object' constructor
// 'project' is a uid of a class on Built.io Backend
var Project = Built.App('blt5d4sample2633b').Class('project').Object;
var project = Project();

var pm = Built.Group('project_manager', [{
   name: 'John',
   age: 32
}])

pm = pm.setReferenceWhere("departments", {
   department_type:"type2"
})

project
.addGroup(pm)
.save()
.then(function(project) {
   console.log(project.toJSON())
})

staticGroup.setReferenceWithObject(field_uid, refObjs){Group}

group.js, line 282
This method will first create object(s) in referred class and then assigns its uids in the base class's referring field. Example: Consider you have a reference field 'project' in class 'Bugs' class. This method would first create object(s) in 'Project' class and then assign its 'uids' in 'Bugs' class's reference field 'project'.
Name Type Description
field_uid String The uid of the reference field or "." delimated string for 'group' fields as shown in example
refObjs Object | Array JSON object or an array of plain JavaScript objects or SDK object(s)
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'Class('class_name').Object returns an 'Object' constructor
// 'project' is a uid of a class on Built.io Backend
var Project = Built.App('blt5d4sample2633b').Class('project').Object;
var project = Project();

var pm = Built.Group('project_manager', [{
   name: 'John',
   age: 32
}])

pm = pm.setReferenceWithObject("departments", [{
   name:'Department A',
   department_type: "type1"
},{
   name: "Department B",
   department_type: "type2"
}])

project
.addGroup(pm)
.save()
.then(function(project) {
   console.log(project.toJSON())
})

addGroup(group){Group}

group.js, line 457
Adds a sub-group under the current group.
Name Type Description
group Built.Group | Built.GroupMultiple Instance of Buillt.Group or Built.GroupMultiple
Example
// 'blt5d4sample2633b' is a dummy Application API key
var person = Built.Group('person', {
   name: 'John',
   age: 22
})
var address = Built.Group('address',{
   city: 'Mumbai',
   area: 20000
})
person = person.addGroup(address)

assign(data){Group}

group.js, line 111
To set multiple key value pair in group use this method.

[Does not modify the Class Schema]

Name Type Description
data object Plain JavaScript object containing the new parameters
Example
// 'blt5d4sample2633b' is a dummy Application API key
var group = Built.Group('person', {
   name: 'John'
})
group = group.assign({
   age: 22,
   gender: 'Male'
})

get(property){variable}

group.js, line 88
Gets the data for the given property
Name Type Description
property String The property whose data is to be fetched
Example
// 'blt5d4sample2633b' is a dummy Application API key
var group = Built.Group('person', {
   name: 'John'
})
console.log(group.get('name'))

getGroupForKey(fieldUid){Group}

group.js, line 538
Wraps a sub-group in Built.Group construct and returns it
Name Type Description
fieldUid field The uid of the sub group field
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'address' is a sub-group in person group.
var person = Built.Group('person', {
   name: 'John',
   age: 22,
   address: {
      city: "Mumbai",
      state: "Maharasthra"
   }
})

var addressGrp = person.getGroupForKey("address")
console.log(addressGrp.toJSON())

pullValue(fieldUid, conditions){Group}

group.js, line 482
Pulls a matching value from the multiple field. The method ensures pull operation to be atmoic
Name Type Description
fieldUid String The uid of the field in which push operation needs to be performed
conditions object | Built.Group | Built.GroupMultiple Value that needs to be pulled
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'address' is field in person group which is marked multiple
var person = Built.Group('person', {
   name: 'John',
   age: 22
})
person = person.pullValue('address',["Mumbai"])

//Consider 'person' class has a group field which is marked multiple 
//to pull a value from this field follow the example shown below
var person = Built.Group('person', {
   name: 'John',
   age: 22
})
var addressGrp = Built.Group("address",{
   city: 'Mumbai',
   state: 'Maharashtra'
})
person.pullValue("address", addressGrp)

pullValueAtIndex(fieldUid, index){Group}

group.js, line 516
Pulls a value from the multiple field at a given index. The method ensures pull operation to be atmoic
Name Type Description
fieldUid String The uid of the field in which push operation needs to be performed
index Number Index from which a value needs to be pulled
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'address' is field in person group which is marked multiple
var person = Built.Group('person', {
   name: 'John',
   age: 22
})
person = person.pullValueAtIndex('address', 1)

pushValue(fieldUid, value){Group}

group.js, line 388
Pushes a value in the multiple field. The method ensures push operation to be atmoic
Name Type Description
fieldUid String The uid of the field in which push operation needs to be performed
value object | Built.Group | Built.GroupMultiple Value that needs to be pushed
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'address' is field in person group which is marked multiple
var person = Built.Group('person', {
   name: 'John',
   age: 22
})
person = person.pushValue('address',["Mumbai"])

//Consider 'person' class has a group field which is marked multiple 
//to push a new value in this field follow the example shown below
var person = Built.Group('person', {
   name: 'John',
   age: 22
})
var addressGrp = Built.Group("address",{
   city: 'Mumbai',
   state: 'Maharashtra'
})
person.pushValue("address", addressGrp)

remove(key){Group}

group.js, line 138
To delete a property from group

[Does not modify the Class Schema]

Name Type Description
key String Key of the property to be removed
Example
// 'blt5d4sample2633b' is a dummy Application API key
var group = Built.Group('person', {
   name: 'John',
   age: 22
})
group = group.remove('age')

set(key, value){Group}

group.js, line 63
Use this method to add a new key value pair in group.

[Does not modify the Class Schema]

Name Type Description
key String The key for the new property
value String Value for the new property
Example
// 'blt5d4sample2633b' is a dummy Application API key
var group = Built.Group('person', {
   name: 'John'
})
group = group.set('age', 22)

setReference(field_uid, refValue){Group}

group.js, line 190
Assigns referenced object's uids to a reference field of an object
Name Type Description
field_uid String The uid of the field whose references are to be set
refValue String | Array Single uid/SDK object or Array of uids/SDK objects
Throws:
new Error('new Error('Uid not found'))
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'Class('class_name').Object returns an 'Object' constructor
// 'project' is a uid of a class on Built.io Backend
var Project = Built.App('blt5d4sample2633b').Class('project').Object;
var project = Project();

var pm = Built.Group('project_manager', [{
   name: 'John',
   age: 32
}])

pm = pm.setReference("departments", ["blt124sample2122l", "blt311sample2324G"])

project
.addGroup(pm)
.save()
.then(function(project) {
   console.log(project.toJSON())
})

updateValueAtIndex(fieldUid, value, index){Group}

group.js, line 422
Updates a value in the multiple field. The method ensures update operation to be atmoic
Name Type Description
fieldUid String The uid of the field in which update operation needs to be performed
value object | Built.Group | Built.GroupMultiple Value that needs to be updated
index Number Index at which update should be performed
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'address' is field in person group which is marked multiple
var person = Built.Group('person', {
   name: 'John',
   age: 22
})
person = person.updateValueAtIndex('address',["Mumbai"], 2)

//Consider 'person' class has a group field which is marked multiple 
//to push a new value in this field follow the example shown below
var person = Built.Group('person', {
   name: 'John',
   age: 22
})
var addressGrp = Built.Group("address",{
   city: 'Mumbai',
   state: 'Maharashtra'
})
person.updateValueAtIndex("address", addressGrp, 2)

upsertForReference(field_uid, upsert){Group}

group.js, line 337
Use this method to perfom a upsert(update else insert) operation on reference field.
Name Type Description
field_uid String Reference uid on which UPSERT is to be performed
upsert Built.Upsert Instance of Built.Upsert
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'Class('class_name').Object returns an 'Object' constructor
// 'project' is a uid of a class on Built.io Backend
var Project = Built.App('blt5d4sample2633b').Class('project').Object;
var project = Project();

// Creating instance of Built.Upsert to represent the upsert scenarios
var upsertDep = Built.Upsert([{
   condition:{
      name: "Department A1"
   },
   replacement:{
      name: "Department A",
      department_type: "type1"
   }
},{
   condition:{
      name: "Department B1"
   },
   replacement:{
      name: "Department B",
      department_type: "type1"
   }
}]);

var pm = Built.Group('project_manager', {
   name: 'John',
   age: 32
});

pm = pm.upsertForReference('departments', upsertDep)

project
.addGroup(pm)
.save()
.then(function(project) {
   console.log(project.toJSON())
})