Revision: $Revision: 1.3 $
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.
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!). |
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).
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:
| Form to create the items table |
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 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 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 (auth.inc.php), by all main script files (except chk_tmpl_tags.php): admin.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).
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. But, I´ve translated the
template files from English to Dutch already myself and it took me about 90
minutes, so that´s not too bad.
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.
By the way, I you´re wondering about why ../chk_tmpl_tags.php
doesn´t "parse" the template files but instead also contains
CSS and HTML code, just think of it: it is for analyzing the template tags
and files, so if there´s something wrong with the template tags or
files, it could effect how and what is displayed and that would be a BAD
THING...
And since I´ve changed ../chk_tmpl_tags.php (from revision 1.2
and up) to work through auth mode instead of by logging on (by
"borrowing" the settings from ../config.php by means of
../config/config_sec.inc.php), using chk_tmpl_tags.php is
now extra convenient.
When you take a look at the files that compose Richy´s Site Map, you´ll see the seven PHP scripts (../about.php, ../admin.php, ../authindex.php, ../chk_tmpl_tags.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 | |||||||
