Recursive Table of Contents v1.4 INSTALL DOCUMENTATION Copyright (C) 2006 Pedro Venda pjvenda at pjvenda org This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License ------------------------------------- see LICENSE file for more information ------------------------------------- A full copy of this program along with this file can be downloaded from my website http://www.pjvenda.org 0. REQUIREMENTS ------------ - A webserver that can interpret php code: * I recommend apache 2.0 or above with php 5 in the form of mod_php. The installation is simple and offers high performance. * Alternatively, php 4 works as well. this software was written in php 4 but works unchanged in php 5. * The php interpreter must have the mysql extension to interact with a mysql database. This extension is tipically included by default. - A mysql database server and/or at least one user/database with enough permissions to create/read one table. 1. INSTALLATION ------------ This document lists instructions to install the application. See the USAGE file for more information. 1.1. PHP INCLUDE LOCATION -------------------- Put the following files in some place that can be accessed by all webpages that will be using the rectoc code. - toc_config.php - toc_db.php - toc_display.php - toc_engine.php I recommend that the "include_path" configuration in php.ini is changed to include some directory where they're stored. Example: Suppose /home/httpd/htdocs/common will be the common include directory. In php.ini, the include_path directive will be appended with this path: include_path = ".:/usr/lib/php:/home/httpd/htdocs/common" 1.2. CSS CODE INCLUSION ------------------ Rectoc generates XHTML which uses some implicit and explicit CSS code that setups the appearence of the table, selected items and sublevels of each entry. The appearence of the TOC is then costumized and/or built from the CSS code, present in toc_style.css. An example CSS file is included that contains some definitions used in the rectoc code. The html code that uses toc() needs to include the CSS stylesheet file to apply the desired appearence for the TOC. An html example for CSS stylesheet inclusion could be: ... ... ... The CSS file can be anywhere within the webserver tree and just needs to be referenced either relatively or absolutely. It can even be on another website. 1.3. SQL DATABASE ------------ You need to create a table on some database (you can even create a dedicated database for that). That table will contain all the information about the table of contents. I would advise two users (user1 and user2) that can read the table information (SELECT) but only one (user2) can change it (INSERT, UPDATE, DELETE). The user 'user1' is adequate to be used in the rectoc php/database interaction code, because if somehow it gets compromised, there isn't much the attacker can do with it. Database administration should be done via 'user2'. *THERE IS NO BACKOFFICE FOR DATABASE MANAGEMENT* so it needs to be inserted manually from a database interface, either the command line or a graphical interface. at the moment, only mysql is supported, but there is a fairly large abstraction layer, so porting into other database engines shoudn't be difficult. I'm even considering using an abstraction engine like adodb, but due to the project's dimension, it would be overkill. The table has the following fields (explained): id (int) - numerical entry identifier (auto-incremented) ref_id (int) - numerical entry identifier of the referer entry level (int) - level of the current entry order (int) - order of the current entry according with the other entries of the same level codename (string) - unique string entry codename identifier toc_name (string) - entry name displayed in the TOC example: "google" title (string) - to be used as top title for the TOC entry example: "google guide" page_title (string) - extended entry description: to be optionally used as a main (big) title of the page example: "google search engine" link_desc (string) - link description example: "best search engine in the internet" link (string) - link address, either relative of full link example: "http://www.google.com" link_enable (int 1 or 0) - enable link for current entry (this value = 0 means that the entry will appear but will not be linked. example: - link_enable=1 generates "best search engine in the internet" - link_enable=0 generates "best search engine in the internet" enable (int 1 or 0) - enable toc entry (this value = 0 means the entry will be completely ignored) 1.4. PHP CODE -------- For each page that needs to use the rectoc, there must be an include directive for the toc_display.php program: require_once("toc_display.php"); Then, a couple of variables must be declared: $toc_name="entry_name"; $toc_name is the codename of the TOC entry in the database. it corresponds to the "codename" column of the toc table. the rectoc code will look for it in the database like this: SELECT * FROM toc_table WHERE codename=$toc_name; (NOTE: this is just indicative. you don't need do to sql queries anywhere) (NOTE2: "toc_table" and "codename" identifiers can be changed) example: 2. FURTHER HELP ------------ Read the USAGE file.