Whitebeam Membership Services Application Interfaces

Site Map

Home

Application Guide
	Quick Start
	PHP and ASP
	Writing Apps
	Applications
	Tutorials
		Replication
		Postgres Interface
		XML Processing
		Using XPath
		Binary Object
		Using HttpRequest
		SmtpRequest
		Session
		Meta Data
		Iterators
		Memb Services
		Page Look&feel
		Authentication+
		Questionnaires
		Message Groups
		Form Handling
	Samples
Reference
Community
Contact Whitebeam
To-Do
Download
Credits
Licence
Whitebeam Users

Whitebeam Membership Services Application Interfaces

Subject

This tutorial discusses the use of the Whitebeam's Membership Services Application Interfaces. The following topics are covered:

Interests Application Interface

Overview
Dependencies
Detailed Usage
Creating an Interest
Retrieving an Interest's details
Modify an Interest's details
Delete an interest from the database
List all Members in an Interest
List all Interests of a Member
Add and remove an Interest to a Member

Formal Definitions

Formal definitions for these application interfaces can be found here.

Member Application Interface - JavaScript Methods

Overview

This application interface encapsulates the concept of member management. Here, a set of javaScript functions have been created to form a foundation and framework upon which the concept of a 'member' can be managed. Functionality provided around this 'member' object involves creation, deletion, viewing and modification. Members can have keywords associated with them. Members can be searched for by keyword or name.

Dependences

These features are immediately available by including the file member.js. You must be aware that the file is included by specifying the code:


<rb:script src="member.js"/>

The following listing of code shows the call in-situe. Here, no functionality has been called - simply the 'Hello World!' message.


<html>
  <head>
    <rb:script src="member.js"/>
    <title>Member Management</title>
  </head>
  <body>
    <p>Hello World!</p>
  </body>
</html>

Detailed Usage

Once you have included the file member.js, you may immediately start to manage members. Below is a list of all the attributes of the member object. No attributes are mandatory. The size of each field is actually very flexible as the area used to store this information is the large contacts metafield. There are however some limitations on size as the metafield has not been used to store all the information; where necessary these limits have been defined in the table.

Member Attribute	Description	Field Size
ID	This is the unique number identifier for the member. This cannot be modified or set in any way - it is automatically generated by the system.	19
uName	This is the unique name for the member. This should be but does not need to be specified by the application; if omitted, one will be provided. If an attempt is made to duplicate a uName then an error code of -1 will be returned.	34
title	Member title eg Mr, Mrs. The title, first name, initials and surname are concatenated into one field on the contacts template called name.	240
first_name	Member title. The title, first name, initials and surname are concatenated into one field on the contacts template called name.	240
initials	Member title. The title, first name, initials and surname are concatenated into one field on the contacts template called name.	240
surname	Member title. The title, first name, initials and surname are concatenated into one field on the contacts template called name.	240
addr1	Address line 1	No maximum.
addr2	Address line 2	No maximum.
addr3	Address line 3	No maximum.
addr4	Address line 4	No maximum.
post_code	Post code	No maximum.
country	Country	No maximum.
phone	Member's telephone number	32
mobile	Member's mobile telephone number	No maximum.
phone	Member's fax number	32
email	Member's e-mail address	240
join_date	Join Date	No maximum.
membership_class	Member's class of membership	No maximum.
keywords	List of keywords associated with this member. This list must be comma-separated and only include alpha-numerics, numbers, spaces or dashes.	240

Creation of a member

As stated above, there is actually no need to provide any attributes when the member is created. The following code will return a value in the result variable which will be the new members ID:


var aMember= new Member();
var result = aMember.create();
if (result== -1){
   rb.page.write("<p>Error on creation</p>");
}
else {
   rb.page.write("<p>Congratulations member with id - "+result+" was created</p>")
}

However, it is most likely that you will be setting attributes on creation of the member. This can be achieved in two ways. The first way is to set the required attributes before the create method call. Here, the unique name, first_name and keyword attributes were first set:


