DP_ObCollectionOrdered

Download | Usage | Constructor | Properties and Methods | Examples | Revision History

A DP_ObCollectionOrdered is used to manage multiple instances of a JavaScript object as a single logical unit where the order (“rank”) of the instances matter. Object instances stored in the collection are called “Members” of the collection. The DP_ObCollectionOrdered assumes the following:

  • The DP_ObCollectionOrdered maintains the order (rank) of it members.
  • Member rank begins at zero (just like JavaScript arrays).
  • Member rank is manageable through exposed methods.
  • Optionally all members of an DP_ObCollectionOrdered can be validated for type.
  • A property of the Member object(s) must contain a unique Key to be used as the identifier. If the collection allows multiple types to be added they must all share a common property for identification.

Use the simpler DP_ObCollection if your application does not require 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

back to top

The component is available from GitHub:

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

Usage

back to top

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_ObCollectionOrdered.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_ObCollectionOrdered objects as you would any other JavaScript object. For example:

var MyCollection = new DP_ObCollectionOrdered(...);

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

back to top

DP_ObCollectionOrdered()

The constructor. Used to create a new DP_ObCollectionOrdered instance.

Method Signature

new DP_ObCollectionOrdered(MemberKeyName, [MemberType])

Arguments

This method has two arguments:

  • MemberKeyName: String, Required. The object property to be used as the unique identifier for DP_ObCollectionOrdered members.
  • MemberType: Object Constructor reference, Optional. 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”).

Return

A reference to the new DP_ObCollectionOrdered instance.

Properties and Methods

back to top

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

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.

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_ObCollectionOrdered.

Method Signature

add(NewMember, [AllowOverwrite])

Arguments

This method has two arguments:

  • NewMember: Object. A reference to the object to be placed in the DP_ObCollectionOrdered.
  • 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).

demote()

Moves a member down in rank (increases its index). If the member is already the last in the collection no action will be taken. Ranks are numbered from zero.

Method Signature

demote(MemberKey | Object, [Steps])

Arguments

This method has three arguments:

  • MemberKey: String, Required. The member key of the object to promote.
  • Object: Object, Required. A reference to the object to demote.
  • Steps: Number, Optional (defaults to 1). The number of ranks to demote the object.

Return

Number. The new rank of the member.

demoteAt()

Moves the Member at the specified index down in rank (increases its index). If the member is already the last in the collection no action will be taken. Ranks are numbered from zero.

Method Signature

demoteAt(Rank, [Steps])

Arguments

This method has two arguments:

  • Rank: Number, Required. The rank of the member to demote.
  • Steps: Number, Optional (defaults to 1). The number of ranks to demote the object.

Return

Number. The new rank of the member.

drop()

Drops a member from the DP_ObCollectionOrdered.

Method Signature

drop(MemberKey)

Arguments

This method has one argument:

  • 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_ObCollectionOrdered.

Method Signature

dropAll() or clear()

Arguments

This method has no arguments.

Return

Boolean. True is the only return.

get()

Gets a specific member from the collection.

Method Signature

get(MemberKey)

Arguments

This method has one argument:

  • 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_ObCollectionOrdered.

Method Signature

getAll()

Arguments

This method has no arguments.

Return

Object. A reference to the Members array which itself contains references to all objects in the DP_ObCollectionOrdered.

getAt()

Returns the Member at the specified rank. Ranks are numbered from zero.

Method Signature

getAt(Rank)

Arguments

  • Rank: Number, Required. The rank of the object to return.

Return

Object. A reference to object at the specified rank.

getCount()

Returns a count of the current DP_ObCollectionOrdered members.

Method Signature

getCount()

Arguments

This method has no arguments.

Return

Number. The current number of DP_ObCollectionOrdered members.

getCreationDate()

Returns the date/time that the DP_ObCollectionOrdered was instantiated.

Method Signature

getCreationDate()

Arguments

This method has no arguments.

Return

DateTime

getKeys()

Returns an array of all the member key values.

Method Signature

getKeys()

Arguments

This method has no arguments.

Return

Array. All of the member key values.

getMemberKeyName()

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

Method Signature

getMemberKeyName()

Arguments

This method has no arguments.

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

This method has no arguments.

Return

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

getRank()

Returns the rank of the specified member. Ranks are numbered from zero.

Method Signature

getRank(MemberKey)

getRank(Object)

Arguments

This method has two arguments:

  • MemberKey: String, Required. The member key of the object to examine.
  • Object: Object, Required. A reference to the object to examine.

Return

Number. The rank of the object (or null if it doesn’t exist in the collection).

isEmpty()

Determines if the DP_ObCollectionOrdered is empty.

Method Signature

isEmpty()

Arguments

This method has no arguments.

Return

