NST WUI

Overview

Directory Layout

The following lists the major directories a developer should be aware of when working with the NST WUI source code:

config/

Common configuration directory (several @macros() are defined here).

wui/

Root directory of the NST WUI (where you run: make).

wui/cgi-bin

Root directory of CGI source files (bash scripts) making up the NST WUI.

wui/php

Root directory of PHP source files making up the NST WUI.

include/skins/default/images

Common (shared) image files.

wui/images

Image files unique to the NST WUI.

include/skins/default/css

Common (shared) CSS files.

wui/css

CSS files unique to the NST WUI.

include/javascript

Repository of JavaScript files.

include/atmacros

Formal definition of @macros().

html/include/at

HTML @macros() (loaded and then "tweaked" by NST WUI specific adjustments ).

wui/include/at

NST WUI specific adjustments to @macros().

src/include/functions

Collection of bash functions which will be installed to: "/nstwui/cgi-bin/include" when building the NST WUI.

Coding Tips

Referencing CSS and Image Files

Use the @imageDirUrl() and @cssDirUrl() when referencing image and CSS files. For example:

@p("See the image: @link("@imageDirUrl()/new_users.gif") or
the CSS file: @link("@cssDirUrl()/site.css").")

Implementing AJAX Style Features

As we venture into AJAX (shorthand for Asynchronous JavaScript and XML, is a web development technique for creating interactive web applications.), we will be creating server side scripts which generate small XML output which client side JavaScript can easily request, parse and process. Currently, we are leaning to the simple Java properties model. In this model, there are many property values each associated with a unique key. Using this model has the following advantages:

• There is already a well defined DTD for these types of XML documents.
• It is simple to implement.
• It is fairly simple to write the client side (mapping keys to HTML page id attributes).

Example Server Side XML Output

Since we are following the DTD specified by the java.util.Properties class, the XML files generated on the server side will have the following form:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<!-- Might add a default style sheet for formatted viewing of CGI output -->

<properties>

  <comment>System Information</comment>

  <entry key="arch">i386</entry>
  <entry key="kernel">2.6.18-2857.fc5</entry>

</properties>

Example Server Side Source

In order to generate the properly formatted output, we will define a set of @macros. This should allow us to write CGI scripts in the following form:

@xmlPropertiesBegin("System Information","bash","true")

  @xmlProperty("arch","uname -m | xml_escape")
  @xmlProperty("system","uname -r | xml_escape")

@xmlPropertiesEnd()

The three macros shown above are fairly self explanatory. The second parameter to the @xmlPropertiesBegin() macro is used to indicate what scripting language will be used on the server. The third parameter to the @xmlPropertiesBegin() macro is used to indicate whether you want the standard set of properties included (system load, system time, etc - we haven't decided what these are yet).

Related Files

include/atmacros/ajax-server.xml

The server side @macros() shown above are defined in this file.

wui/javascript/ajax.js

A set of JavaScript functions to aid in the parsing and processing of XML documents.

wui/cgi-bin/networking/ifmon-ajax.cgi

A CGI script which returns a minimalistic XML document containing status for a particular interface.

wui/cgi-bin/networking/ifmon.cgi

A AJAX page which the user can use to select a network interface to monitor the status of (makes use of: ifmon-ajax.cgi).

wui/cgi-bin/include/form.sh

One can find the definition of the bash function: "xml_escape()" here.

Related Links

The following links are useful when working with AJAX:

• The XMLHttpRequest Object (W3C)

• XMLHttpRequest Info At WikiPedia

• XMLHttpRequest Info at W3 Schools

JavaScript

Using JavaScript unescape

It can be tough to generate valid JavaScript code within HTML output from the server side using PHP, bash, xsl, etc.

For example, consider the case where we need to pass the string: Hello: '<b>World</b>' to the function: domTT_activate() on a mouse over event. The above gives an example of the invalid code which one might first come up with:

<a href="index.php"
      onmouseover="domTT_activate(this, event, 'content', 'Hello: '<b>World</b>'');">
  Hello
</a>

There following problems are evident:

• The "<" and ">" symbols need to be replaced with their HTML escape sequence.

• The single quote characters within the JavaScript string need to be JavaScript escaped (replace: "'" with: "\'").

• Had the string not been static, it becomes very difficult to insert the proper escape sequences.

This "escaping" is tedious work and very error prone. In this situation, we can greatly simplify our lives by making use of the JavaScript unescape() function provided with have a JavaScript escape() function on the server side. The following shows a PHP fragment of code which uses the rawurlencode() PHP function to generated the JavaScript escaped string:

$title = rawurlencode("Hello: '<b>World</b>'");

// $title now contains: "Hello%3A%20%27%3Cb%3EWorld%3C%2Fb%3E%27"
// ALL of the troublesome characters have been replaced by a harmless percent sequence.
// the following will now generate valid HTML and produce the desired results.

echo <<<EOD
<a href="index.php"
      onmouseover="domTT_activate(this, event, 'content', unescape('{$title}'));">
  Hello
</a>
<<<EOD;