var aMember= new Member();
aMember.uName = params.uName;
aMember.first_name = params.first_name;
aMember.keywords = params.keywords;
var result = aMember.create();
if (result== -1 && params.uName!=null){
  rb.page.write("<p>This user already exists please
				 enter a different name</p>");
}
else{
  rb.page.write("<p>Congratulations member with id - "+result+" was created</p>")
}

The alternative way to create the member with attributes would be to pass the parameters sent by the web page call:


<rb:script>
var params =rb.page.formdata();
var aMember= new Member(params);
var result = aMember.create();
if (result== -1){
  rb.page.write("<p>Error on creation</p>");
}
else{
  rb.page.write("<p>Congratulations member with id - "+result+" was created</p>")
}
</rb:script>

Here, the variable params is created holding an object representing all the calling parameters passed over to the web page being called. The list of parameter names must match the attribute names of the member object. The list does not need to cover every attribute, just the names you require. Finally, the parameter list can include other names which do not match the name of any member object attribute - these will be ignored by the creation function.

Viewing of Member Details.

To view a members details, you first need to have either their unique name (uName) or number (ID).There are two ways to get the members details:


var aMember= new Member();
aMember.uName = "MyUniqueName"
result = aMember.get();

The local variable aMember shown in this script can then be used in HTML calls to populate display widgets. The second way to get a members details is to utilize a simple piece of functionality which will implicitly find the details if given on the new Member call:


var memberatt = new Object;
memberatt.uName = params.uName;
var aMember= new Member(memberatt);

Here, the local variable memberatt has to be created so that it can pass the uName or ID to the new Member call. The call will get the presentation page to search the database and return a member whose details match the value given. This functionality is useful if you want to use the web page call parameters to find the members details:


<rb:script>
var params =rb.page.formdata();
var aMember= new Member(params);
</rb:script>

Modification of a Members Details

Naturally, members details can only be modified if that member has already been drawn from the database. To this end, a get method will have to be used before a save command is given.


<rb:script>
var aMember= new Member();
aMember.uName = "myUniqueName";
result = aMember.get();
aMember.first_name = "DifferentFirstName";
aMember.keywords = "DifferentKeywords";
var result = aMember.save();
if (result== -1){
  rb.page.write("<p>Error - failed to save changes</P>");
}
else{
  rb.page.write("<p>Congratulations modify worked</p>")
}
</rb:script>

The script above shows the get method retrieving the member from the database. The retrieved details are then passed into the local variable object aMember of type Member. This object then has its attributes set/modified. Finally, a save method call is made to update that member's details.

Removal of a Member

To remove a members, you again first need to have either a unique name (uName) or number (ID). Next, a get method call will need to be made (or the equivalent). Finally, a remove method call must be made to the retrieved Member object:


<rb:script>
var memberatt = new Object;;
memberatt.uName = params.uName;
var aMember= new Member(memberatt);
if (aMember.ID != null){
  result = aMember.remove();
}
</rb:script>

Here, a member's details have been retrieved from the database by use of uName. If a member has been found then the method remove is invoked. The value for result will be -1 if the removal failed, otherwise the ID of the member will be returned.

Retrieval of Members by Keyword Search

Once a member has been created, apart from the get method, members can be returned according to a keyword search. There are two areas that can be searched: Name and Keywords (you will be aware that the title, first_name, initials and surname are concatenated in to one field - this field represents the name field in which a search can take place). To carry out a search, an array of keywords needs to be created. Also, an object defining exactly where a search will take place will have to be created. These two objects are then passed to the search call to the Member class. Once the search call has been made, an iterator object will be returned containing the members whose details match the search. This iterator object can then be stepped through and each member detail presented as required on the web page (eg list box or report).

Creating the keyword array:


var  l_keyword = new Array;
l_keyword[0] = "fred";
l_keyword[1] = "john";

Creating the search flags:


var flags = new Object;
flags.searchDescription = true;
flags.searchName        = true;

Create the search iterator


var iterator = Member.get(l_keyword,flags);

Display the returned results


while (iterator.getNextRow()){
  i++;
  rb.page.write('<option value="'+iterator.uName+'">'
		+iterator.uName+'('+iterator.ID+')'+'</option>\n');
}

Interests Application Interface - JavaScript Methods

Overview

This application interface encapsulates the concept of interests management. Here, a set of javaScript functions have been created to extend the member framework above. Functionality provided around this 'interest' object involves creation, deletion, viewing and modification. Members can have interests associated with them. To this end, the interests can be added to or removed from a member. Additionally, all interests associated with a member can be retrieved. The core management functions of an interest are methods attached to an Interest object. The ability to add, remove or list a members interests is provided by extending the list of methods available from a Member object.

Dependences

The interest features are immediately available by including the files member.js and interest.js. They MUST be included in this order as the functionality contained within the interest.js file extends that previously provided by the member.js file. Note the way the functionality is called:


<rb:script src="member.js"/>
<rb:script src="interest.js"/>

The following listing of code shows the inclusion of the application interface libraries in-situe; at this stage no functionality has been called, simply the 'Hello World!' message displayed.


<html>
  <head>
    <rb:script src="member.js"/>
    <rb:script src="interest.js"/>
    <title>Interest Management</title>
  </head>
  <body>
    <p>Hello World!</p>
  </body>
</html>

Detailed Usage

Once you have included the files above, you may immediately start to manage interests. Below is a list of all the attributes of the interest object. No attributes are mandatory. If none are provided then a unique name for that interest will be auto generated. The size of each attribute field has been provided in the table.

Interest Attribute	Description	Field Size
ID	This is the unique number identifier for the interest. This cannot be modified or set in any way - it is automatically generated by the system.	19
uName	This is the unique name for the interest. This should be but does not need to be specified by the application as if omitted, one will be provided by the system. If an attempt is made to duplicate a uName then an error (-1) will be returned. Once created, this value cannot be altered.	34
name	The short name of the interest. It would be commonly the main display name.	240
description	The long name of the interest.	240

Creation of an Interest

As stated above, there is actually no need to provide any attributes when the interest is created. Using the create() method, the following code will return a value in the result variable which will be the new interest ID:


var aInterest= new Interest();
var result = aInterest.create();
if (result== -1){
  rb.page.write("<p>Error on creation of interest</p>");
}
else{
  rb.page.write("<p>Congratulations a interest with id - "+result+" was created</p>")
}

However, it is most likely that you will be setting attributes on creation of the interest. This can be achieved in two ways. The first way is to set the required attributes before the create() method call. Here, the unique name, name and description are first set:


var aInterest= new Interest();
aInterest.uName = params.uName;
aInterest.name = params.name;
aInterest.description = params.description;
var result = aInterest.create();
if (result== -1){
  rb.page.write("<p>This interests unique name already 
			exists please enter a different name</p>");
}
else{
  rb.page.write("<p>Congratulations an interest with id - "+result+" was created</p>")
}

The alternative way to create the Interest with attributes would be to pass the parameters sent by the web page call:


<rb:script>
var params =rb.page.formdata();
var aInterest= new Interest(params);
var result = aInterest.create();
if (result== -1){
  rb.page.write("<p>Error creating the interest</p>");
}
else{
  rb.page.write("<p>Congratulations an interest with id - "+result+" was created</p>")
}
</rb:script>

Here, the variable params is created holding an object representing all the calling parameters passed over to the web page. The list of parameter names must match the attribute names of the interest object. The list does not need to cover every attribute, just the ones you require set. The parameter list can include other names which do not match the name of any interest object attribute - these will be ignored by the creation function.

Viewing of Interest Details.

To view an interests details, you first need to have either its unique name (uName) or number (ID).There are two ways to get the details - the first way uses the get() method:


var aInterest= new Interest();
aInterest.uName = "MyUniqueName"
result = aInterest.get();

The local variable aInterest shown in this script can then be used in HTML calls to populate display widgets. The second way to get an interest's details is to utilize a simple piece of functionality which will implicitly find the details without the get() method:


var interestatt = new Object;
interestatt.uName = params.uName;
var aInterest= new Interest(interestatt);

Here, the local variable interestatt has to be created so that it can pass the uName or ID to the new Interest call. The call will get the presentation page to search the database and return an interest whose details match the value given. This functionality is useful if you want to use the web page call parameters to find the interest details:


<rb:script>
var params =rb.page.formdata();
var aInterest= new Interest(params);
</rb:script>

Modification of an Interest's Details

Naturally, interests details can only be modified if that interest has already been drawn from the database. To this end, a get() method will have to be used before a save() command is given.


<rb:script>
var aInterest= new Interest();
aInterest.uName = "myUniqueName";
result = aInterest.get();
aInterest.name = "DifferentName";
aInterest.description = "DifferentDescription"
var result = aInterest();
if (result== -1){
  rb.page.write("<p>Error - failed to save changes</p");
}
else{
  rb.page.write("<p>Congratulations modify worked</p>")
}
</rb:script>

The script above shows the get method retrieving the interest from the database. The retrieved details are then passed into the local variable object aInterest of type Interest. This object then has its attributes set/modified. Finally, a save() method call is made to update that interest's details.

Removal of an Interest Details

To remove an interest, you again first need to have either a unique name (uName) or number (ID). Next, a get method call will need to be made (or the equivalent). Finally, a remove() method call must be made to the retrieved Interest object:


<rb:script>
var interestatt = new Object;
interestatt.uName = params.uName;

var aInterest= new Interest(interestatt);
if (aInterest.ID != null){
  result = aInterest.remove();
}
</rb:script>

Here, an interest has been retrieved from the database by use of uName. If an interest has been found then the method remove() is invoked. The value for result will be -1 if the removal failed, otherwise the ID of the interest will be returned.

Retrieval of Interests by Keyword Search

Once an interest has been created, apart from the get method, interests can be returned according to a keyword search. There are two areas that can be searched: Name and description. To carry out a search, an array of keywords needs to be created. Also, an object defining exactly where a search will take place will have to be created. These two objects are then passed to the search() call to the Interest class. Once the search call has been made, an iterator object will be returned containing the interests whose details match the search. This iterator object can then be stepped through and each interest detail presented as required on the web page (eg list box or report).

Creating the keyword array:


var  l_keyword = new Array;
l_keyword[0] = "%"; //the % sign here represents all values

Creating the search flags:


var flags = new Object;
flags.searchDescription = true;
flags.searchName        = true;

Create the search iterator


var iterator = Interest.search(l_keyword,flags);

Display the returned results


while (iterator.getNextRow()){
  i++;
  rb.page.write('<option value="'+iterator.uName+'">'
	+iterator.uName+'('+iterator.ID+')'+'</option>\n');
}

Retrieval of Members by Interest Search

Once members have been linked to interests, members can be listed according to interest. The method call (findMembers()) which carries out this action requires a list of interests and a logic switch. The switch will stipulate whether the member should be attached to all or any of the interests in the list provided. The list of members returned, as above, will be a Whitebeam iterator which can then be stepped through to create the web page's display.

Creating the keyword array:


var interestArray = new Array;
interestArray[0] = "myInterest";
var inAll = true;

Create the search iterator


var iterator = Interest.findMembers(interestArray,inAll);

Display the returned results


while (iterator.getNextRow()){
  i++;
  rb.page.write('<option value="'+iterator.uName+'">'
	+iterator.uName+'('+iterator.ID+')'+'</option>\n');
}

Enhancements to the Member Class

The inclusion of the interest.js file will not only provide an Interest object, but also extend the Member object. This extension will allow interests to be added to and removed from a member. Additionally, a member's interests can be listed as required. The syntax for these additional methods is as follows:

List All Member Interests

The method getInterests() will return an array of interest IDs which are linked to a member. This array can then be used to create a web page display:


<rb:script>
if (aMember.ID !=null){
 var memberInterests = aMember.getInterests();
 var allInterests = Interest.get();
 while (allInterests.getNextRow()) {
       rb.page.write('<input type="checkbox" name="'+allInterests.ID+'" value="yes"');
       if (memberInterests[allInterests.ID]!=null){
           rb.page.write(' checked');
	 }
       rb.page.write('>&nbsp'+allInterests.name+'<br>\n');
  }
}
</rb:script>

Here, a member has already been 'pulled' from the database. All the member's interests are then obtained var memberInterests = aMember.getInterests() followed by all available interests on the database var allInterests = Interest.get(). Iterating through all the database interests, a checkbox is created and checked if the ID matches that in the member's list of interests.

Add and Remove an Interest from a Member

The methods addInterest() and removeInterest() simply need to be supplied with an interest group ID. Naturally, the member object to which the method is called will first need to be called back from the database. If either add or remove methods fails then a result of -1 will be returned, otherwise the member ID will be returned.


//Add an Interest

<rb:script>
var memberatt = new Object;
memberatt.uName = params.uName;
var aMember= new Member(memberatt);
var result = aMember.addInterest(params.ID);
</rb:script>

//Delete an Interest

<rb:script>
var memberatt = new Object;
memberatt.uName = params.uName;
var aMember= new Member(memberatt);
var result = aMember.remInterest(params.ID);
</rb:script>

Whitebeam release 1.3.36

View XML source of this page

(loadtime : 8ms)

Whitebeam Membership Services Application Interfaces

Subject

Member Application Interface

Interests Application Interface

Formal Definitions

Member Application Interface - JavaScript Methods

Overview

Dependences

<rb:script src="member.js"/>

Detailed Usage

Creation of a member

Viewing of Member Details.

Modification of a Members Details

Removal of a Member

Retrieval of Members by Keyword Search

Interests Application Interface - JavaScript Methods

Overview

Dependences

<rb:script src="member.js"/><rb:script src="interest.js"/>

Detailed Usage

Creation of an Interest

Viewing of Interest Details.

Modification of an Interest's Details

Removal of an Interest Details

Retrieval of Interests by Keyword Search

Retrieval of Members by Interest Search

Enhancements to the Member Class

List All Member Interests

Add and Remove an Interest from a Member

<rb:script src="member.js"/>
<rb:script src="interest.js"/>