Toader
Common Variables In The Documentation
Below is a list of variables that are commonly used in documentation.
$entryName - The entry name for a L<Toader::Entry> object.
$outputDir - This is base directory for writing output to.
$r2r - This is relative path from root L<Toader> directory to the current one.
$toaderDir - This is a L<Toader> directory.
$toaderRoot - This is the root L<Toader> directory.
$pageName - This is the name of the page.What is a Toader directory?
A Toader directory is a directory with a '.toader' directory in it. The Toader root is base Toader directory in a tree of Toader directories.
The following limitations are imposed on what can be a Toader directory.
First it can't be root, '/'.
Second, it can't begin with a period.
Third, it must be able to contain a '.toader' directory.
Below is a posibility of what a '.toader' directory may contain as well as the mapping to the relavent documentation.
autodoc/ - AutoDoc.pod
config.ini - Config.pod
entries/ - Entry.pod
gallery.ini - Gallery.pod
index - Directory.pod
pages/ - Pages.pod
templates/ - Templates.podCommon Objects
AutoDoc
This copies over documentation from the specified directories under the specified directories under the Toader directory.
The related modules are as below.
Toader::Render::AutoDoc::Cleanup
Directory
This is a Toader directory. It renders to a single page that acts a index/landing page for a directory.
The related modules are as below.
Toader::Render::Directory::Cleanup
Toader::Render::Directory::backends::html
Entry
Entries are basically a blog entry or a article in a Toader directory.
By default the last entries page will the 25 newest articles.
The related modules are as below.
Toader::Render::Entry::Cleanup
Toader::Render::Entry::backends::html
Gallery
This is handles for Toader.
The related modules are as below.
Page
This is a single named page. It is for creating like a about page, contact page, etc.
The related modules are as below.
Toader::Render::Page::backends::html
Rendering
Rendering is handled be done via two methods, if not doing it via the command line tools.
The first is to use Toader::Render. This is the simpler method as once initiated Toader::Render can be reused.
The second is to invoke the rendering module for that type of object directly and use it to render it. For some things this is required as there are
The template "page" is used for rendering all pages. It is as below.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title> [== $c->{_}->{siteTitle} ==] </title>
<LINK href="[== $g->cssLocation ==]" rel="stylesheet" type="text/css">
</head>
<body>
<div id="header" >
[== $g->top ==]
</div>
<div id="location" >
[== $g->locationbar( $locationID ) ==]
</div>
<div>
<div id="sidebar" >
[==
if ( ! $g->hasEntries ){
return "";
}
return " <h3>Entries</h3>\n".
" ".$g->entriesLink." <br>\n".
" ".$g->entriesArchiveLink." <br>\n".
" <hr>\n";
==]
[==
my $pages=$g->listPages;
if ( ( ! defined( $pages ) ) || ( $pages eq "" ) ){
return "";
}
return " <h3>".$g->pageSummaryLink."</h3>\n".$pages."\n <hr>\n";
==]
<h3>Directories</h3>
[==
if ( $g->atRoot ){
return "";
}
return $g->rlink("Go To The Root")." <br>\n ";
$g->upOneDirLink." <br>\n <br>";
==]
[== $g->listDirs ==]
</div>
<div id="maincontent" >
[== $content ==]
</div>
</div>
<br><br><br>
<div id="copyright">
[==
my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst)=localtime(time);
$year=$year+1900;
return "Copyright ".$year." ".$c->{_}->{owner};
==]
</div>
</body>
</html>The following variables are passed to it.
toader - The L<Toader> object.
g - The L<Toader::Render::General> object.
self - The L<Toader::Render::Entry> object.
obj - The L<Toader::Entry> object.
c - The L<Config::Tiny> holding the Toader config.
content - This is the content to be included in the content section of the page.VCS integration
Toader is meant to integrate with a versioning system. By storing everything as a file, this is a fairly trivial task.
This allows the website to easily be stored in the same place and manner as the coding project that it is a website for, which allows documentation to be published easily and automatically via Toader::AutoDoc .
Security Concerns
As Toader uses Perl for templating, this means any arbitrary could can be executed via rendering it. For this purpose it is important that the person doing the rendering trusts that nothing dangerous is in any of it. For this purpose one needs to trust the any one who has commit privledges to that part of the VCS tree that contains it.