Description of the Brazil technology

Although Brazil is intended to be used for content aggregation and portal services, it may also be used for more traditional web site construction.

This site was built using Brazil Framework. In lay-men's terms, the host computer is running the Brazil project framework as a web server (you can download a copy here). The content is mostly HTML (and images), but includes some additional markup that is interpreted by the server instead of your browser.

This page will contain a tutorial explaining how the Brazil web framework is used to build this site. We have attempted to use various features of the Brazil system to explore some of the capabilities of the framework. Due to the nature of this site, only a small fraction of the Brazil features will be presented.

Until then, the following links contain the raw HTML (plus Brazil framework specific XML markup), along with the server configuration file we use. Together, the configuration and the XML marked-up HTML pages interact to provide the functionality that would require CGI scripts, Servlets, or their equivalent in other web service environments.

Main Server configuration file

The Brazil framework uses one or more ASCII file for its configuration, in a format compatible with a Java^tm Properties file. The files are concatenated together. This one is the primary configuration file.

The basic operation of the server, as defined in the configuration file, consists of four steps. The first step happens once, the others occur for each HTML page.

1. Setup and initialization.
2. Obtaining the content for the requested URL
3. Analyzing the content, and extracting it into its semantic elements.
4. Integrating the extracted elements into the site template, and delivering the result to the user.

Logging configuration file

Server configurations can be divided into several files, each of which represents a specific part of the configuration. This optional configuration file adds custom logging information to the existing server configuration.

Proxy configuration file

Some of the projects on this site already have content on the research portion of the www.sun.com site. Rather than forcing the content author to maintain two copies of such pages, one here and one on www.sun.com, each with a different look, this configuration file, if incorporated into the server, will dynamically fetch selected pages from www.sun.com, and reformat them into this site's look and feel.

When enabled, all content on this site with links to the relevant portions of www.sun.com are dynamically rewritten to change the links to point to a URL on this site, which will then fetch the content from www.sun.com, and deliver it with a look and feel that is consistent with this site.

If this configuration is not enabled, those same links are left alone, and clicking on them will send the browser directly to the relevant site on www.sun.com.

Primary XML page template

Unlike other systems, where page headers and footers are sourced into every page, this configuration defines a canonical page, or template, and each page's content is stuffed into it. This is the primary template that defines the look of every page.

Notice the page is a combination of ordinary HTML, along with additional tags that are interpreted by the server, and replaced with ordinary HTML.

In some places, the formatting and indentation of the template is a bit bazaar. This is due to tip-toeing around many differences in layout policy we've discovered while attempting to make this site look right on a wide variety of browsers and operating systems.

XML printing template

The look of any page can be changed simply by changing the template page that all the content is stuffed into. For printing, we switch to a simpler template -- no navigation bars -- to make the printed output look better.

Changing the site look is simply a matter of changing the site template.

Site customization form.

Minor changes to the site look are accomplished, not by changing the site template, but by modifying parts of it. This form alters the look of the main template by setting variables that alter the way in with the server interprets certain constructs in the main template.

As is typical in Brazil system implementations, the HTML form tag has no action attribute; the form is submitted back to the same URL it was retrieved from. This allows the form data and the form processing to be kept in the same place.

Custom navigation bar manipulation

Simple changes in the look or feel of the site can be realized using only the macro-like capabilities built into the server. Customizing the navigation bar requires a small amount of real programming. For that, we choose one of the several available server-side scripting languages supported by the Brazil framework, in this case, TCL. Notice the construct of the form:

      <server language=tcl> ... </server>
   

Rather than emmiting HTML using the "print" statements in our scripting language, we extract, compute, and provide variables into the server environment that are then interpreted using the XML constructs in the rest of the page.

Using this technique, we can separate the "logic" from the "look".

Common scripting procedures

Integrating the server-side scripting language in with the rest of the system requires a little "glue", that defines procedures in that language to access and modify the server's environment. This file contains that "glue" for TCL.

Putting it all together

The server is started with this script. On Unix systems, a native code library is required to allow the server to use a privilaged port (80), yet only run with ordinary user privilages for everything else.

Running the server then consists of choosing an appropriate Java VM, and the desired set of configuration files.

Brazil Developer's Documentation (javadoc format).

This link provides an on-line version of the Brazil Framework documentation. A more complete (and uptodate) version is available on the Brazil framework download site.