SWS layout

Simple Website Software (SWS)

Simple Website Software (SWS) is my attempt to provide software to generate a reasonably modern looking web site while requiring a minimal amount of effort to set up, yet keeping the HTML pages independent so they can be easily editted and verified outside the web site.

SWS requires PHP version 4.1 or above and consists of only a small number of files. It uses cascading style sheets (CSS) to control the basic look and feel and has the basic layout, but not appearance) of that shown to the left. If you want a web site which has different components than those you see here, SWS is not for you.

There are only a few components to your basic SWS web page:

  1. Banner - an optional box across the top of the page. This is provided as a file containing a fragment of HTML.

  2. Left hand menus - a required set of links organized in one or more blocks. Each block has a title and consists of zero or more static links. This is provided as a file containing partial HTML address tags.

  3. Middle - is where the basic HTML you provide is shown. This is provided as a file which is often named similar to your PHP program.

  4. Right hand menus - an optional set of links, similar to those on the left hand side.

  5. Footer - generated HTML which shows a copyright and date for each page of HTML.

So what's a real SWS web site look like? You're looking at one example right here at SWS at SourceForge. Here are some other web sites to get ideas of what can be done using SWS:

SWS is available at SourceForge.

Interesting Features

SWS pages are rended quite fast by your PHP web server. There is no operating system dependency here - you may use a Unix (Linux) or Windows-based server. The only software requirement is that you have PHP available. You code each page in PHP, but the PHP is very simple and almost always looks the same. You don't need to be much of a PHP coder.

SWS requires no database to render it's pages.

Any authentication uses the normal web server mechanism (e.g. .htaccess files for Unix Apache).

Menus can be selectively displayed based on what section of the web site is being displayed. If one selects 'vacations', then you can show a menu of vacation links. Move elsewhere and the menu disappears.

Menus can be selectively displayed based on whether the user is authenticated ('logged in') or not. Different menu blocks can be shown to different people.

A utility program called showfilelist.php is provided to generate simple lists of links. This program reads a simple ASCII file and generates the HTML for you keep your interface very simple.

An entire SWS installation and setup consists of only a half dozen files, all centralized in one directory. Your basic HTML remains in HTML files so you can develope it and test it as you normally would. You only use a small PHP program to tie it all together so the pages have the correct look and feel. This keeps things easy for you to create and maintain your web site.

Files

An SWS web site is driven by small PHP programs which render the HTML you provide and add the banners and menus for the web site. Here's a typical PHP program. If this is named 'index.php', then it will display 'index.html' from the same directory. Note you must set $SWSDIR to specify where the SWS files are to be found. Most all your SWS pages consist of a file like this and the HTML you normally would show.

<?php $SWSDIR = "$_SERVER['DOCUMENT_ROOT']/sws"; // Where all my files are include_once "$SWSDIR/common.php"; session(); // Watch for authorization to expire // Display .html file with the same name as this file $title = 'This is My SWS Web Site'; do_page($title); ?>

HTML File Format

The HTML files your PHP programs will display need to have valid HTML directives in them. Many times a browser will ignore errors. Since your HTML is wrapped in a <table> directive by SWS routines, it is possible your pages can cause the browser to show you quite a mess. You should also remove the header and trailer lines of your HTML pages for the best results. Specifically you should remove the HTML enclosed between the following directives:

There are times when your HTML document header contains information you really want to control. SWS generates the headers and by the time your HTML file is read, the headers have already been sent. You can include some times of details specific to your HTML file as comments where SWS will pick the information out and put it in the headers.

Each of these appears as a single line of comment to HTML (e.g. <-- key=value -->.). The comment start (<--) must start in column one and must end on the same line (no wrapping or multi-line mode is supported). The following key=values are recognized:

For example, here's a fragment of an HTML file rendered by SWS:

