Web Crossing Server-side JavaScript

JavaScript and Web Crossing Objects

Web Crossing Objects
Viewing User Properties
Adding a User Property
Last Section
Troubleshooting
Resources

Web Crossing Objects

In the previous section, we learned how to use forms inside Web Crossing JavaScript (WCJS). In this section we will expand our use of JavaScript to include special objects, and their methods, which are unique to Web Crossing.

One of the huge advantages of WCJS is that the language is so thoroughly integrated with Web Crossing's database itself. You can create new objects and also take full advantage of built-in objects. These built-in objects, and their associated methods, are specified in the sysop online manual. This section will describe those objects and give some examples of their use to help you get started.

Object

Description

Stored Object

Stored objects are the primitive building blocks from which other objects are derived. They can hold any JavaScript primitive objects, as well as other stored objects.

Node Object

Node object are used to derive all the locations in Web Crossing: folders, discussions, messages, chat rooms and links. You can also derive new objects from the Node object and make use of all the methods associated with it.

Folder Object

Derived from the Node object, Folder objects have special methods for creating new folders and other special properties associated with folders.

Discussion Object

Derived from the Node object, Discussion objects also has a method for creating new discussions.

Message Object

Derived from the Node object, Message objects also have methods for creating new messages or adding a message to an existing thread (message tree).

Chat Object

Derived from the Node object, Chat objects have special methods for creating new chat rooms and other special properties associated with chat rooms.

Link Object
Derived from the Node object, Link objects have special methods for creating new links and other special properties associated with links.

User Object

Derived from the Node object, User objects have special methods for creating new users and many other special properties associated with users, including custom properties you can add to the database.

Site Object

The Site object contains special properties, such as the location of the Images directory, the URL base and others, including your own customized site properties.

Viewing User Properties

Let's examine how this all works with a simple example that looks up a user and displays the user's email address.

We will make use of the command syntax and form URL discussed in the previous section.

Create a file named showproperties.tpl and place the following JavaScript function in the file:

%% command showProperties () {+ '<HTML><BODY BGCOLOR="#FFFFFF">';
var userName = form.userName;
var member = User.lookup(userName);
if (!member) {
+ 'The user ' + userName + ' does not exist ';
return;
}
+ userName + "'s email address is: " + member.userEmail + ' ';
+ '</BODY></HTML>';
} %%

Move showproperties.tpl to your webxTemplates directory, make sure the file is included in your webx.tpl file. Then reset the Web Crossing file cache, all as described in the previous section.

We tested this function using the following URL:

http://webx.webxharbor.com/cgi-bin/webx?showproperties@@!userName=doug

When you test it, be sure to replace the URL part in red with your own domain and script name.

Since we do have a member here at Web Crossing Harbor with the user name of doug, Web Crossing returned the response page shown in figure 1.

Figure 1 - successful search response page

If I were to search for a user who did not exist, such as Hacker, then the response page shown in figure 2 is returned instead.

Figure 2 - an unsuccessful search response page

Let's examine the function part-by-part to see how it works:

