Richy´s Site Map Documentation

Index

Introduction

Richy´s Site Map is a set of files to display and work with a site map of your web site, comprising of PHP 4 scripts and template files with the CSS and HTML code, while the data of the site map is kept in a MySQL database. All configuration/administration is web-based. To run, it needs a web server (obviously), PHP 4 (at least 4.0.4 or higher), a MySQL server (and database), and a web browser for the configuration and administration (or text editor if you´re bold).

Because of the modular design and the separation of PHP, CSS and HTML code, it is quite easily changed and using another language is a question of providing for a set of HTML template files in that language and the alteration of some configuration settings. Also, if you don´t know any PHP (or don´t have any programming/scripting skills at all), changing the look or content of Richy´s Site Map means changing one or some CSS or HTML template files (which does mean you do need to know something about CSS or HTML), instead of tampering with PHP code. However, if you don´t want to, you don´t have to.

OK, enough boasting... You want it running and fast... But first, let me explain a little bit more about Richy´s Site Map and how to work with it.

The four little piggies, I mean, modes...

In Richy´s Site Map there are four so-called modes:

mode   explanation
normal   This is the mode when Richy´s Site Map is used by one of the visitors of your web site. Just a site map, as you´d expect.
auth   So called "authorized" mode, because this mode can only be used by someone who is authorized to do so, like the webmaster. Works on the principle of a simple link (or alias definition in Apache´s httpd.conf) to Richy´s Site Map in a password-protected section of your web site.
admin   The mode where you can administer Richy´s Site Map, which means change its items. Works only when already in auth mode, simply by clicking on the Admin button beneath the site map frame, or directly by typing "http://www.example.com/$base_auth_url/?admin" in the location bar of your browser.
config   By calling ../config.php (what you´re about to do in a minute when you´re just starting), you can configure the settings of Richy´s Site Map itself, so paths, URLs, titles etc.
One (perhaps premature) warning though: because ../config.php is for configuring ../config/config.inc.php, it cannot assume the values in this file are correct and so can´t use any means of security provided by Richy´s Site Map (like working through auth mode, like the admin mode does). And because I can´t know on what web server you´re going to install Richy´s Site Map, I can´t just put an .htaccess file in the directory and hope it works... Thus I have incorporated a crude security method in ../config.php with a username and a password, but maybe it is best that you secure ../config.php further. The username and the password by the way, are in ../config/config_sec.inc.php (the only file included by ../config.php) and are initially set to username "admin" and password "admin" (which also means, that at least you have to change ../config.php´s password, because this Documentation Page could have been read by a casual visitor!!! ../config.php does provide a means to change the password and/or username online, but you could also change the values yourself in ../config/config_sec.inc.php with a text editor. At least make sure you do change the password or you are at risk! You have been warned!).

Some more about auth mode

Auth mode needs a little bit more explaining: what is it and what does it do?

When I started to use Bjorge Dijkstra´s PHP3 TreeMenu as a site map on my own web site, I tweaked it a bit because I wanted one subsection of my site map (and all items/subsections beneath it of course) to be only visible by me (the webmaster) and not by other people. This subsection was called Webmaster Tools, where I would make site map items linking to pages/sections of the web site that were only meant for the webmaster, for example configuring MySQL or using my webmail application etc. There´s not much use for an item in the site map, that when clicked asks for a password, when you´re just a regular visitor, right? That´s why I wanted to hide that section when the site map was used by a regular visitor. As I used the items under the Webmaster Tools subsection a lot, I had it automatically expanded. Now, as an added bonus, Richy´s Site Map will automatically expand all auth subsections on level 2 of the site map (unless disabled of course). This feature is built into Richy´s Site Map and can be enabled/disabled by changing one configuration setting (instead of tweaking several lines of PHP code).

After some time, there was also another subsection of my site map I wanted to hide, but this time without being a subsection of Webmaster Tools. That meant again tweaking Bjorge´s PHP script, on which time I decided to write a whole new site map application for myself, where I could simply toggle the auth setting of an item in the site map, so I could hide more than one subsection of the site map for regular visitors. So, as you´d probably guessed, this feature is also built into Richy´s Site Map (actually, it was one the most important reasons to write my own site map application).

Furthermore, one subsection of my site map I was using very often myself, the Reference section, and this section contained a lot of subsections itself, so when I wanted to look up something, I ended up expanding the Reference section of the site map, waiting for the script and the browser to finish, then expanding a subsection of the Reference section, again waiting for the script and the browser to finish, etc. etc.

You can understand, that after a while I was fed up with the situation, and again (sigh!) tweaked Bjorge´s PHP script to automatically expand all subsections with level 3 and higher, so when I wanted to use an item in the Reference section, I only had to expand the Reference section and all subsections beneath that would already be expanded automatically. This feature is also built into Richy´s Site Map and can be enabled/disabled easily also.