<!-- KEYWORDS=battles colorado river --> <!-- KEYWORDS=white water rafting trip summer 1995 --> <!-- STYLE=@import url("mycss.css"); --> <!-- TITLE=Terry Gliedt Battles the Colorado River --> <h2 align="center">What'd You Do On Vacation, Terry ?</h2> <p align="center">Terry Gliedt Battles the Colorado River</p> etc.

Authentication

A convenient feature of SWS is to display differing menu blocks based on who is viewing your pages. Of course, in order for you to decide this, the user must first 'login' by visiting a protected web page where you get a prompt for a user and password. For instance, suppose a user visited the page a 'secret/login.php'. If you have provided a .htaccess file to control who can access this page, the user will be prompted for a userid and password. After the prompt the following PHP code might be invoked:

<?php $SWSDIR = "$_SERVER['DOCUMENT_ROOT']/sws"; // Where all my files are include_once "$SWSDIR/common.php"; session(1); // Actually creates session, sets expiration time Header("Location: /index.php"); // Go to start of web site ?>

In this case a PHP variable ($_SESSION[REMOTE_USER]) is set to the userid from the password prompt. This is remembered and available for other SWS PHP pages to use. A timeout value is also set, so you can configure your web site to require re-authentication after a certain number of seconds.

Similarly, code like the following can be used to 'logout' and lose the SWS authentication:

<?php $SWSDIR = "$_SERVER['DOCUMENT_ROOT']/sws"; // Where all my files are include_once "$SWSDIR/common.php"; // Force expiration of authenticated period session(); $_SESSION[SESSTIME] = 0; $_SESSION[REMOTE_USER] = ''; // Go to start of web site Header("Location: /index.php"); ?>

Optional Menus

Another convenient feature of SWS is to display differing menu blocks based on what the current "topic" is. This requires that your PHP code sets a global variable $SHOWBLOCK with some name (e.g. 'vacations'). In your menus you specify blocks which only are shown when the topic is 'vacations'. An example will help:

BLOCK=Professional Life <a class="menus" href="/resume/index.php">Resume</a> BLOCK=Vacations SHOWONLY=vacations <a class="menus" href="/vac/summer95.html">A Water Experience</a> BLOCK=Secret Vacations SHOWONLY=secretvac [tpg] <a class="menus" href="/vac/summer96.html">Another Water Experience</a> BLOCK=Odds and Ends <a class="menus" href="/personal/">Personal Details</a>

The second menu block shown above will appear as long as your PHP code does the following:

// Normal code as shown above and then this: $SHOWBLOCK = 'vacations'; // Force vacation menus to be seen do_page($title);

Installation and Setup

To set up a SWS site simply install the SWS files in a directory on your web site. In these examples I've assumed it to be in /sws in the web server DOCUMENT_ROOT. In this directory you will have these files of note:

banner.html (optional) bluetri.png (optional unless used) redtri.png (optional unless used) common.php (required) my.lhmenu.txt (define left hand menus) index.html (zero length file to avoid snooping) local_config.php (required) showfilelist.php (optional unless used) styleMINE.css (defines CSS details for site) TEST (optional directory of examples)

The sample configuration file should be copied with cp sws/TEST/local_config.php sws. Edit the file local_config.php with your favorite ASCII editor (not Word). The example provided is well commented, but you should remember this is PHP code you are providing. You must get the PHP code syntax correct. The following variables will be of most interest:

 
$SITENAME
name of your site - appears in default footer.
$LHMENUS
full path to a file which defines the left hand menus.
$RHMENUS
full path to a file which defines the right hand menus. This is optional.
$RHMENUS_IF_AUTH
controls whether SWS dislays the right hand menus if the user is authenticated.
$SITEJS
full path to where the CSS for this site is to be found.
$BANNERFILE
full path to a file which provides the HTML for the banner. This is optional.

Your menus are controlled by files you specify in the local_config.php file. A sample menu file can be copied with cp sws/TEST/TEST.lhmenu.txt sws/your-menu-filename. Edit the file with your favorite ASCII editor (not Word). The syntax of the file is shown below.

Defining Menu Blocks

