DP_ObCollection

A DP_ObCollection is used to manage multiple instances of a JavaScript object as a single logical unit. Object instances stored in the collection are called “Members” of the collection. The DP_ObCollection assumes the following:

  • The DP_ObCollection does not maintain any specific order of it members.
  • Optionally all members of an DP_ObCollectionOrdered can be validated for type.
  • A property of the specified Member object must contain a unique Key to be used as the member identifier.

Use the more advanced DP_ObCollectionOrdered if your application requires members to be maintained in order.

This component requires a JavaScript (ECMAScript) 1.3 (or better) environment and has been tested successfully on Internet Explorer 6+, Firefox 1+ and Opera 9+.

Download

The component is available from GitHub:

All downloads and code are covered by our Source Code Policy.

Usage

The library consists of a single JavaScript file with a .JS extension.

Importing the Library

The library must be imported before it is used. To import the library use the <script> tag. For example:

<script type="text/javascript" src="DP_ObCollection.js"></script>

Your path may vary depending on the location of the script on your server.

Creating and Accessing the Object

Once the library has been imported you may create DP_ObCollection objects as you would any other JavaScript object. For example:

var MyCollection = new DP_ObCollection(...);

See the Constructor section for more information.

Once you have created an instance of the object you can use the methods and properties provided to add, manipulate, delete and access members and information about them. See the Examples section for some sample code.

Constructor

DP_ObCollection()

The constructor. Used to create a new DP_ObCollection instance.

Method Signature

new DP_ObCollection(MemberType, MemberKeyName)

Arguments

  • MemberType: Object Constructor reference or null, Required. If a reference to an object constructor is passed all objects added to the collection will be validated against that type. Use the constructor reference (for example “Option.constructor”) or a reference to a custom constructor function. Note that Mozilla-based browsers require that the constructor reference comes from an instantiated object (for example “new Option().constructor” rather than simply “Option.constructor”).
  • MemberKeyName: String, Required. The object property to be used as the unique identifier for DP_ObCollectionOrdered members.

Return

A reference to the new DP_ObCollection instance.

Properties and Methods

There are several properties available in an ObOrderedCollection. However it is recommended that all access to these properties occur via their related method calls.

DP_ObCollection properties available:

  • Members: A JavaScript array which contains references to all members of the collection. Access to this property is exposed via the getAll() method.
  • MemberType: A reference to the Member constructor used to validate member type. Access to this property is exposed via the getMemberType() method.
  • MemberKeyName: The name of the Member property to use as the unique member key. Access to this property is exposed via the getMemberKeyName() method.
  • CreationDate: A date/time reference referering to the instantiation time of the collection. Access to this property is exposed via the CreationDate() method.

DP_ObCollection methods available:

Note that in method/function signatures a pipe (“|”) indicates “OR” while arguments in square brackets are optional.

add()

Adds a member to the DP_ObCollection.

Method Signature

add(NewMember, AllowOverwrite)

Arguments

  • NewMember: Object. A reference to the object to be placed in the DP_ObCollection.
  • AllowOverwrite: Boolean, Optional (defaults to False). If true will allow the new Member to replace an existing Member with the same key value.

Return

Boolean. True if the new member was added, false if not (due to type validation for example).

drop()

Drops a member from the DP_ObCollection.

Method Signature

drop(MemberKey)

Arguments

  • MemberKey: String, Required. The member key of the object to return.

Return

Boolean. True if the member specified was in the collection to begin with, false if not.

dropAll() or clear()

Drops all members from the DP_ObCollection.

Method Signature

dropAll() or clear()

Arguments

  • None

Return

Boolean. True is the only return.

get()

Gets a specific member from the collection.

Method Signature

get(MemberKey)

Arguments

  • MemberKey: String, Required. The member key of the object to return.

Return

Object. A reference to the member object specified.

getAll()

Gets all of the members in the DP_ObCollection.

Method Signature

getAll()

Arguments

  • None

Return

Object. A reference to the Members object which itself contains references to all objects in the DP_ObCollection.

getCount()

Returns a count of the current DP_ObCollection members.

Method Signature

getCount()

Arguments

  • None

Return

Number. The current number of DP_ObCollection members.

getCreationDate()

Returns the date/time that the DP_ObCollection was instantiated.

Method Signature

getCreationDate()

Arguments

  • None

Return

DateTime

getKeys()

Returns an array of all the member key values.

Method Signature

getKeys()

Arguments

  • None

Return

Array. All of the member key values.

getMemberKeyName()

Returns the name of the property used as the unique key.

Method Signature

getMemberKeyName()

Arguments

  • None

Return

String. The Member key property name.

getMemberType()

Returns the type of the Member object (a reference to the object constructor).

Method Signature

getMemberType()

Arguments

  • None

Return

Javascript function reference. The constructor for the specified Member object.

isEmpty()

Determines if the DP_ObCollection is empty.

Method Signature

isEmpty()

Arguments

  • None

Return

Boolean. True if no members exist, false otherwise.

isMember()

Determines if the specified member is in the collection.

Method Signature

isMember()

Arguments

  • MemberKey: String, Required. The member key of the object to return.

Return

Boolean. True if the member exists in the DP_ObCollection, false if not.

isValidType()

Determines if the passed object is of the same type defined for the DP_ObCollection.

Method Signature

isValidType(Object)

Arguments

  • Object: Object, Required. A reference to an object.

Return

Boolean. True if the object is of the correct type for the DP_ObCollection, false if not.

Examples

Creating and Using a Collection

Let’s first create an instance of DP_ObCollection called “MyOptions”. Since we’re creating a collection of options we pass in the constructor for the Option class. We’ll use the “text” property of the Option class as our unique key.

	MyOptions = new DP_ObCollection("text", new Option().constructor);
	

Now we’ll create a few options and simultaneously add them to the collection using the add() method:

	MyOptions.add( new Option("Jim") );
	MyOptions.add( new Option("Carol") );
	MyOptions.add( new Option("Paxton") );
	MyOptions.add( new Option("Matilda") );
	MyOptions.add( new Option("Sandy") );
	MyOptions.add( new Option("Louise") );
	

Loop over the Collection and display the contents:

	for(var Cur in MyOptions.Members) {
		document.write("Current Option Text: " + Cur + "<br>");
	

Revision History

June 8, 2013

  • Initial GITHUB release.

August 22, 2005

  • Changed the name of the component to “DP_ObCollection”.
  • Cleaned up the method declaration procedure used in the object.

August 27, 2004

  • Fixed several bugs with typeless collections.
  • Reversed position of the contructor arguments to allow the “type” argument to be optional.

August 18, 2004

  • Added ability to have typeless collections.

July 26, 2004

  • Initial Release

1 Comment

Comments are closed.