This document describes the licensing terms for the Barrel software, how to install it, and how to configure and tune it to your needs once it is installed.
This is the "free" version of Barrel. It is copyright (c) 2003 Frank Carver, and licensed under the GNU Public License (GPL) version 2. If you wish to use the Barrel software, in whole or in part, in an application or situation incompatible with the GPL, we are willing to consider other, less-restrictive, licensing terms. Note, however, that there may be a charge for this option. Please contact us at barrel@efsol.com to discuss your needs.
The latest version of Barrel is available from the Barrel Project at Sourceforge.net. If you got this software or this document from another source, please check that you have the latest version.
If you are in a hurry, Barrel can be installed as quickly as you can copy a file!.
You will need a working Servlet Container or Application Server which implements at least version 2.3 of the Java Servlet API. Barrel has been tested on Resin 2, and Tomcat 4, and sticks to the specification, so it should work on all other compliant servers. Please let us know if you find a server it won't work on..
All you need to do is drop the file "barrel.war" into the "webapps" directory of your servlet container. Most smart containers should recognize the new application automatically, but you may need to restart the container if yours gets confused. Once the container has recognized, deployed and initialized the web application (which may take a few minutes), check that it works by viewing the "web control panel". To view the control panel, append barrel to the URL of your server. For example, if I have a server at http://tomcat.efsol.com/, I can access Barrel at http://tomcat.efsol.com/barrel, or if you have a server at http://localhost:8080/, you can access Barrel at http://localhost:8080/barrel. Now you can use the control panel to create, edit, preview and publish pages to your heart's content. See The Barrel User Guide for more details.
That was straightforward, wasn't it!
Warning! There is one thing to beware of if you run Barrel this way. Any changes you make or new pages you create will be stored in the "temporary directory" provided by the servlet container as part of the servlet specification. It's the only way to make an application work "out-of-the-box" like this, but it can be a little dangerous. The servlet API specification is vague about what should happen to the contents of this "temporary directory" if you reload or modify a web application. I can't control how your container behaves in this respect, and I'd hate to see a lot of hard work and information inadvertently lost if you upgrade or reinstall later. By all means run Barrel this way to check it out, and see how it works, but I strongly recommend that you configure your installed Barrel to use a different, more permanent, directory for your files before you use it "for real".
Barrel is extremely configurable. In fact, almost anything may be configured or customised, often in more than one way. Barrel may be configured or customised by altering values, styles, templates, or code:
Values and styles are the simplest to change, in most cases just requiring that you edit existing files. The great majority of common customisations can be done just with values and styles. To change the templates, it is necessary to "expand" the delivered "war" file, and edit files within the web application folder. If you change any templates you may need to re-start the web container to make sure it notices the changes. Source code for both the Barrel application and the libraries it uses are also available for download, so if you wish, you can alter and rebuild enything in the system.
If you can't create or edit the file /tmp/barrel.prp, or you are working on a multi-user system and feel that /tmp is not a secure enough location for configuration files, you will need to "expand" the web application as decribed later, and change where Barrel looks for its application properties.
One of the first "customizations" you should consider is where the page definitions are stored. Note that Barrel stores the definitions of the pages separately from the actual HTML pages served by the web server. This allows all the pages on a site to be automatically updated when you decide to change the style or layout of your pages. It is most important that you look after these page definitions and don't let them get accidentally deleted or overwritten and they represent the "content" of your web site.
Find or make a directory which is unlikely to be deleted or messed with by another user or another system process. Make sure that it is both readable and writable by the user your servlet container runs as, and that it is initially empty.
Add a line like the following to the barrel.prp file (substitute your chosen location):
After you re-start the servlet container, go to the control panel, then upload and publish some pages to make sure it works. Check that a file for each page has appeared in your chosen location. Note that page definition files typically have the extension ".tract".
Because Barrel stores the definitions of the pages separately from the actual HTML pages used by the web server, you need to "publish" a site to be able to access it over the web. By default, Barrel publishes pages to the "temporary directory" supplied by the servlet container, and provides a special servlet to show the styled pages. If you want to serve styled pages using a regular web server such as Apache, you need to tell Barrel where to put the pages
Add a line like the following to the barrel.prp file (substitute your chosen location):
Please be very careful with this configuration. When you use Barrel to publish pages, it will overwrite any files with similar names in the chosen directory. This includes automatically generating common files such as "index.html". Make sure you take a copy of all files from your chosen directory before you run Barrel and publish pages. After you re-start the servlet container, go to the control panel, then create and publish some pages to make sure it works. Check that a file for each page has appeared in your chosen location.
Barrel uses CSS for most styling of published pages. CSS is very powerful, and the basic HTML pages generated by Barrel are built with CSS in mind, so it is easy to completely change the look of a whole site by just changing a single file, without even re-publishing the pages.
The default CSS style definitions are contained in the file barrel_style.css, which is automatically placed with the published pages if not already present. Once the default styles have been published you are free to modify the file to alter the style of your pages. Bear in mind that if you do this, and you wish to make use of the "preview" facility, you will need to make sure your changed style definitions are also copied to the "preview" directory.
The following configuration and customization instructions assume you have an "expanded" installation of the Barrel web application "war" file. All files mentioned are relative to this expanded directory.
Almost all servlet containers expand each web application into its own directory when it is deployed. If your server doesn't automatically expand the deployed web application you will need to expand it yourself using something like "WinZip" or "jar". You should make sure that you expand the "war" to a subdirectory of a directory monitored by the server. Typically this will be the same "webapps" directory in which you placed the "war" file, so you could for example use jar xf Barrel.war Barrel.
Before you start modifying the expanded web application, you should remove the original "war" file from the webapps directory, to ensure you don't get any conflicts. This may require stopping the server.
Some servlet containers will automatically detect a change to web.xml or other files and reload the web application after your changes. For others you will need to restart the server.
I find it hard to imagine, but you may not want to offer an application called "Barrel" on your web site. If this is the case, you can call the application anything you like (within the limits of acceptable URL directory names).
If you wish to install more than one Barrel on your web site (for example, one for staff use, and one for customer use, or one for each of your product areas), you can't call both of them "Barrel". Follow the process described above in "to change the name of the application", but copy the directory rather than moving it. Remember to configure each Barrel instance to use a different directory for page storage, or things may get very confusing!
Using this technique will allow you to install as many Barrel's as you want.
The default page style of Barrel is functional but bland. You can easily change most features of the page style with CSS (as described above), but some things are so fundamental that you need to actually change the underlying HTML.
| Version 1.0.1 | 10 Aug 2003 | Frank Carver |