Menus are defined in a simple ASCII file. One must first define a block and follow that with lines of HTML address directives for the links. Two files are supported, one for menus on the left side and optionally one on the right (see $LHMENUS and $RHMENUS in local_config.php). The rules for lines in the files are:

Here's an example that defines a number of blocks and shows all the combinations:

# Just shows 'Home' and a small graphic. No block name # This block begins and ends with a <p> directive in column one. BLOCK=NOSHOW <p class="tpgmenu"> <a href="/index.php" class="tpgmenu"> <img src="/graphics/tpg3yr.gif" hspace="5" vspace="5" border="0" width="33" height="51" align="right"/> Home<br>tpg </a> </p> # This is only shown then $SHOWBLOCK is set to 'vacations' # which should be done by the PHP scripts for the topic 'vacations' BLOCK=Vacations SHOWONLY=vacations <a class="menus" href="/vac/summer95.html">A Water Experience</a> <a class="menus" href="/vac/gc/" target=_blank>Grand Canyon</a> # This is only shown then $SHOWBLOCK is set to 'ourvac' # and will only be shown when 'you' and 'me' are logged in. BLOCK=Vacations SHOWONLY=ourvac [me you] <a class="menus" href="/vac/summer96.html">Another Experience</a> # These are simple one-line links, Notice the use of the class= # keyword. 'menus' is defined in the SWS .css file. # You'll want to use class to control the look of the links. BLOCK=Professional Life <a class="menus" href="/resume/index.php">Resume</a> <a class="menus" href="http://phpsws.sourceforge.net/" target="_blank">SWS Web Site</a> <a class="menus" href="/toolbox/linux.php">Linux</a> BLOCK=Personal Projects INDENT<a class="menus" href="/win/" target=_blank>Coping with Windows</a> INDENT<a class="menus" href="/ukdict/index.php">UK English for the American Novice</a> BLOCK=Private [mike tonee] <a class="menus" href="/secret/index.php">Password Box</a> <a class="menus" href="/secret/directions.html">Directions to Hideaway</a>
SWS layout

Configuring CSS

SWS makes extensive use of Cascading Style Sheets (CSS). This allows one to centralize all the attributes of the HTML tags to control the look of each. Want to use a different color scheme? Just change a few background colors in one file and it's done.

A sample CSS is provided in TEST/styleTEST.css. This intentionally generates a very ugly web page. The colors were chosen to contrast so you can identify exactly where each area defined in the CSS will show up. A better choice is to begin by copying the CSS for the SWS web site to your SWS directory: cp sws/web/sws/styleSWS.css sws/styleMINE.css using any name you choose. Be sure to set the name of $SITEJS in local_config.php.

Edit the CSS file and compare the colors in the screen image showing all the CSS fields above. Start changing things as you want. You'll notice there are a series of CSS classes which control various parts of each component of a page.

findfile()

The SWS code provides a simple way for you to create one PHP program which can read a variety of HTML files, avoiding the problem of creating separate PHP files for each HTML file. Your PHP program should be called with a parameter file=name which identifies a .html file in the same directory as your PHP program. For instance, if you create vacations/showme.php then calling it by

    showme.php?file=china

will cause showme.php to search for 'china.html' in the 'vacations' directory. For security reasons, you may not provide relative paths to other HTML files outside of vacations. The complete 'showme.php' program would look like:

<?php $SWSDIR = "$_SERVER['DOCUMENT_ROOT']/sws"; // Used globally include_once "$SWSDIR/common.php"; session(); // Watch for authorization to expire extract(isolate_parms( 'file')); // Get parms passed to me $html = findfile($file); // Get $file.HTML, maybe do_page('',$html); ?>

ShowFileList

The PHP program showfilelist.php generates simple lists of links. Yes, you can do this in HTML, but for some it's far easier to edit a simple ASCII file and avoid the chance of generating invalid HTML. Use this program if you find it useful or ignore it as suits you. You can invoke showfilelist.php with a simple URL likes this:

