Stop making sense

Don't you also need a good picture of the world around you to keep a firm grasp on things? I know I do. Sometimes people come to me with some claim and I go "that's impossible!" without even looking just because it does not fit Reality As I Know It(tm).

The same thing also goes for software like GX WebManager. It needs a good understanding of its components in order to do sane things. Let's take a look at my favourite type of WCB: the presentation WCB.

Here we have a bunch of resources that WebManager would love to be close with, especially the JSP files. So how does WebManager get to know them all?

First of all the contents of your beautiful WCB will be unpacked to specific directories. At regular intervals the directories containing JSPs are scanned for XML descriptor files. So WebManager builds its world image basically from two things:

• the presentation directories to scan
• the contents of the descriptor files

Presentation directories

The directories that WebManager scans for descriptor files can be set per website in the "General configuration" tab of the setup tool.

By default it is set as follows:

website_settings.presentation_jsps_url:

• /WEB-INF/project
• /WEB-INF/wm/jsp

It is important to know that the order of the directories matters; WebManager will scan the directories in the order they are entered. As a result, in the case of double entries (more on that later) the first descriptor file encountered "wins".

The directory "/WEB-INF/project" is a general one. If you are going to work with multiple presentations and multiple websites, you will probably want to insert a more specific directory above it, e.g.:

website_settings.presentation_jsps_url:

• /WEB-INF/project/site1
• /WEB-INF/project/shared
• /WEB-INF/project
• /WEB-INF/wm/jsp

This order will ensure that presentations in the "site1" directory take precedence over those in the "shared" directory, and they all take precedence over all other presentations.

Note: NEVER remove the "/WEB-INF/project" directory!

Why? The standard out-of-the-box design that WM comes with also resides in that directory. By removing the directory, it will no longer be found and the default WM presentations will no longer exist according to WebManager. Needless to say, this will cause all sorts of mischief on your website.

Descriptor files

Now that we learned how WebManager knows where to find files, it is time to look at those files themselves.

Let's start off by quoting the great Yoda: "Always two there are". JSP files always are paired with a XML descriptor file. They have exactly the same filename, except for the postfix. So "site1BigTextElement.jspf" comes with a "site1BigTextElement.xml" in the same directory.

Let's take a look at this "site1BigTextElement.xml" up close:

<presentation>
  <name>S1 BigTextElement</name>
  <display-name>Site1 Big Text</display-name>
  <scope>TextElement</scope>
</presentation>

This descriptor file contains the bare minimum of tags to make WebManager understand the "site1BigTextElement.jspf". The tags are:

• name: a unique identifier used for internal referencing by WebManager
• display-name: a pretty print name that editors will see in the presentation selection pulldown.
• scope: the place where this presentation will be used. This particular presentation is for the TextElement only.

Note that if the same name is used twice, the order of the directories in the website_settings comes into play. The presentation that is discovered first, will be used. The other presentation will be ignored. This can lead to strange and hard to debug behaviour, which is why you should always make sure you have a unique value for the name tag in your descriptor file. The first thing I always do after copying the XML file is changing the value of the name tag!

So there we have it; WebManager's grasp of the world of presentations laid out. It's all about the order of directories, the names in the descriptor files and the scope where they are valid.

Easy, huh? If only things would stop making sense.

Patrick