Passing Variables to Commands

One of the beauties of working with WebCrossing is that it handles a lot of the backend integration for you. One of those is the ability to pass "command line" or URL parameters to any scripting method that you create in either WCTL or SSJS. In order to continue with the authentication series, we must first give a quick lesson on how to pass information through URL's into your methods.

WebCrossing URL structure is varied due to some legacy issues in the code. I will start with the older methods of sending information into the methods and move up from there. The Original URL structure is like this:

http://yoursite.com/webx?CC@xxxxx@location!key1=val1&key2=val2

The CC is the command code or the name of your macro/command that you create in the scripting files.
The xxxxxx is the "certificate" which lets WebCrossing track users across various pages without the need for cookies.
location is a unique ID of some "node" in the database which corresponds usually to a folder, discussion, or message.
The key1=val1 are & separated key value pairs of information that your macro/command can read and use for whatever you want.

The key value pairs are separated from the rest of the URL by the use of an exclamation point ( ! ).

Lets say that you wanted to display your own simple calendar and wanted your URL structure to have the month and year passed into the calendar so that a specific month/year can be displayed to the user. Your URL might be something like this:

http://yoursite.com/webx?my_cal@@!month=1&year=2011

This would mean that 2 variables would be available in the macro "my_cal". Your macro then might look like this to process these types of URL's in WCTL:

%% macro my_cal %%
%% set month form.month %%
%% set year form.year %%
%% // use month and year to display a calendar %%
%% //… left as an exercise for the reader :-) %%
%% endmacro %%

The key value pairs are passed in through an object called "form" where the dotted property is the same as the key in the URL. These are all strings when coming into your macro, so appropriate conversions may be necessary. These values are also URL encoded, so it may also be necessary to decode them to convert %20's to spaces, etc.

This same snippet of code to process the key value pairs in SSJS would look like this:

%% command my_cal(){
month = form.month - 0;
year = form.year - 0;
// use month and year to display a calendar
// etc.

} %%

You might ask why I subtracted 0 from the form.* variables. In normal Javascript, if you subtract a 0 from a string, then it will convert the value of the string into an integer type without modifying what the value was. For instance, if form.month held the string "11", then subtracting a 0 from that would convert that value into the numeric value 11 so that subsequent calculations could be done on the number.

The "New" URL structure
One of the more recent URL structures in WebCrossing allows a more SEO friendly representation of the commands and locations. This structure is laid out like this:

webx/location/macroOrCmd/cert.certificate/name.value[/name.value.. .]

The example URL above would be represented by this:

http://yoursite.com/webx/my_cal/month.1/year.2011

Note that the certificate can be eliminated completely as long as cookies are available to track the user session instead. This query-string-less version of the WebCrossing URL is much more friendly to search engines and humans alike.

Now that you know a little about the URL structure and passing information to your macros that you write, we can continue along with the authentication filters.
Dave Jones
dave@lockersoft.com
http://www.youtube.com/lockersoft

Authentication Filters - Part 1

One of the amazingly flexible concepts that WebCrossing does well is integrating into existing login/authentication systems. Because of this flexibility, it can also be a bit daunting to try and figure out how to do this with an existing single-sign-on solution that your website already has.

I will attempt to show many different ways that WebCrossing can integrate into these existing login systems by showing the ins and outs of what we call the "Authentication Filter".

HTTP - Stateless and Ignorant
First of all, the HTTP web protocol is a "stateless" protocol, meaning that each request of a web page or resource is completed and usually the connection is closed leaving the server to wait for another request. A simple web page makes many TCP/IP requests in the course of displaying the various pieces of a web page such as external CSS files, images, Javascript files, etc.

Since the protocol is stateless, there is no way for the web server to know who is asking for new information across these pages. Therefore, something must happen on the client side (browser) which identifies the user back to the server so that "state" of the user can be maintained across these page requests.

The browser can help with this in many ways including:

1. Cookies
2. Additional URL information
3. HTML Header information
4. HTTP Environmental Variables
5. Basic Authentication

WebCrossing can integrate with any of these methods so that the user credentials can be transmitted across each page so that the perception of a user being "logged in" can be maintained.

Authentication filters are the basis for most of these login integration systems and I will start with one of the easiest, written in WCTL. This auth filter will log in ANYONE as the sysop of the site. This is obviously not practical in production, but is an easy way to bypass the sysop password on a database if perhaps the password is lost, etc.

The code for this is as follows:

%% macro authenticateFilter %%
%%   userLookup( "sysop" ) %%
%% endmacro %%

This is an obviously dangerous filter to put into place because anyone that comes to the site will be logged in as the sysop, but it serves to illustrate some points.

One of the values that are "returned" from a filter is the User ID of someone in the WebCrossing database. the "userLookup" function returns this value after finding them in the DB and then that value is "printed" to the output buffer, so the result of executing this function is to return the userID of the sysop. This then logs in the person specified by the userID.

The authentication filter is executed for EVERY SINGLE web request made to the server, so we try and make it as simple and as fast as possible.

There are LOTS more uses of authentication filters and different ways to write them, so I will continue this in future blogs on this subject.
Dave Jones
dave@lockersoft.com
http://www.youtube.com/lockersoft