%% command showProperties () {

We define showProperties as a command, rather than as a function, so we can call invoke it from a URL.

+ '<HTML><BODY BGCOLOR="#FFFFFF">';

Next we append an HTML tag and BODY tag to the response page, setting the default background color.

var userName = form.userName;

Here we receive the contents of the form field userName and store the name in a local variable, also called userName. (The names don't have to be the same, of course. But why bother making up a second name?)

var member = User.lookup(userName);

User.lookup is a User object property that returns the user object for the user name in parentheses.

Note: I emphasize again that what User.lookup returns is a user object - not just an ordinary character string or user ID. This object contains all the user's properties.

if (!member) { + 'The user ' + userName + ' does not exist '; return; }

If User.lookup fails to find a user with the specified user name, it returns a null value. This part checks to see if the returned value stored in member is a null value (!member) and if so, an appropriate error message is appended to the response page and the function is finished with the return statement.

+ userName + "'s email address is: " + member.userEmail + ' ';

If the function proceeds, it means an existing member was found. The built-in user property userEmail contains the user's email address. The user's name and email address are appended to the response page.

+ '</BODY></HTML>'; } %%

Finally, the closing BODY and HTML tags are appended to the response page and the function is completed.

Adding a User Property

In the same function, you can also easily add a customized user property. For example, suppose you wanted to add an age custom field to a user's object. You could modify the showProperties function and turn it into a setProperties function using JavaScript associative arrays to name the new property.

Let's try this. Create a new file called setproperties.tpl and put the following function inside the file.

%% command setProperties () {
+ '<HTML><BODY BGCOLOR="#FFFFFF">';
var userName = form.userName;
var member = User.lookup(userName);
if (!member) {
+ 'The user ' + userName + ' does not exist ';
return;
}
var propName = form.propName;
var propValue = form.propValue;
member[propName] = propValue;
+ userName + "'s " + propName + ' has been set to ' + member[propName] + ' ';
+ '</BODY></HTML>';
} %%

Move setproperties.tpl to your webxTemplates directory, include setproperties.tpl in your webx.tpl file and reset your Web Crossing file cache.

You can now add any new property you want to any user!

Here at WebX Harbor, for example, I entered the following URL (all on one line) to set the age property for user doug to a value of 43:

http://webx.webxharbor.com/cgi-bin/webx? setProperties@@!userName=doug&propName=age&propValue=43

Note that ampersands (&) are used to separate the different field names: userName, propName and propValue.

When you try this on your site, you will want to replace the URL part in red with your own domain and script name.

Entering this URL results in the response page in figure 3 being displayed.

Figure 3 - the setProperties response page

We have created a new custom property for the user and set its value!

Note: At this point, now that you have verified that your function works properly, you might consider creating an actual form to input the user name, property name and value in, as we did in the previous section.

Let's examine the function part-by-part to see how it works:

%% command setProperties () {
+ '<HTML><BODY BGCOLOR="#FFFFFF">';

First we define setProperties to be a command, as we did before, so that we can invoke it from a URL. We also append some standard HTML headers to the response page.

var userName = form.userName; var member = User.lookup(userName);

Next we assign the value of userName to a local variable and return the user's object, assigning it to the local variable member.

If (!member) { + 'The user ' + userName + ' does not exist ';
return;
}

If the user does not exist, we append an appropriate error message to the response page and immediately return from the function.

var propName = form.propName;
var propValue = form.propValue;

Now we are ready to set the custom property. The name of the property (age) is stored in the local variable propName and the value (43) is stored in the local variable propValue.

Member[propName] = propValue;

This is actually the statement that is key to making the whole function work. It is also something I personally find particularly cool - associative arrays. This is a basic feature of JavaScript and is supported by WCJS. What we want to accomplish is member.age=43. But the actual name of the property is stored in a variable. We cannot say member.propName = propValue because that would look like the property name itself was propName.

JavaScript provides the member[propName] syntax to get around this problem. What we are doing here is equivalent to having written member.age=propValue directly in the function body.

If the age property already exists, its value is overwritten. If the age property does not already exist, it is created.

Note: All JavaScript object properties are associative arrays. You can use that fact to loop through arrays and examine all the properties in an object. You can, for example, create a loop to check all of a user's properties without actually knowing ahead of time which properties a user has, or even how many properties a user has.

+ userName + "'s " + propName + ' has been set to ' + member[propName] + ' ';
+ '</BODY></HTML>';
} %%

Finally we just append a confirmation message to the response page.

Those of you out there who are of a skeptical nature may wonder if we really did create a new age property and set it properly. OK. I will prove it to you!

In the Control Panel > Look Up Users form you can specify a search by custom field and value, as shown in figure 4.

Figure 4 - searching for users by custom property and value

After entering age=43 and pressing the OK button, Web Crossing returns the result page shown in figure 5.

Figure 5 - the result page returned by the custom user lookup

As you can see, Web Crossing correctly found that user doug has his age property set to 43.

Next Section

In the final section we explore how to use the setUserProperties function to import a comma-delimited file of users and their property values.

Troubleshooting

I tried searching for a user with a first and last name, but it seemed that only the first name I entered was received by the showProperties function. How do I send form data with an embedded space in it?

You can use %20 instead of a space. For example, if you want to search for Taro Watanabe, you can use a URL like:

http://yourdomain.com/webx?showproperties@@!userName=Taro%20Watanabe

Resources

Sysop docs:

sysjs.htm

Recommended book:

JavaScript - The Definitive Guide, 4th Edition, David Flanagan, O'Reilly
This book really is the definitive guide. It is thorough, readable and answers all your questions about JavaScript. It is an indispensable resource for any serious JavaScript programmer. In fact, I won't even recommend any other books. Just get this one!

Developer Center

Object	Description
Stored Object	Stored objects are the primitive building blocks from which other objects are derived. They can hold any JavaScript primitive objects, as well as other stored objects.
Node Object	Node object are used to derive all the locations in Web Crossing: folders, discussions, messages, chat rooms and links. You can also derive new objects from the Node object and make use of all the methods associated with it.
Folder Object	Derived from the Node object, Folder objects have special methods for creating new folders and other special properties associated with folders.
Discussion Object	Derived from the Node object, Discussion objects also has a method for creating new discussions.
Message Object	Derived from the Node object, Message objects also have methods for creating new messages or adding a message to an existing thread (message tree).
Chat Object	Derived from the Node object, Chat objects have special methods for creating new chat rooms and other special properties associated with chat rooms.
Link Object	Derived from the Node object, Link objects have special methods for creating new links and other special properties associated with links.
User Object	Derived from the Node object, User objects have special methods for creating new users and many other special properties associated with users, including custom properties you can add to the database.
Site Object	The Site object contains special properties, such as the location of the Images directory, the URL base and others, including your own customized site properties.