<a href="/sws/showfilelist.php?dir=mydocs&file=docs.txt">See docs</a>

The file to read is specified by the file= keyword on the invocation. A subdirectory relative to htdocs may be specified with a keyword 'dir='. The file must contain lines of keyword=value lines (one line only). The keyword pagetitle will set the HTML <title> directive. The keyword header will generate an HTML <h2> directive at the top of the page. Header is not optional.

The rest of the file consists of keywords describing lists, organized as sections. The keyword section will generate an HTML <h4> directive to start a section of the document. The keywords item and url provide information for an HTML list item and an address reference for a link. An example will make this all much more clear:

pagetitle=Software Documentation header=Select From These Documents section=<font color="red">Statistical Software</font> item=Allegro url=allegro/ item=ASPEX, nonparametric linkage analysis of sib pair data url=aspex/ section=<font color="red">Our Environment</font> item='Dot' file examples url=dotfiles/README.txt item=Machine List url=machines.txt item=Printers url=printers

which generates the following HTML (remember, the links exist only as examples):

Select From These Documents

Statistical Documentation

Our Environment

Advanced Topics

Changing Look Based on Who is Logged In

Sometimes you want to change the values of in the local_config.php file based on what user is logged in. This requires a little trickery since the variables in local_config.php are defined before the user name is defined. To get around this an override function is supported. In the local_config.php file, code a subroutine like the following and put the logic there you want:

/*--------------------------------------------------------------- # CONFIG_OVERRIDE - This code is called when the user is logged # in and allows one to change defaults from those # defined above. # # Parameters: # user - user we logged in as # # Returns: # nothing #---------------------------------------------------------------*/ function CONFIG_OVERRIDE($user) { global $SITEJS, $BLOCKNAMEHTML, $MENUITEMHTML; if ($user == 'janedoe') { $SITEJS = "/sws/style$user.css"; $BLOCKNAMEHTML = ''; $MENUITEMHTML = "<img src=\"/sws/redtri.png\" alt=\"arrow\"&/> "; } }

Show Data From a Different Name?

Sometimes the HTML you wish to show is not named the same as your PHP code. To deal with this case, just provide the HTML to do_page() directly. Note the call to findfile sets the variable $REVISIONDATE which is used in the footer. If it's not set, it is not used. In these cases your PHP code will look like this:

<?php $SWSDIR = "$_SERVER['DOCUMENT_ROOT']/sws"; // Used globally include_once "$SWSDIR/common.php"; session(); // Watch for authorization to expire $title = 'This is My SWS Web Site'; // Could also be set in HTML file $file = 'sample'; $html = findfile($file); // Get sample.html do_page($title, $html); ?>

Show Data From a Non-Standard File?

Sometimes the HTML you wish to show comes from a file that is not named .html or .htm. We handle these cases pretty much like that above:

<?php $SWSDIR = "$_SERVER['DOCUMENT_ROOT']/sws"; // Used globally include_once "$SWSDIR/common.php"; session(); // Watch for authorization to expire $title = 'This is My SWS Web Site'; $file = 'sample.public'; $lines = file($file); // Provide the HTML for center $html = implode('',$lines); $REVISIONDATE = "<br>Last Revision: " . date('M d, Y', filemtime($file)); do_page($title, $html); ?>

Use Symlinks to Avoid All Those PHP Files

On Unix systems you can use symbolic links so that one PHP file is read for many files. Consider this directory:

