1. Home
  2. Namespaces
  3. FooGallery.utils.obj

obj

Contains common object utility methods.

Details

core/js/foogallery.js, line 1546

Methods

<static> create( proto ) → {object}

Creates a new object with the specified prototype.

Description

This is a basic implementation of the Object.create method.

Parameters
Name Type Description
proto object

The object which should be the prototype of the newly-created object.
Returns

A new object with the specified prototype.

Details

core/js/foogallery.js, line 1555

<static> extend( target, object [, ...objectN ] ) → {Object}

Merge the contents of two or more objects together into the first target object.

Description

This does not merge arrays by index as jQuery does, it treats them as a single property and replaces the array with a shallow copy of the new one.

This method makes use of the FooGallery.utils.obj.merge method internally.

Parameters
Name Type Attributes Description
target Object

The object to merge properties into.
object Object

An object containing properties to merge.
objectN Object <optional>
<repeatable>

Additional objects containing properties to merge.
Returns

The target merged with the contents from any additional objects.

Examples

// alias the FooGallery.utils.obj namespace
var _obj = FooGallery.utils.obj,
	// create some objects to merge
	defaults = {"name": "My Object", "enabled": false, "arr": [1,2,3]},
	options = {"enabled": true, "something": 123, "arr": [4,5,6]};

// merge the two objects into a new third one without modifying either of the originals
var settings = _obj.extend( {}, defaults, options );

console.log( settings ); // => {"name": "My Object", "enabled": true, "arr": [4,5,6], "something": 123}
console.log( defaults ); // => {"name": "My Object", "enabled": true, "arr": [1,2,3]}
console.log( options ); // => {"enabled": true, "arr": [4,5,6], "something": 123}

Details

core/js/foogallery.js, line 1572

<static> merge( target, object ) → {Object}

Merge the contents of two objects together into the first target object.

Description

This does not merge arrays by index as jQuery does, it treats them as a single property and replaces the array with a shallow copy of the new one.

This method is used internally by the FooGallery.utils.obj.extend method.

Parameters
Name Type Description
target Object

The object to merge properties into.
object Object

The object containing properties to merge.
Returns

The target merged with the contents from the object.

Examples

// alias the FooGallery.utils.obj namespace
var _obj = FooGallery.utils.obj,
	// create some objects to merge
	target = {"name": "My Object", "enabled": false, "arr": [1,2,3]},
	object = {"enabled": true, "something": 123, "arr": [4,5,6]};

console.log( _obj.merge( target, object ) ); // => {"name": "My Object", "enabled": true, "arr": [4,5,6], "something": 123}

Details

core/js/foogallery.js, line 1607

<static> mergeValid( target, validators, object [, mappings ] ) → {Object}

Merge the validated properties of the object into the target using the optional mappings.

Parameters
Name Type Attributes Description
target Object

The object to merge properties into.
validators FooGallery.utils.obj~Validators

An object containing validators for the target object properties.
object Object

The object containing properties to merge.
mappings FooGallery.utils.obj~Mappings <optional>

An object containing property name mappings.
Returns

The modified target object containing any valid properties from the supplied object.

Examples

Shows the basic usage for this method and shows how invalid properties or those with no corresponding validator are ignored.


// alias the FooGallery.utils.obj and FooGallery.utils.is namespaces
var _obj = FooGallery.utils.obj,
	_is = FooGallery.utils.is;

//create the target object and it's validators
var target = {"name":"John","location":"unknown"},
	validators = {"name":_is.string,"location":_is.string};

// create the object to merge into the target
var object = {
	"name": 1234, // invalid
	"location": "Liverpool", // updated
	"notMerged": true // ignored
};

// merge the object into the target, invalid properties or those with no corresponding validator are ignored.
console.log( _obj.mergeValid( target, validators, object ) ); // => { "name": "John", "location": "Liverpool" }

Shows how to supply a mappings object for this method.


// alias the FooGallery.utils.obj and FooGallery.utils.is namespaces
var _obj = FooGallery.utils.obj,
	_is = FooGallery.utils.is;

//create the target object and it's validators
var target = {"name":"John","location":"unknown"},
	validators = {"name":_is.string,"location":_is.string};

