1. What is toaH?
  2. Get toaH
    1. Download
    2. License
    3. Changelog
  3. Setting up toaH
    1. The HTML
    2. The Menu
      1. General
      2. Structure
      3. Special Chars
    3. The Template
    4. The Stylesheet
  4. Contact
What is toaH?
toaH connects HTML pages and adds templates to them. You write your HTML pages just as you normally would and toaH is either not mentioned in the file at all and accessed with the help of a rewrite engine or is included with a single line of PHP. toaH integrates the template into the body of the page and adds stylesheets. Now toaH searches for a file which contains a link list with all files that should appear in the menu.
  • You have full control of what you are doing.
  • It's easy to integrate into existing pages.
  • It doesn't get in your way.
  • It prevents you from doing the same things over and over again for every page added.
Get toaH
Download
The archive option includes some sample files in addition to toah.php.
License
toaH is licensed under the GNU GPLv3.
Changelog
v141004 (2014/10/04)
  • Some small code cleanups
v140928 (2014/09/28)
  • Add sub-menu functionality
v130129 (2013/01/29)
  • Add option to prevent direct acccess of toah.php
v130125 (2013/01/25)
  • Try to make sure the file to handle is inside the webroot directory
v130108 (2013/01/08)
  • Send content type headers earlier to avoid problems when a plugins outputs something directly
  • Add a simple log functionality to toaH (not printed/handled by toaH itself)
  • Include a plugin file (toah/thplugins.php) in the archive containing the following plugins: getInfo - moved from toah.php, noToah - allows to disable toah by passing a parameter, counter - a very simple stat counter, debugToah - outputs the log and some other data
v121231 (2012/12/31)
  • Provide proper content type for XHTML documents (fixes some tag closing issues)
v121230 (2012/12/30)
  • Enhance API
  • Updated htaccess to pass on the query string
v121216 (2012/12/16)
  • Remove dependencies between path, menu and titles as read from "menu.txt" files; Each of them should now work independently even if a wrapper item for another one is missing in the template
  • Some small code cleanups
v120719
  • fixed: When in webroot wrong link was used
  • Important: Remove encoding detection and conversion between different ones since it was very buggy and caused a lot of limits. Now every file used by toaH has to be utf-8 encoded!
v120620
  • fixed: Fallback to HTML parsing not working
  • When ASCII encoding is detected by PHP for the document prefer UTF-8 instead
  • Don't hide errors/warnings by default but rely on the server settings
v120530
  • Stop using $_SERVER["DOCUMENT_ROOT"] since its availability is not guaranteed. This requires an additional parameter when toaH is used through mod_rewrite or in a similar way: link should contain the filename of the page to parse, relative to the document root (see sample.htaccess).
  • When using toaH by including it, remove the necessity to call toahEnd() at the end of input. toaH needs to be included with include_once/require_once. include or require will fail!
  • Enhance module flexibility by introducing new stages, accessible through constants. The documentation for the module API is also improved. Modules need an update to the new stages!
  • When the template file does not exist do not fallback to an internal one, but run without it.
v120523
  • smaller code cleanups
  • -1 file access
v120103
  • changed: meaning of file parameter. It should now contain the absolute, full path.
  • fixed: duplication of the xmlns attribute of the html tag when using the XHTML 1.0 Doctype
  • distinguish between HTML and XHTML when loading and saving the XML DOM to gain better support for HTML
  • sample.htaccess (in archives) simplified
v120102
  • fixed: loading of thplugins.php when toah used via include
  • cleaner code structure (separation of menu and stylesheet modules from toaH core class)
  • remove T::$file and T::$link. If toaH is used via parameter $_SERVER["SCRIPT_FILENAME"] and $_SERVER["PHP_SELF"] will now be set to the input file to not require distinguishment between usage via include and parameter anymore.
v111230
  • fixed: last element in body was being dropped (in most cases just whitespace)
v111229
  • fixed: links in menu did not work in webroot due to double slash
v111222
  • fixed: make usage via include work again
v100330
  • change Backend: Simple HTML Dom -> DOM + DomXPath
  • use static class instead of global array to store data
  • allow more possibilities for plugins / modules
  • Speed boost (up to twice as fast as previous versions of toaH v2)