Boolean. True if no members exist, false otherwise.

isIndexInRange()

Checks to see if the passed integer is in range of the current collection. Ranks are numbered from zero.

Method Signature

isIndexInRange(Index)

Arguments

This method has one argument:

  • Index: Number, Required. The index to check.

Return

Boolean. True if the passed index is in range, false if not.

isMember()

Determines if the specified member is in the collection.

Method Signature

isMember()

Arguments

This method has one argument:

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

Return

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

isValidType()

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

Method Signature

isValidType(Object)

Arguments

This method has one argument:

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

Return

Boolean. True if the object is of the correct type or the collection can accept any type, false if not.

promote()

Moves a member up in rank (decreases its index). If the member is already the first in the collection no action will be taken. Ranks are numbered from zero.

Method Signature

promote(MemberKey | Object, [Steps])

Arguments

This method has three arguments:

  • MemberKey: String, Required. The member key of the object to promote.
  • Object: Object, Required. A reference to the object to promote.
  • Steps: Number, Optional (defaults to 1). The number of ranks to promote the object.

Return

Number. The new rank of the member.

promoteAt()

Moves the Member at the specified index up in rank (decreases its index). If the member is already the first in the collection no action will be taken. Ranks are numbered from zero.

Method Signature

promoteAt(Rank, [Steps])

Arguments

This method has two arguments:

  • Rank: Number, Required. The rank of the member to promote.
  • Steps: Number, Optional (defaults to 1). The number of ranks to promote the object.

Return

Number. The new rank of the member.

setRank()

Sets the rank of a member (removes it from one position and inserts in another). Ranks are numbered from zero.

Method Signature

setRank(MemberKey, NewRank)

setRank(Object, NewRank)

Arguments

This method has three arguments:

  • MemberKey: String, Required. The member key of the object to promote.
  • NewRank: Number, Required. The new rank of the specified member.
  • Object: Object, Required. A reference to the object to promote.

Return

Boolean. True if the setRank was successful, false if not (for example if the new rank was out of range).

setRankAt()

Sets the rank of the member at the specified index (Removes it from one position and inserts in another). Ranks are numbered from zero.

Method Signature

setRankAt(Rank, NewRank)

Arguments

This method has two arguments:

  • Rank: Number, Required. The numbered rank of the member to set.
  • NewRank: Number, Required. The new rank of the specified member.

Return

Boolean. True if the setRank was successful, false if not (for example if the new rank was out of range).

sort()

Sorts the collection using a developer-specified sorting function. The function specified should meet the requirements of the core JavaScript Arry.sort() function.

Method Signature

sort(OrderFunction)

Arguments

This method has one argument:

  • OrderFunction: Function, Required. The function to use for sorting the collection members. This function must meet the requirements of core JavaScript Array.sort() function.

Return

Boolean. True upon completion.

sortByProp()

Sorts the collection by a member property.

Method Signature

sortByProp(Property, SortType, SortOrder)

Arguments

This method has three arguments:

  • Property: String, Required. The member property to sort the collection by.
  • SortType: String, Required. Defaults to “Alpha”. Values can be “Numeric” (sort is numeric), “Alpha” (sort is alphabetic, all lowercase letters are sorted before all uppercase letters) or “AlphaNoCase” (sort is alphabetic regardless of letter case).
  • SortOrder: String, Required. Defaults to “Asc”. Values can be “Asc” (sort in ascending order) or “Desc” (sort in descending order).

Return

Boolean. True upon completion.

swap()

Exchanges (swaps) the ranks of two members. Ranks are numbered from zero.

Method Signature

swap(MemberKey1, MemberKey2)

Arguments

This method has two arguments:

  • MemberKey1: Number, Required. The MemberKey of the first member to swap.
  • MemberKey2: Number, Required. The MemberKey of the second member to swap.

Return

Boolean. True upon completion.

swapAt()

Exchanges (swaps) the ranks of the two members at the specified ranks. Ranks are numbered from zero.

Method Signature

swapAt(Rank1, Rank2)

Arguments

This method has two arguments:

  • Rank1: Number, Required. The numbered rank of the first member to swap.
  • Rank2: Number, Required. The numbered rank of the second member to swap.

Return

Boolean. True upon completion.

Examples

back to top

Examples of DP_ObCollectonOrdered (examples will open in a new window):

Revision History

back to top

June 8, 2013

  • Initial GITHUB release.

August 22, 2005

  • Changed the name of the component to “DP_ObCollectionOrdered”.
  • 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.

August 11, 2004

  • Added sort() and sortByProp() methods.

July 26, 2004

  • Initial Release

1 Comment

  1. Pingback: I’ve GitHubbed! GitHubbled? GitHubliered? | The DepressedPress

Comments are closed.