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:

Member Application Interface

Interests Application Interface

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 AttributeDescriptionField Size
IDThis 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
uNameThis 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
titleMember title eg Mr, Mrs. The title, first name, initials and surname are concatenated into one field on the contacts template called name.240
first_nameMember title. The title, first name, initials and surname are concatenated into one field on the contacts template called name.240
initialsMember title. The title, first name, initials and surname are concatenated into one field on the contacts template called name.240
surnameMember title. The title, first name, initials and surname are concatenated into one field on the contacts template called name.240
addr1Address line 1No maximum.
addr2Address line 2No maximum.
addr3Address line 3No maximum.
addr4Address line 4No maximum.
post_codePost codeNo maximum.
countryCountryNo maximum.
phoneMember's telephone number32
mobileMember's mobile telephone numberNo maximum.
phoneMember's fax number32
emailMember's e-mail address240
join_dateJoin DateNo maximum.
membership_classMember's class of membershipNo maximum.
keywordsList 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 AttributeDescriptionField Size
IDThis 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
uNameThis 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
nameThe short name of the interest. It would be commonly the main display name.240
descriptionThe 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.35
(loadtime : 29ms)