Almost from the beginning, after starting to use Bjorge´s PHP3 TreeMenu, I set the start page of my web browser to be the site map of my web site and normally had more than one browser window open with a page from my web site (like the Log Monitor). So I would just open a new browser window, the site map would be automatically loaded and I would click on an item in the site map to load that page (a bit like the counter between the client area and the kitchen in a Chinese take-away restaurant). That was annoying, because I would have several browser windows, all with the same text in the title bar and thus it was difficult to know which window contained which page. The fullscreen functionality offers this feature when in auth mode in Richy´s Site Map and is (again) easily enabled/disabled.

And finally, when you´re in auth mode, the content of the "main"/right frame is different compared to normal mode, and can be easily adjusted by changing the content of one HTML template file.

As a last bonus thrown in, you can configure Richy´s Site Map to automatically change a link to the about.php page in the site map to point to the auth version of about.php instead. So, put an item in your site map tree that links to "/path_to_sitemap/about.php", enable this setting, and when in auth mode, you´ll get an item that links to "/path_to_auth/about.php".

So all in all, auth mode comprises several little gems of tweaking that make life a lot easier (in my opinion), and they can all, piece by piece, be enabled or disabled by you easily. They are all enabled now (the way I like it); if you don´t like it that way, just go to config mode to change the settings to your own liking (but first, read on about installation and configuration of Richy´s Site Map).

Installation/configuration instructions

Obviously, you´ve already unpacked the archive, since you´re viewing the documentation page that´s part of the archive... But, for the sake of completeness, I´ll write down all steps necessary to install and configure Richy´s Site Map:

  1. Unpack the archive to a subdirectory of the document root on your web site. Note: unpack it recursively, since there are directories in the archive.
  2. In a password-protected or otherwise secured section of your web site, make a link to the directory where you´ve unpacked Richy´s Site Map. You could also define an alias in your web server configuration, for instance when you use Apache, define this in the httpd.conf file. This is necessary to make the auth (and admin) mode work.
    Warning: if you don´t secure this link or alias, everybody can go to auth and admin (!) mode just by typing the right URL! You have been warned!
  3. Create a database on your MySQL server that will hold the site map items. You are free to choose a name for this database. Remember the name you chose, as you´ll be needing it later. Optionally, you can skip this step, go directly to step 4 and let me handle the creation of the database by means of the form directly under step 4.
  4. Create the items table in the MySQL database you´ve just created. To do that, use the form beneath this text or import the file ../config/items.sql in MySQL yourself. One item will already be added to the items table if you use ../config/items.sql or the form under this step: the home page of your web site.
    B.T.W.: this form will already give a user and pass of admin and admin respectively to ../config.php for convenience. If you´ve already changed the username and/or password for config mode, this obviously will not work. Just logon and the items table (and database) will still be made.


  5. Form to create the items table
    hostname of MySQL server  
    username to logon to MySQL server
    password to logon to MySQL server
    name of MySQL database
    Also create the database
     

  6. Alright, just one more step before Richy´s Site Map will work: configuring the package. As mentioned above, there is a config mode to configure the package and the way to get there, is by calling ../config.php. After that, go to admin mode by going to the URL defined by you as a link or an alias for auth mode and you should see one item in your site map (the Home Page), beneath that an Admin button to go to admin mode. Or just type "?admin" after your auth URL in the location bar of your web browser.
    Now fill your site map with the items you want and voilà, you´re done!
  7. That´s it. Check it out!

How it´s done (if you´re interested)

The main script files

The first script that is called, is ../index.php, which defines the frameset (in the "main"/right frame ../about.php and in the "sitemap"/left frame ../sitemap.php) or redirects to ../sitemap.php if the visitor´s browser doesn´t support frames.

Of course it´s all about ../sitemap.php, which produces the site map. It actually comprises several bits of code and HTML templates to account for the functionalities that Richy´s Site Map can offer.

In the "main"/right frame, ../about.php is executed. It is also executed for the first page of admin mode. After that, ../admin.php takes over for the real administrative work (inserting/mutating/deleting items in the site map). So, as you´ve probably guessed, ../admin.php is for administering Richy´s Site Map.

Last but not least, ../config.php is for configuring Richy´s Site Map and because it´s for configuration, it can´t assume the settings in ../config/config.inc.php are right, and thus can´t use any of the include files, and thus has to do everything by itself, including generating all necessary HTML code. So ../config.php is one big mishmash of PHP, CSS and HTML all in one page, and therefore it actually is kind of an outsider (because it´s not really modular and doesn´t separate PHP from CSS and HTML code).

Later on, I have made also ../chk_tmpl_tags.php as a handy tool if you want to make a new language available (so then you have to add several HTML template files) or tweak the PHP code of Richy´s Site Map. It checks all PHP and template files and reports back any inconsistencies it has found.

And to make life even easier, I´ve added ../authindex.php, that gives a simple page with links to all the different items of Richy´s Site Map when in auth mode.

The include files

The main script files require a lot of include files: two PHP classes, several files that insert code directly in the script and others that only define a/some function(s), which are then used. I can safely say that the most used function throughout Richy´s Site Map is the parse() function defined in ../include/parse.inc.php. It´s used in all main script files (except ../config.php of course and ../chk_tmpl_tags.php doesn´t use it either), and by almost all other include files in ../include.
Note that only later, I read in the PHP Manual about strtr() which does about the same, if I´m right... What the heck, parse() is working quite alright and I don´t really expect to see much performance improvement if switching to the use of strtr() throughout Richy´s Site Map instead of parse(). My guess it would be much work for nothing...

