Setter Functions

PiMunkey Documentation -> Pi Object Reference ->

add: Appends values to the end of a PiComponent when used as an Array.

Usage:

add (any item1 [, any item2, ... any itemN]) : Pass one or more items to be added to the end of the array. The items may be of any data type. To add items to the beginning or in the middle of an array, use the "insertAt" function.

Example:

ColdFusion:
<cfset numbers = newMunkey(1,3,5,7) />
<cfset numbers.add(2,4,6) />

Javascript:
var numbers = new PiObject([1,3,5,7]);
numbers.add(2,4,6);

result: 1,3,5,7,2,4,6

NOTE: The add() function will not accept named attributes.
destroy: [Javascript only] Cleans up the Pi Object for garbage collection from Javascript memory.

Usage:

destroy() : Call the function without arguments. It will delete all of the internal variables, and all filters and listeners, and references to other objects. (This is important so that linked objects don't remain in memory.)

Example:

Javascript:
// Cleanup child objects, if any
piObject.each( function(object, property, value) {
     if ( value instanceof PiObject )
          value.destroy();
     }
});
piObject.destroy();
delete PiObject;

CAUTION: If a property is a simple object, like a string, number, or date, it will be deleted, but if it is a complex object that has been assigned by reference, that other object will continue to exist, unless you delete it as well. It has to be assumed that something else might also have a reference to that object.
extend: [Javascript only] Creates a new object class that inherits from the PiObject class.

Usage:

extend (function constructor) : Call this function and it will return the new class. You can optionally pass a function to use as the constructor for the new class. The extend() function is also available on all children objects, as well as a reference to the parent prototype class, as a class-level variable named 'parent'. All pi object children call an init() function after instantiation, which you can override to execute your own code. The init function receives the configuration object used when the new object is created.

Example:

Javascript:
Car = PiObject.extend();
Car.prototype.init = function(config) {
     Car.parent.init.apply(this,arguments);
     // Car initialization code here
}
SportsCar = Car.extend();
SportsCar.prototype.init = function(config) {
     SportsCar.parent.init.apply(this,arguments);
     // Sports Car initialization code here
}
var myCar = new SportsCar({
     type: "DeLorean",
     color: "silver",
     accessories: new PiObject(["flux capacitor"])
});
insertAt:

Usage:

insertAt (integer index, any item1 [, any item2, ... any itemN]) : The first argument is always a ColdFusion-type numeric index, i.e. starting at 1 and going up to the length of the array. The items passed will be inserted into the array before the specified index position. The index is then followed by one or more items to be added to the array at the desired position. The items may be of any data type. To add items to the end of an array, use the "add" function.

Example:

ColdFusion:
<cfset numbers = newMunkey(1,3,5,7) />
<cfset numbers.insertAt(2,2) />
<cfset numbers.insertAt(4,4,6) />

Javascript:
var numbers = new PiObject([1,3,5,7]);
numbers.insertAt(2,2);
numbers.insertAt(4,4,6);

result: 1,2,3,4,6,5,7 (Note that the numbers 6 and 5 are reversed, because 4 and 6 were both inserted before 5.)

NOTE: The insertAt() function will not accept named attributes.
move: Moves a value to a new ordered location in an object.

Usage:

move (any oldIndex, any newIndex) : The first argument is the current location of the property in the object. The second argument is the desired location of the property. Most often these arguments will be numbers, but if you added the items by names, you can also use the property names instead of numbers. In addition, you can use negative indexes to count backwards from the end of the list.

Example:

ColdFusion:
<cfset numbers = newMunkey(1,2,3,4,5) />
<cfset numbers.move(5,3) />

Javascript:
var numbers = new PiObject([1,2,3,4,5]);
numbers.move(5,3);

result: 1,2,5,3,4

CAUTION: The move() function does not fire any filters or listeners.

CAUTION: An index of 0 is a special case, depending on the language you're programming in. In Javascript, where indexes start with 0, an index of 0 will indicate the first item in the list, but in ColdFusion, where indexes start with 1, and index of 0 will count backwards form the end of the list and give you the last item in the list.
newMunkey: [ColdFusion only] A shortcut function for any child of the PiComponent that returns a new instance of the base PiComponent class, and not the child class. To get a new instance of the child class use the 'new' function. WARNING: This function should never be overridden by a child class!
Usage:
1. newMunkey ( ) : Call the function without arguments to get an empty PiComponent.
2. newMunkey (propertyName1 = any item1 [, propertyName2 = any item2, ... propertyNameN = any itemN]) : If you use the named attribute syntax in ColdFusion, the returned object will be initialized with the arguments passed. Each argument name will be used as the name of the property, and the value of the argument will be used as the associated item.
3. newMunkey (ArgumentCollection = Struct collection) : If you use the ArgumentCollection syntax in ColdFusion, the returned object will be initialized with the values of passed structure. The name of each member of the passed structure will be used as the name of the property, and the value of each member of the structure will be used as the associated item.
Examples:

Each of the following examples will produce the same object structure:

<cfset object = newMunkey() />
<cfset object.set(id="page1", title="Page One", template="first.cfm") />

<cfset object = newMunkey(id="page1", title="Page One", template="first.cfm") />

<cfset args["id"] = "page1" />
<cfset args["title"] = "Page One" />
<cfset args["template"] = "first.cfm" />
<cfset object = newMunkey(ArgumentCollection=args) />

Caller Page Code: <my:customTag id="page1", title="Page One", template="first.cfm" />
Custom Tag Code: <cfset object = newMunkey(ArgumentCollection=Attributes) />
remove: Removes the specified property from the object.
Usage:
1. remove (integer index) : Removes the item at the specified position in the object.
2. remove(string propertyName) : Removes the item with the associated name.
Examples:

ColdFusion:
<cfset numbers = newMunkey(1,3,5,7) />
<cfset numbers.remove(4) />
<cfset numbers.remove(2) />

Javascript:
var numbers = new PiObject([1,3,5,7]);
numbers.remove(4);
numbers.remove(2);

result: 1,5

ColdFusion:
<cfset page = newMunkey(id="page1", title="Page One", template="first.cfm", group="Lesson 1") />
<cfset page.remove("group") />
<cfset properties = page.getPropertyList() />

Javascript:
var page = new PiObject({
     id: "page1",
     title: "Page One",
     template: "first.html",
     group: "Lesson 1"
});
page.remove("group");
var properties = page.getPropertyList();

result: The "properties" variable contains "id,title,template" because "group" is now gone.
removeAll: Removes all properties from the object.
Usage:
1. removeAll() : Deletes all properties from the object.
Examples:

ColdFusion:
<cfset collection.removeAll() />

Javascript:
// Cleanup child objects, if any
piObject.each( function(object, property, value) {
     if ( value instanceof PiObject )
          value.destroy();
     }
});
piObject.removeAll();

result: empty

NOTE: This function does not affect listeners or filters.

CAUTION: For Javascript garbage collection, if a property is a simple object, like a string, number, or date, it will be deleted, but if it is a complex object that has been assigned by reference, that other object will continue to exist, unless you delete it as well. It has to be assumed that something else might also have a reference to that object.

CAUTION: When using removeAll(), you cannot use a listener to restore any values.
set: A function for direct assignment of properties, singly or in bulk.
Usage:
1. set (string propertyName, any item) : If you use unnamed arguments, the first argument is the unique name of the property within the object, and the second argument is what to store there. The second argument can be of any data type you want.
2. set (propertyName1 = any item1 [, propertyName2 = any item2, ... propertyNameN = any itemN]) : [ColdFusion only] If you use the named attribute syntax in ColdFusion, each argument name will be used as the name of the property, and the value of the argument will be used as the associated item.
3. set (ArgumentCollection = Struct collection) : [ColdFusion only] If you use the ArgumentCollection syntax in ColdFusion, the name of each member of the passed structure will be used as the name of the property, and the value of each member of the structure will be used as the associated item.
4. set (array values) : [Javascript only] If you use an array to set the values, it will create unnamed properties in the object using an array-style syntax.
5. set (object config) : [Javascript only] If you use an object to set the values, the properties of the object are used as the property names, storing their corresponding values. It essentially creates a pi object version of a regular object.
Examples:

Each of the following examples will produce the same object structure:

ColdFusion:
<cfset object.set("id", "page1") />
<cfset object.set("title", "Page One") />
<cfset object.set("template", "first.cfm") />

<cfset object.set(id="page1", title="Page One", template="first.cfm") />

<cfset args["id"] = "page1" />
<cfset args["title"] = "Page One" />
<cfset args["template"] = "first.cfm" />
<cfset object.set(ArgumentCollection=args) />

Caller Page Code: <my:customTag id="page1", title="Page One", template="first.cfm" />
Custom Tag Code: <cfset object.set(ArgumentCollection=Attributes) />

Javascript:
var object = new PiObject();

object.set("id", "page1");
object.set("title", "Page One");
object.set("template", "first.html");

object.set({
     id: "page1",
     title: "Page One",
     template: "first.html"
});

var args = {
     id: "page1",
     title: "Page One",
     template: "first.html"
};
object.set(args);