// create the object to merge into the target
var object = {
	"name": { // ignored
		"proper": "Christopher", // mapped to name if short is invalid
		"short": "Chris" // map to name
	},
	"city": "London" // map to location
};

// create the mapping object
var mappings = {
	"name": [ "name.short", "name.proper" ], // try use the short name and fallback to the proper
	"location": "city"
};

// merge the object into the target using the mappings, invalid properties or those with no corresponding validator are ignored.
console.log( _obj.mergeValid( target, validators, object, mappings ) ); // => { "name": "Chris", "location": "London" }

Details

core/js/foogallery.js, line 1644

<static> prop( object, name [, value ] ) → {*}

Get or set a property value given its name.

Parameters
Name Type Attributes Description
object Object

The object to inspect for the property.
name string

The name of the property to fetch. This can be a . notated name.
value * <optional>

If supplied this is the value to set for the property.
Returns

The value for the name property, if it does not exist then undefined.

If a value is supplied this method returns nothing.

Examples

Shows how to get a property value from an object.


// alias the FooGallery.utils.obj namespace
var _obj = FooGallery.utils.obj,
	// create an object to test
	object = {
		"name": "My Object",
		"some": {
			"thing": 123
		}
	};

console.log( _obj.prop( object, "name" ) ); // => "My Object"
console.log( _obj.prop( object, "some.thing" ) ); // => 123

Shows how to set a property value for an object.


// alias the FooGallery.utils.obj namespace
var _obj = FooGallery.utils.obj,
	// create an object to test
	object = {
		"name": "My Object",
		"some": {
			"thing": 123
		}
	};

_obj.prop( object, "name", "My Updated Object" );
_obj.prop( object, "some.thing", 987 );

console.log( object ); // => { "name": "My Updated Object", "some": { "thing": 987 } }

Details

core/js/foogallery.js, line 1718

Type Definitions

Mappings

An object used by the mergeValid method to map new values onto the target object.

Description

The mappings object is a single level object. If you want to map a property from/to a child object on either the source or target objects you must supply the name using . notation as seen in the below example with the "name.first" to "Name.Short" mapping.

Examples

The basic structure of a mappings object is the below.


{
	"TargetName": "SourceName", // for top level properties
	"Child.TargetName": "Child.SourceName" // for child properties
}

Given the following target object.


var target = {
	"name": {
		"first": "",
		"last": null
	},
	"age": 0
};

And the following object to merge.


var object = {
	"Name": {
		"Full": "Christopher",
		"Short": "Chris"
	},
	"Age": 32
};

The mappings object would look like the below.


var mappings = {
	"name.first": "Name.Short",
	"age": "Age"
};

If you want the "name.first" property to try to use the "Name.Short" value but fallback to "Name.Proper" you can specify the mapping value as an array.


var mappings = {
	"name.first": [ "Name.Short", "Name.Proper" ],
	"age": "Age"
};
Details
Object.<string, string> | Object.<string, Array.<string>>

core/js/foogallery.js, line 1797

Validators

An object used by the mergeValid method to validate properties.

Description

The validators object is a single level object. If you want to validate a property of a child object you must supply the name using . notation as seen in the below example with the "name.first" and "name.last" properties.

Any function that accepts a value to test as the first argument and returns a boolean can be used as a validator. This means the majority of the FooGallery.utils.is methods can be used directly. If the property supports multiple types just provide your own function as seen with "name.last" in the below example.

Examples

The basic structure of a validators object is the below.


{
	"PropName": function(*):boolean, // for top level properties
	"Child.PropName": function(*):boolean // for child properties
}

Given the following target object.


var target = {
	"name": {
		"first": "", // must be a string
		"last": null // must be a string or null
	},
	"age": 0 // must be a number
};

The validators object could be created as seen below.


// alias the FooGallery.utils.is namespace
var _is = FooGallery.utils.is;

var validators = {
	"name.first": _is.string,
	"name.last": function(value){
		return _is.string(value) || value === null;
	},
	"age": _is.number
};
Details
Object.<string, function(*): boolean>

core/js/foogallery.js, line 1834