training> ls -l -rw-r--r-- 1 123284 tpg 81625 Aug 18 11:32 2002handbook.html lrwxr-xr-x 1 123284 tpg 9 Aug 18 11:30 2002handbook.php -> index.php -rw-r--r-- 1 123284 tpg 80348 Aug 18 11:31 2003handbook.html lrwxr-xr-x 1 123284 tpg 9 Aug 18 11:30 2003handbook.php -> index.php -rw-r--r-- 1 597297 tpg 10776 Aug 18 11:32 alumni.html lrwxr-xr-x 1 123284 tpg 9 Aug 18 11:30 alumni.php -> index.php -rw-r--r-- 1 123284 tpg 1048 Aug 18 11:31 application.html lrwxr-xr-x 1 123284 tpg 9 Aug 18 11:30 application.php -> index.php -rw-r--r-- 1 597297 tpg 8271 Aug 18 11:30 faculty.html lrwxr-xr-x 1 123284 tpg 9 Aug 18 11:30 faculty.php -> index.php lrwxr-xr-x 1 123284 tpg 13 Jul 12 10:25 index.html -> overview.html -rw-r--r-- 1 123284 tpg 360 Aug 18 11:29 index.php -rw-r--r-- 1 123284 tpg 3458 Aug 18 11:31 overview.html -rw-r--r-- 1 597297 tpg 1671 Aug 18 11:32 students.html lrwxr-xr-x 1 123284 tpg 9 Aug 18 11:30 students.php -> index.php

In this case there is really only one PHP file (index.php). All the other PHP files are simple symlinks to it. This sole PHP file is as simple as one can want:

<?php // One PHP file with symlinks works for all $SWSDIR = "$_SERVER['DOCUMENT_ROOT']/sws"; // Used globally include_once "$SWSDIR/common.php"; session(); // Watch for authorization to expire do_page(); ?>

Use One PHP Program to Show Various HTML Files

In this case we write a slightly more complex PHP program which supports a parameter file=name which specifies the name of an HTML file (no '/' allowed) to be read and displayed:

<?php /*################################################################# # Syntax: showme.php?file=tom #################################################################*/ $SWSDIR = "$_SERVER['DOCUMENT_ROOT']/sws"; // Used globally include_once "$SWSDIR/common.php"; session(); // Watch for authorization to expire extract(isolate_parms( 'file')); // Get 'file' parameter $html = findfile($file); // Get $file.HTML $title = 'Show some Page of HTML'; // Use this title do_page($title,$html); // or use <!-- TITLE in $file.HTML ?>

Of course you can use more elaborate PHP code to construct the page of HTML to show. I've only shown you a very simple and probably insecure example.

I Need a More Complex Footer

The default footer for a page is pretty simple. Based on values in the local_config.php file, it contains the name of the web site, a copyright statement and a contact Email address. If the variable REVISIONDATE was set, this will also show the date the file was last modified.

You might want a more elaborate footer or need it to vary based on the particular files being shown or who is viewing the document. All this can be programmed into your PHP program. Simply set the global variable $FOOTER and this will replace the SWS default as shown here:

<?php /*################################################################# # Syntax: showme.php?file=tom # Provide my own FOOTER #################################################################*/ $SWSDIR = "$_SERVER['DOCUMENT_ROOT']/sws"; // Used globally include_once "$SWSDIR/common.php"; session(); // Watch for authorization to expire extract(isolate_parms( 'file')); // Get 'file' parameter $html = findfile($file); // Get $file.HTML $FOOTER =<<<END <hr size="4" width="80%" noshade="noshade"> <p class="footer" align="center"> From <a href="index.php" class="footer"> <i>The Glied(t)s 1723-1993 and Poeppelmeiers 1804-1993</i></a> by <i>Donna Budzier</i>, Copyright (c)1993. <a href="index.php?file=copyright" class="footer">All rights reserved</a>. <br>Direct comments or questions to <a href="mailto:tpg@hps.com?subject=270" class="footer">tpg@hps.com</a> $REVISIONDATE</p> END; do_page('',$html); // Title found in HTML file ?>

Copyright

SWS is copyrighted by Terry Gliedt and the University of Michigan (2004) and is available as free software. Neither the author nor the University provides any warranty this code is useful for any purpose. You may redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; See http://www.gnu.org/copyleft/gpl.html.


Simple Website Software (SWS)
$RCSfile: index.html,v $
$Date: 2006/06/19 14:15:16 $
$Revision: 1.5 $