ZZZZZZ.com
>>>>>>>>
Web Crossing Message Boards Integration
A
ZZZZZZ®
SYSTEMS DESCRIPTION DOCUMENT
January
2001
ZZZZZZ.com
>>>>>>>>
Web Crossing Message Boards Integration
A
ZZZZZZ®
SYSTEMS DESCRIPTION DOCUMENT
January
2001
Definition of Message Board Terms
A Games.com User’s View of the Forums
Implementation
of the Forums In Blue Martini
Implementation
In Web Crossing
Your Local
Development Machine
Code
running on the Blue Martini Server
Code
Running on the Web Crossing Side
The Conversation between and Blue Martini and
Web Crossing
Achieving
the Games.com look and feel on a forum page
Keeping the Games.com session alive
The purpose of this document is to describe the integration of Web Crossing message boards into the Games.com web site. Included are a history of the design, a system overview, a technical discussion of the integration, a short section on customizing Web Crossing pages and suggestions for where to get additional information.
The Games.com forums are hosted by WEB X, on a WEB X message board server, owned and administered by WEB X and located in a WEB X server farm.
All links to the message board forums from Games.com web pages direct a user to the WEB X server, where the user stays until he or she clicks a non-forum related link back to the games.com site. The Games.com look and feel, consisting of the side navigation bar, the play games, my games and buy games tabs, the banner ad and side promotions, is obtained by the Web Crossing server with an http request back to the Blue Martini server. This request is made once for each user when they first click on a message boards link and start communicating with the WEBX system.
A different, better design, which was rejected due to time constraints, was to house each message board page on the Blue Martini server and reach across to the Web Crossing server for the message board content. A phase two is planned to do just this, as the following advantages will be realized:
Message Boards and
Forums are synonymous
Discussion or topic – A container for a set of messages. This is the smallest container in the container set, as it can contain no other containers.
Folder – A container
of discussions.
Forum – A container discussions and/or folders.
Games.com home
page User clicks the link to the forums, aka. The Community Main Page
The Community
Main Page Here the user clicks on a forum. This is a Blue Martini jsp. served by Games.com
|
As of Hard Launch, there are
5 forums represented by html links to the WEBX system
Each forum is a folder in the
assortment, assortments/games/Forums, except Games Guides which is in it’s own
assortment, assortments/games/GameGuideForums. Each folder has only 2 attributes
The same 5 forums exist in
the Web Crossing system. Each forum may
contain folders and or discussions (aka. topics), and each folder may contain
additional folders and discussions.
To download an evaluation copy of web crossing, which runs on Windows NT and does not expire, go to www.webcrossing.com. Currently Webx and Blue Martini are installed on the NT Workstation, cpu10. If you’re testing a change that involves Blue Martini changes to jsp or CIS and .tpl file changes, this is a good place to work, using a locally running copy of Blue Martini webconnect server running true, true, true.
To access the webx system, use the url: http://111.111.111.111/webx?
Note the ip of cpu10 is 111.111.111.111.
For an NT installation, by default, the software loads to c:\Program Files\webx, and everything of importance for a developer, all .tpl and log files, is in the webx directory.
For a unix/linux installation, everything of importance, all .tpl and log files, loads to /webx. When you ftp to the server, you just need to cd to webx and all you need is there in that directory.
The staging/development WEBX server is a linux machine, located in a Web Crossing Hosting center. We have ftp but no telnet access. Normally, you’d use this server to test the message boards from staging, xxxxxxx.games.com.
The production WEB X server is a linux machine, located in a Web Crossing Hosting center, to which we have ftp but no telnet access. It communicates with the Games.com production Blue Martini Server through port 80 on the production Games.com web servers. Note that Web Crossing people have upgraded the software on the WEB X Linux machine without notifying us and we have uncovered a bug (on Jan. 4, 2001) in one recent release.
Web Crossing templates are
text files with a .tpl extension containing procedural language code and HTML,
much like a java server page, except the code is either java script or Web Crossing
Template Language.
Webx templates are all
checked into BMV, under, content/webx/templates.
Template files containing production code are:
The following description
includes the names of all the .jsp files on the Blue Martini side and the
macros on the Web Crossing side, which are involved in the conversations. Note that I’ve simplified the story a bit on
the Web Crossing side, as some of the macros call other macros to get things
done, and most of those calls have been left out of this description.
Below, the same
conversation between Blue Martini and Web Crossing above, is described with the
actual Http requests and responses involved.
This example assumes a guest user who is interested in seeing the Arcade
Games forum. The first link the user
clicks could be in a sidebar or the well of the community_main.jsp.
Link to the Arcade Forum, from community_main.jsp or
community_navigation.jsp:
(The query string is webx
syntax :
the 14, after the webx?, is a Web Crossing command code ( see Webx
documentaion for command code details)
the @@ is 2 delimiters for a
Webx user session id, which is non-existent at this point
the /Arcade%20Forum is the
Webx location, (forum name), with the space encoded to %20
the ! delimits the beginning
of query string data – a Web Crossing syntax specification
after the ! is the
WebLogicSession id which is passed to Webx so the user can tracked while
bouncing back & forth between Blue Martini and Webx.
Webx pings Games.com for the Games.com userID:
http://111.111.111.111:9012/playgames/webx_ping.jsp?WebLogicSession
=OhWPthCnNKZNkyAvawFbzW2q5czFtdEzcxgO2j6W2hexoX22K2QgUheo4WN1av1l2pr6dU2IbcY3|-3150971451818161151/-790651797/5/7005/7005/7002/7002/-1
ping.jsp returns the string value indicating the user
is not logged in :
“webxNoUser”
Webx sends user to login.jsp (Note the return url equals the original link to the Arcade Forum
After login.jsp runs, webx_redirect.jsp sends user back to webx, Arcade Forum
Webx pings Games.com for the Games.com userID:
http://111.111.111.111:9012/playgames/webx_ping.jsp?WebLogicSession
=OhWPthCnNKZNkyAvawFbzW2q5czFtdEzcxgO2j6W2hexoX22K2QgUheo4WN1av1l2pr6dU2IbcY3|-3150971451818161151/-790651797/5/7005/7005/7002/7002/-1
ping.jsp returns the user name :
“bob”
Webx requests the Games.com look & feel HTML:
http://111.111.111.111:9012/playgames/webx_look_feel.jsp?
WebLogicSession=OhWPthCnNKZNkyAvawFbzW2q5czFtdEzcxgO2j6W2hexoX22K2QgUheo4WN1av1l2pr6dU2IbcY3|-3150971451818161151/-790651797/5/7005/7005/7002/7002/-1
webx_look_feel.jsp returns the HTML:
<html><head>…lots
of html here – looking much the Games.com Home page……..</html>
A macro in the webx architecture called authenticateFilter, is executed when a user hits the webx site. This macro exists in the auth.tpl file, which is then included in webx.tpl. It checks to see if the user is logged into the webx system. If not, webx gets the user’s userID from the Blue Martini server and logs the user in to webx automatically. If the user is a guest on the Blue Martini system, the user is redirected to the login.jsp on the Blue Martini server. If the user has never before visited the message boards, there will be no webx user yet created. When this is the case, the user is automatically created on the webx side and logged in. If the user name begins with a gg_, upon webx user creation, the user is placed in the “Game Guide” user group. Please read more about Game Guides in the security section of this document.
Webx has a built in concept of a banner and a footer, designed to make the look and feel of a message board page easily customizable. It turns out that for our games.com pages, the banner is all of the html from a Games.com page before the content well of a page and the footer is the html after the well.
To get the banner and footer html code, webx will look for a %% banner macro %% and or %% footer macro %% in the webx.tpl file. Our macros do http requests to the Blue Martini server and the games_look_feel.jsp, to get the html. (Actually the macros are in d:\Program Files\webcrossing\blue_martini.tpl which is included in webx.tpl).
The games_look_feel.jsp page serves up that html, with <banner></banner> tages around the banner html and <footer></footer> tags around the footer html. It is pretty much a copy of the home.jsp page, so the look & feel html will look like the home page, in that all the side navigation, ads, the store, everything except the content well will look like the home page.
The games_look_feel.jsp is checked into BMV, under templates\playgames.
Note that for simpler look and feel customizations, webx has 2 control panel fields, banner and footer where you can put html code, but then it’s static and would not pick up any changes which have been made to the Games.com site, so we use the 2 macros.
The request by webx for Games.com look & Feel HTML is coded in blue_martini.tpl, which is called by code in bannerfooter.tpl and looks like this:
There is a concept in web crossing of a top level folder, which is the root of all existing forums, like “c:\” in Windows or “/” in Unix. For our implementation, a template called toplevel.tpl has been customized to redirect to www.games.com/playgames/community_main.jsp so that when a user clicks on the link “Games.com Forums”, the request is served by the Blue Martini jsp page.
3 types of
users exist:
1.
sysop – Administers the
Message Boards from a systems point of view and may make look and feel changes.
2.
game guides
– May access forum monitoring tools and delete unruly users.
3.
regular
users – May participate in the forums.
Note that the Game Guide specifications are customizable and are subject to change, so check with the administrator for the current settings. If a user is a game guide, web crossing automatically includes the buttons that allow them the additional privileges, and the webx_look_feel.jsp page on the Blue Martini side adds a Game Guide Central link in the side navigation bar. The links for Game Guides to use to access the Game Guides forum are on the My Games and Game Guide Central pages.
The user id “sysop” needs to exist (reserved, so no users happen to choose it as a username) in the Blue Martini data base. This is the system administrator’s id for Web Crossing, and is hard coded in Web Crossing template(s) and cannot be changed in any web crossing installation. The reason our sysop user name in production is “operations” is that it’s not “really” the sysop user, but a super user given all sysop privileges. This user is referred to as sysop in this document.
The sysop user and password is in the Blue Martini data base, so the sysop admin can log on to www.games.com, go to any forum and will automatically see all the buttons enabling sysop privileges, including the link to the Sysop Controls page.
While a user is busy in the message boards, their Games.com
session is kept alive by a HTTP request from webx back to Blue Martini. Each time a user clicks on a link to a
forum, a macro called “ping” is called, which makes a request back to www.games.com/playgames/webx_ping.jsp,
with the user’s Web Logic session id in the query string. Webx_ping.jsp returns the user’s username
back and the Web Logic session is kept alive.
The decision to perform the “ping” when a forum name link is clicked was
made by consensus and it may become evident that the ping needs to be performed
more frequently, such as whenever a user clicks on any link in the message
board pages.
There are two places to make customizations:
1. Control panel options
The sysop user (an admin user with highest power) can go into the Control Panel admin tool and make numerous, but usually superficial customizations. These customization options include button image size changes, backgrounds, basic look & feel.
Also in this tool is user admin, system admin, a link to system documentation, etc.
2.
Code
All Web Crossing HTML pages are produced by code written in java script or wctl
(web crossing template language) and placed in the webx/webx.tpl file. Each 'out of the box' webx html page is produced by code (wctl), which resides in
the standard.tpl file. ( I think it’s
safe to say that all out of the box code is wctl, and js is a new option for
customizing this existing code base.
Maybe web crossing will migrate to js in the future for out of the box
code.) Each page is produced by a separate wctl macro. (Some of the html pages
are produced by code in the Web Crossing exe itself and therefore not
customizable, but very little of it is produced there. So far I’ve run into just a couple of admin
pages, so there’s no impact to regular users.)
To make a modification to a webx page, you need to find the macro which
produces the page, in the standard.tpl file, copy and paste it into webx.tpl,
and modify it there. Or, to keep more
organized, you can create a separate .tpl file for the customized macro and
include it in webx.tpl. That way,
webx.tpl is just a list of include statements.
After each change to a .tpl file, you need to go into the control panel
, (logged in as sysop), and click the "Reset file cache for HTML files and
webx.tpl templates" link, because the previous version of template code
would still be cached. (Note that if
you modify the code in standard.tpl directly, no change takes place, as that
code is for documentation and as a source of code for the customizer's starting
point.) When looking for the macro to
produce a particular html page, Webx looks in webx.tpl first, before using the default
“out of the box” code.
To find out which macro produces which page, look in the sysop documentation - Standard Templates and Command Codes section. There’s a “page to macro” cross reference table.
Also, you can view source of a page, find a string which may be fairly unique for that page, and search the standard.tpl file for the string - hopefully you'll land in the right macro. Or you can guess, because usually a macro is named for the page’s functionality, so if you’re modifying the page which a user uses to reply to a message, you might search for “macro reply*” in standard.tpl. (I have found this process to be a bit frustrating.)
All .tpl files are in the webx directory, and are also saved in BMV under Content/webcrossing/templates
Currently, in many of the customized .tpl files, are commented lines of code which write debug messages to files. As always, this is a good way to figure out what’s going on during processing, as are debug output statements right to the web pages themselves. Another technique is to write a java script function or wctl macro, place it in the webx.tpl or any .tpl included in webx.tpl, and just run that function or macro by logging on to webx with the url http://111.111.111.111/webx?59@sysop:sysoppw@!id=sysop
Then resetting the cache, and changing the url by changing the command code to your function or macro name, something like,
http://111.111.111.111/webx?myFunctionName@251.McIxatRCain^0@
Here the session id is left from the sysop login. You get the functions output on the screen. To tweak it, make your code change, go back to the browser, hit the back button, reset cache, and change the url again to re-test.
Commented out code remains in some .tpl files for possible future use, as learning tools or actual resurrection into a production change. Hope it may help.
Of course, as always, looking at and playing with code is what will get you the farthest.
Links in a Blue Martini page that point to the forums are built using a system property called games.environment, which is set in the start script, webconnectserver.bat.. Possible values are development, staging and production, and each property is set to the IP of the Web Crossing server that will work with that particular Blue Martini server. Currently, in code, each of these environments is set. If you’re going to develop on your own NT box, you’ll need to change the template.
Also, in init.tpl, there are 2 application level variables declared and assigned:
Init.tpl has commented lines of code for each IP address currently relevant, so you’ll get the idea. These two variables are used in a couple .tpl files for creating the proper urls so communication is between the machines that you’re developing with. It’s quite possible the site.IP and site.gamesIP are both your local machine, except the games IP will include port 1234.
A design change could be made where the Blue Martini links to Web Crossing contain the IP of the calling host, so that CIS would not need to be changed during development, which requires a stage to be able to run a local webconnect server in True, false, false mode.
Images for buttons are in webx/html/Images/b1. First find what image you want to change by right-clicking on it and viewing the properties, which includes its location and name. ftp the new image to the location. If the properties indicates a location other than webx/html/Images/b1, ftp the new image to the location shown in the properties box. Note you’ll have to reset your browser cache to see the update.
That’s it, now your change is in.
Note that this goes for init.tpl too, where you might think a server reboot would be necessary, as global variables are being assigned, but a simple resync does it.
This section shows how to add a forum to the Message Boards, probably the most common update, and requires no coding on the Web Crossing side.
In
the conference area, (not the Control Panel), Click Add Folder
Type
in the Name, eg. CD ROM & click Add Folder
Note: If the Forum name contains characters other than letters, the web crossing template, blue_martini.tpl, in the command findLocation, needs to be coded to accommodate them, as Blue Martini strips out some url encoded characters in the url pointing to the forum. The regular expression code below already exists in blue_martini.tpl to fix the problem for spaces, ‘&’ and ‘–‘ characters. It replaces the character with the url encoded value :
re = /\s/g;
str = str.replace( re, "%20" );
re = /&/g;
str = str.replace( re, "%26" );
re = /-/g;
str = str.replace( re, "%2D" );
Also, this line, also in the findLocation command needs to contain the character :
re = /\/[ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz&-0-9\s%]+(\/\d+)?/i;
This is a regular expression, and as you can see, it contains a lot right now, but not every possible character, so you may need to update this line too. When the CD-ROM Forum was added, the ‘-‘ after the characters ‘xyz&’ was added to accommodate the ‘-‘ in CD-ROM.
When the server crashes, you’ll usually get a page cannot be displayed message, but the server will restart and in a minute or two, the site may be working properly again. If any interesting behavior is encountered, have a look at the following logs:
Since we have no telnet id, ftp to the site, get the log files and review them on your own machine.
Note that the common.log file can be used as an audit trail for administrative changes. You’ll need to ftp the log to your local machine and view it there. To obtain a string to search for in the log, you might perform any functions in question on a development copy of webx, look at common.log there, after the change, see the line in the log that making the change produced, and use it for what to search on in the production log.
As of 12-20, this link will take you to Web Crossing site where you make support requests:
http://support.webcrossing.com/
The old way was to email, which I’ll leave documented.
Email Web Crossing at hosting@webcrossing.com if you need help.
Also, support@webcrossing.com is another option, though I’m not sure of the difference. If you have a general support question, as opposed to a system problem, use this one.
Web Crossing Hosting services has been updating the software on the production site without notifying us beforehand. We uncovered a bug (on Jan. 4, 2001) in one recent release. You can look at webx.log to see
which version and Build is running. The lines in the log look like this:
Mon Nov 20 08:04:47 2000 started webx-11.345.334.555 as pid=65435677
Mon Nov 20 08:04:47 2000 version Web Crossing(r) Unix-v4.0 built Oct 14 2000
The production site has not been stress tested, though the hosting service has been notified of our current traffic numbers, 12,000 concurrent sessions on the Games.com site.
Web crossing provides a wealth of information on their web site at www.webcrossing.com. Included are wctl and java script docs, code examples, discussion boards for administrators and developers, support discussions where you can post questions to webx support people and the webx user community. Regular expressions are used in the java script and you can find a java script regular expression reference at http://www.webreference.com/js/column5/.