|
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<BR>';
return;
}
+ userName + "'s email address is: " + member.userEmail
+ '<BR>';
+ '</BODY></HTML>';
} %%
Move
showproperties.tpl to your webx 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<BR>'; 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
+ '<BR>';
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<BR>';
return;
}
var propName = form.propName;
var propValue = form.propValue;
member[propName] = propValue;
+ userName + "'s " + propName + ' has been set to ' + member[propName]
+ '<BR>';
+ '</BODY></HTML>';
} %%
Move
setproperties.tpl to your webx 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 Web Crossing 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<BR>';
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] + '<BR>';
+ '</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?
Resources
Sysop
docs:
Recommended
book:
-
JavaScript - The Definitive Guide, 3rd 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!
Web
Crossing Tech Support Forum
Developer
Center
|
