Simple WebSite Software

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:

Banner - an optional box across the top of the page. This is provided as a file containing a fragment of HTML.
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.
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.
Right hand menus - an optional set of links, similar to those on the left hand side.
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:

Just the tags <html> and </html>
Everything from <head> and through </head>
Everything from <title> and through </title>
Everything from <style> and through </style>
Just the tags <body> and </body>
All <meta> tag

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 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:

TITLE=string can be used to set 'string' to the title of the HTML document, i.e. in lieu of <title>/</title>.
FOOTER=htmlstring can be used to force the page footer (after the last </table>) to the string of HTML provided. Remember this must all appear on one line, but may contain any valid HTML. Do not include any </html> or </body> tags.
STYLE=htmlstring can be used to insert a <style> directive to be put in the HTML header. Whatever is provided is wrapped in <style>, so you probably want to code this like the example shown below.
KEYWORDS=meta_tag_words can be used to set META tags in your HTML. You may define more than one such line. If you don't know what this is about, you don't need it. SWS will extract the keywords and put them in the header of the document that is rendered. If you are viewing this document at the SWS Home Site, look at the source HTML rendered by your browser (probably control-U will show you this) and notice the META tags at the top.

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

<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 '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.
$HEADERLINES: defines a set of lines added to the <head> block of every page generated by SWS. This is a good place to put <meta> tags as well as Javascript (<script>) definitions.

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:

A # in column one is a comment and is ignored
Blank lines are ignored
BLOCK=name [SHOWONLY=name] [authlist] defines a block with a particular name. If SHOWONLY is provided, it identifies the name of a block that is to be displayed if the PHP variable $SHOWBLOCK matches 'name'. If this is not matched, the menu block is not displayed. SHOWONLY is optional. You may also specify a blank delimited list of authorized users in square brackets. If the user has logged in and his/her name is in the list, then this menu is shown, else it is not shown. If the name of the block is NOSHOW, the block name is not shown.
BLANKLINE in column one will insert a spacer line in a menu
Lines defining a block are lines of HTML beginning in column 1. They either define a single menu line or a block of HTML:
1. Complete HTML address directives, all on one line like:
     <a class=menus href="/somewhere">Words in Menu</a>
        or
     INDENT<a class=menus href="/somewhere">Words in Menu</a>
  See the variables $MENUITEMHTML and $MENUINDENTHTML in the local_config.php file for details on how these are formatted.
2. Several lines of HTML. The HTML opening directive starts on the first line beginning in column one. The same ending directive is found a subsequent line, again beginning in column one.

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 when $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 when $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> # If the user is logged in and is 'mike' or 'tonee', then show this menu 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>

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 the following. The function findfile is provided by SWS in common.php.

<?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:

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-2008) 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: 2008/01/24 16:21:09 $
$Revision: 1.6 $