First of all, ../config/config.inc.php is included by all main script files, except ../config.php of course (and from now on, I won´t mention anymore that ../config.php doesn´t include any files except for ../config/config_sec.inc.php). In this file are the configuration settings of Richy´s Site Map.

Secondly, ../config/config_sec.inc.php is only included by ../config.php and ../chk_tmpl_tags.php and contains the security settings of config mode, which means two simple lines with variable definitions, namely $username and $password.

Then there are the include files in ../include. There are two class files, class.mysql_sitemap.php and class.dir.php. There are files that are included by all main script files (except chk_tmpl_tags.php: admin.inc.php, auth.inc.php and parse.inc.php), files that are included only by admin.php (admin_convert.inc.php, admin_del.inc.php, admin_fill.inc.php, admin_ins_after.inc.php, admin_ins_before.inc.php, admin_mutate.inc.php, admin_radio.inc.php, insert_level.inc.php and insert_radio.inc.php), only by sitemap.php (fullscreen.inc.php and sitemap.inc.php), and by ../admin.php and ../sitemap.php (diesmiling.inc.php).

The template files

Then, the last file type are the template files. They are files that will be returned to the browser as-is, with only text that starts with <<< and ends with >>> replaced by the output of some PHP code. Note: whenever you change a template file, make sure you only use the <<<>>> tags already there. If you add a <<<>>> tag that is formerly unknown, you have to change the PHP file(s) that "parse(s)" this template file! But for that, see ../chk_tmpl_tags.php; it will tell you which PHP file(s) "parse" which template file(s).
You´ve got ../config/languages, where are all the HTML template files in subdirectories (so language-dependent), and ../config/templates/css, where are all the CSS template files.

So if you want to run Richy´s Site Map in another language, you have to provide for all the files that are in ../config/languages/language. There are a lot of files there, so it will take you some time, but most files are only a few hundreds of bytes (they are just small components, not a complete HTML page). The most files you have to provide for are the components of the site map frame/page.
By the way, Richy´s Site Map has been designed to run in one language only at a time, so there is no mechanism to provide the pages in a language the visitor chooses (for example via HTTP_ACCEPT). Maybe I´ll do that in the future. The problem is namely, that there are also language-dependent values in ../config/config.inc.php, so actually the place of this file is wrong, it should be in ../config/languages/language...

So when you look at the bigger picture of the HTML template files, there is ../config/languages/language/components with the components (so just small pieces of HTML pages), and ../config/languages/language/templates/html with the files that make up complete sections of an HTML page (like the <head> and <style> sections) and files that make up complete HTML pages.
The HTML component files are (mostly) "parsed" by the include files, and the HTML template files are "parsed" by the main script files.

The complete picture

When you take a look at the files that compose Richy´s Site Map, you´ll see the five PHP scripts (../about.php, ../admin.php, ../config.php, ../index.php and ../sitemap.php) and some subdirectories. This is the complete hierarchy of the directories and files (hover with your mouse over an item with a dark gray background colour to see an explanation about the subdirectory or file. If that doesn´t work or you can´t read fast enough, you can also click on it.):

                   
Base dir of Richy´s Site Map
config
languages
language (default: en)
components
main
body_content
html
main_auth
body_content
html
sitemap
button
admin
auth
fullscreen
no
yes
good_frames
html
tree
collapse_item
expand_item
img_end
img_leaf
img_line
img_space
img_split
item_text_admin
item_text_fullscreen
item_text_nolink
item_text_normal&auth
item_text_replace_about_fullscreen
item_text_replace_about_nofullscreen
table&tr
table_end
table_end_auth
td_begin
td_spacer
tr
tr_end
templates
html
admin
admin_access_denied
admin_convert
admin_del
admin_fill
admin_ins_after
admin_ins_before
admin_mutate
css
error
footer
header
index
main
main_admin
main_auth
sitemap
sitemap_auth
templates
css
index
main
main_admin
main_auth
sitemap
sitemap_auth
config.inc.php
config_sec.inc.php
doc
index.html
images
action!.jpg
admin_button.jpg
auth_button.jpg
rule.gif
tree_collapse.gif
tree_end.gif
tree_expand.gif
tree_leaf.gif
tree_space.gif
tree_split.gif
tree_vertline.gif
web.gif
include
admin.inc.php
admin_convert.inc.php
admin_del.inc.php
admin_fill.inc.php
admin_ins_after.inc.php
admin_ins_before.inc.php
admin_mutate.inc.php
admin_radio.inc.php
auth.inc.php
class.mysql_sitemap.php
diesmiling.inc.php
fullscreen.inc.php
insert_level.inc.php
insert_radio.inc.php
parse.inc.php
sitemap.inc.php
about.php
admin.php
authindex.php
chk_tmpl_tags.php
config.php
index.php
sitemap.php

Appendix

Page made with the internal editor of Midnight Commander on Linux Mandrake 8.1 by Richard Vrijhof