v100214
  • cleaner links: links used in the menu, for including stylesheets, ... are now relative to the webroot. (till now they might have looked something like this: ./../../../../index.php)
  • removed check if linked file (menu) exists as this may lead to problems when using a rewrite engine
  • some smaller clean-ups
v100119
  • new: load possible plugins from thplugins.php (same directory as toah.php) (no plugins included yet) (documentation on how to write plugins to follow)
v100111
  • fixed: do not quit script if warning was created somewhere before toah execution
  • fixed: try to work around if enviroment variable DOCUMENT_ROOT is not set
v100110
  • new: add support to open file via parameter (for details see the html)
  • fixed: output buffer + callback doesn't work on some servers -> use output buffer without callback (for details see the html)
v091128
  • fixed: correct order of stylesheets: current one is last to make it override parent ones
  • fixed: support different encodings: toaH detects the encoding from the HTML File and encodes everything from different files (menu, template) accordingly
v091126
  • fixed: Now the links to parent elements in the path refers to a directory rather than to "directory/index.php". This allows the user to use a directory index different to "index.php".
v091124
  • new: Added support for separators between Path element
    (e.g. "Parent Child" now might look "Parent / Child")
    to use the separator add a second child to #thPath similar to this one: <li>/</li>

The changelog for toah 1 is located here. But please note: Main parts for toah 2 were rewritten. Thus the changelog has no meaning anymore.

Setting up toaH

Warning: This information is partly outdated and not valid anymore.

The HTML
It is recommended that your HTML is valid to guarantee the parser to work well.
toaH offers two ways to be used:
Parameter
Give the name of your file + the absolute path from the webserver root to toah.php?file=...
This will result in ugly URLs and you will have to change your links. To avoid this it is recommended to use a rewrite engine.
A sample .htaccess for Apache is included in the archieves.
Include
Add a line similar to this one at the very top of your file to include toah.php: <?php include_once "path/to/toah.php"; ?> Make sure to use include_once or require_once. A simple include will not work!
The Menu
General
  • The menu file is called menu.txt
  • toaH uses the files in the parent directories to create a path
  • CSV is used
  • Semicolons are used as separators
Structure
In the first line the title takes place. It is used in the path and as the main title on every page in the area of validity of this menu.

The link list consists of three items:
  1. path to the file (without leading slash)
  2. name of the link
  3. sub-title which will be used on the linked page only
Example: Doku
changelog.php;Changelog;Change log
howto/index.php;How To;HowTo Page
faq/index.php;FAQ;Frequently Asked Questions
Special Chars
  • To use a semicolon put quotation marks around it:
    Example: faq/index.php;"FAQ;other stuff";Frequently Asked Questions
  • To write special chars use HTML Entities:
    Example: faq/index.php;"FAQ &amp; &hearts;";FAQ
The Template
  • The template is called template.xml and has to be in the same directory as toah.php
  • Everything that should be used by toaH has to be in the first div in the file
  • IDs that are required:
    • thMenu
    • thPath
    • thContent
  • Optional IDs:
    • thMainTitle
    • thPageTitle
    • thAuthor
    • thChange
  • thPath and thMenu have to contain an element used to wrap the items.(see example)
  • to achieve that your path entries are separated add a second child to thPath like this <li class="thSeparator">/<li> (for another example take a look at the template Example below)
  • Everything that is in the body of the HTML file will be put into the element with the ID thContent.

Example: <div>
   <div>
      <h1 id="thMainTitle"></h1>
      <h2 id="thPageTitle"></h2>
      Path:
      <p id="thPath">
         <span/>
         <span>ยป</span>
      </p>
      <ul id="thMenu"><li/></ul>
      <p>
         Author: <span id="thAuthor"></span>
         <br />
         Last Change: <span id="thChange"></span>
      </p>
   </div>
   <div id="thContent"></div>
</div>

<p>Some stuff that will not be in the output generated by toaH</p>
The Stylesheet
  • The stylesheet is called style.css
  • toaH will use all stylesheets found in parent directories. This will enable you to add something without copying everything.
Contact
If you have questions on or problems with toaH you can contact me here: toah [at] ttill [dot] de