Recursive Table of Contents v1.4 USAGE 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 Before reading this document, you should REALLY read the INSTALL file. 1. GENERAL INFORMATION ------------------- Usage is actually very simple. Create database entries, include the rectoc code file and define the necessary variables. Call the toc() function and the toc will be written in some correct XHTML code, hopefully to be rendered pretty with the help of a well written CSS style sheet. Please note that it is up to you to place the toc wherever you want. That is not relevant for the rectoc code. The code itself was written to use some a CSS style sheet to make it pretty and to place where I wanted. You should create such a style sheet too or change the included one. Example php file that renders and displays the TOC: 2. DATABASE ENTRIES ---------------- I haven't written a backend rectoc management yet. It didn't seem that important then, and it still doesn't. Of course it not practical nor generally pretty to directly hack the database everytime I want a change, but that's ok, I've designed it and know it well, so it doesn't take me much time. You however will need to understand what the fields mean and how they can be used. The list below tries to describe the database structure for reference. (this text is also present in the INSTALL file) 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 title (string) - to be used as top title for the TOC entry page_title (string) - extended entry description: to be optionally used as a main (big) title of the page link_desc (string) - link description link (string) - link address, either relative of full link 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. So a quick example of a simple TOC to be rendered like the following: TOC display | id | level | order | reference id | ------------------------+----+-------+-------+--------------+ Home | 1 | 0 | 1 | 0 | About the author | 2 | 1 | 1 | 1 | Programming | 3 | 0 | 2 | 0 | PHP | 4 | 1 | 1 | 3 | rectoc | 5 | 2 | 1 | 4 | (please not that at first, only "About the author" OR "PHP" are seen according to the respective selection of "Home" or "Programming") The above example could be inserted into the database as something like: | codename | toc_name | title | main_desc | link_desc | link ---------------------------------+----------+----------+------------+----------------------+------------+----- INSERT INTO table VALUES (1,0,0,1,"hom", "Home", "/ Homepage","Home Page of Foo Bar","main index","/index.php",1,1); INSERT INTO table VALUES (2,1,1,1,"author","About the author"," / Homepage / Author","The author of Foo Bar page","author information","/author/index.php",1,1); INSERT INTO table VALUES (3,0,0,2,"prog","Programming","/ Homepage / Programming","Programming section of Foo Bar","programs","/programming/index.php",1,1); INSERT INTO table VALUES (4,3,1,1,"php","PHP","/ Homepage / Programming / PHP","PHP Programming section of Foo Bar","php programs","/programming/php/index.php",1,1); INSERT INTO table VALUES (5,4,2,1,"rt","rectoc","/ Homepage / Programming / PHP / Recursive TOC","Recursive Table of Contents","rectoc program","/programming/php/rectoc/index.php",1,1); Get the picture? Hope so. 3. SOME AVAILABLE FUNCTIONS ------------------------ The toc_display.php contains all the frontend code to be used in the website pages. * toc() - main TOC function. generates the TOC and puts it in $toc["results"]["div"] * toc_display_toc() - prints the contents of the $toc["results"]["div"]. this function is just to avoid doing the ugly echo $toc["results"]["div"] but it is the second most important function of the project since toc() itself doesn't actually display the TOC. * toc_toptitle_cname() - (title from codename) returns a toptitle for the TOC entry $cname * toc_pagetitle_cname() - (page title from codename) returns a page title of a TOC entry $cname * toc_linkdesc_cname() - (link description from codename) returns a link description of a TOC entry $cname * toc_link_cname() - (link from codename with database description link_desc) returns an html formatted link of a TOC entry $cname with the database description link_desc * toc_link_desc_cname() - (link from codename with custom description) returns an html formatted link of a TOC entry $cname with a custom description 4. WORKING COMPLETE EXAMPLE ------------------------ Refer to the example/ subdirectory of this distribution. It contains the following files: - database.sql - database creation code and example TOC contents - example_page.php - example page that produces a TOC using rectoc - example_page_2.php - another example page - toc_config.php - rectoc configuration - toc_db.php - rectoc db abstraction code - toc_display.php - rectoc frontend code - toc_engine.php - rectoc functional code - toc_style.css - rectoc CSS style code 5. FURTHER HELP ------------ The source code is your friend. 6. FUNCTION REFERENCE ------------------ 6.1. toc_db.php ---------- toc_db_connect toc_db_disconnect toc_get_id toc_get_cname toc_get_row toc_get_id_cname toc_get_link_cname toc_get_linkdesc_cname toc_get_tname_cname toc_get_title_cname toc_get_pagetitle_cname toc_get_lenable_cname toc_get_link_id toc_get_refid_id toc_get_lenable_id toc_get_refid_row toc_get_id_row toc_get_link_row toc_get_lenable_row toc_get_tname_row toc_get_title_row toc_get_cname_row toc_get_level_row toc_get_linkdesc_row toc_get_pagetitle_row toc_get_enable_row toc_get_level_id toc_get_linkdesc_id toc_get_pagetitle_id 6.2. toc_display.php --------------- toc_link_cname toc_link_desc_cname toc_linkdesc_cname toc_pagetitle_cname toc_toptitle_cname toc_display_toc 6.3. toc_engine.php -------------- toc toc_create_path toc_create_row toc_create_toc toc_create_link toc_link_id toc_linkref toc_link toc_link_desc