PageTemplate 2.1.6 → 2.1.7

data/site/src/index

@@ -0,0 +1,165 @@
+# 'title' = 'PageTemplate'
+
+h2. Vital Information and Links
+
+|Version|2.0.0|
+|Project Page|"PageTemplate on RubyForge":http://rubyforge.org/projects/pagetemplate|
+|Instructions|Start with "Installing It":install|
+|API Documenation|"Generated by RDoc":ref|
+|Download|"Grab the File":http://rubyforge.org/frs/?group_id=407|
+|Forums|"Talk about PageTemplate":http://rubyforge.org/forum/?group_id=407|
+|Bugs|"Report a Bug":http://rubyforge.org/tracker/?atid=1626&group_id=407&func=browse|
+|Features|"Request a Feature":http://rubyforge.org/tracker/?atid=1629&group_id=407&func=browse|
+|Project Changes|"Latest CVS Copy of Changes":http://rubyforge.org/cgi-bin/viewcvs.cgi/*checkout*/PageTemplate/Changes?cvsroot=pagetemplate|
+
+p(note). PageTemplate 2.x is in a major state of flux. Loads of new features were added by Greg Millam in
+short order, and we are still streamlining and testing the code. All that means for you is that the docs
+are not as up to date as we would like. Still, we try. Shouldn't be _too_ bad. Until then, look at
+the "2.0 overview page":/products/pagetemplate/version2.html.
+
+h2. Introduction
+
+PageTemplate is a Ruby package which allows you to utilize text
+templates for your Web projects. It is mainly intended for use in
+a CGI environment, but has been designed to be useful in a broad
+range of similar applications. It is inspired by, yet almost entirely
+unlike, the "HTML::Template":http://html-template.sourceforge.net/ package 
+available for Perl. It has many features in common with other templating 
+engines:
+
+* Variable substitution
+* "if/else" blocks - inserting chunks of content depending on the 
+  existence of a flag variable
+* "loop/no" blocks - repeatedly inserting a chunk of content, using 
+  values from a list
+* A simple default syntax
+* The ability to include external files
+
+It also has a few features of its own _(otherwise, where's the fun?)_.
+
+* Customizable markup syntax to simplify integration with your own 
+  tools.
+* Loop metavariables for special cases like the first or last step through
+  a loop.
+* Variable preprocessor to handle things like escaping HTML entities and
+  displaying URL-encoded strings.
+* Access to the accessors of a variable. _(like @circle.radius@)_
+
+More features are planned, such as support for localization to allow 
+native-language markup. PageTemplate already does what I want it to do, so it
+has hit the stage of refinement and addition of requested features.
+
+h2. What PageTemplate Is Not
+
+* It's not a programming language. If you want a programming language 
+  for your Web pages, try "PHP":http://www.php.net/.
+* It's not a tool for embedding Ruby code into your Web pages. 
+  "eruby":http://www.modruby.org/ already does a fine job of that.
+* It is _definitely_ not XML. PageTemplate serves a much narrower field. 
+  If you want to use Ruby with XML, there are 
+  "excellent resources":http://www.rubyxml.com/ for that.
+* PageTemplate is a personal project, which means that it's not a 
+  commercial product. As much as I hope that it's useful and stable on 
+  your computer, I can't make any promises. If installing PageTemplate 
+  levels New Jersey, there's nothing I can do about it. This is my 
+  version of the standard **no warranty** warranty.
+* Last but not least, PageTemplate is not HTML::Template. HTML::Template 
+  has been growing and evolving for a few years, while PageTemplate was originally
+  the result of a week alone with 5 pounds of coffee. PageTemplate has
+  matured over the last couple of years, but it is still just a small
+  project maintained by a couple of guys in their spare time.
+
+h2. Motivation
+
+I've been a fan of Perl's HTML::Template package for a long time, and I 
+miss its robust usefulness whenever I'm using a language that isn't Perl. 
+After delving deeper into other languages, I thought it might be fun to make
+some of that usefulness available in "Ruby":/geekery/ruby/index.html.
+It would give me a decent-sized personal project, which would help me stretch 
+my skills with project development and unit testing. Plus, if I had a 
+templating system available to me, maybe I wouldn't miss Perl so badly.
+
+So those are my primary motivations: personal education and homesickness.
+
+Once the code started taking shape, though, I decided that I wanted
+this to be useful for other people. "Download and use" kind
+of useful. 
+
+The road since PageTemplate 1.0 has been shaped almost entirely by
+user suggestions. My own needs for PT were modest, and it's 
+pretty much been complete for me since 0.3. All of the additions since
+then, such as include, unless, comments, and loop metavariables, have
+been added because _you_ wanted more out of PT. If it wasn't you, then
+maybe it was that guy behind you. I'm delighted that people have
+been pushing and redefining PageTemplate to fit their own nefarious
+goals. And heck, I'll admit it. Loop metavariables are cool. 
+
+So if there's anything I can do to make it easier for you
+to put it to use in your own projects, please "tell me":#{contact}!
+
+h2. Using PageTemplate
+
+First, you'll want to "download and install":install the latest version of 
+PageTemplate. Then, "designers":design will make templates, 
+"programmers":program will write code, and some of us will do both. 
+Eventually, you will probably get tired of the default syntax, and want to 
+make your own. If you're an especially geeky sort of person, you'll no doubt 
+want to look at the 
+"reference":ref to classes and methods that are available in the PageTemplate 
+package.
+
+Most importantly, _enjoy yourself_! PageTemplate is 
+supposed to be good geeky fun, not hard work with lots of sweat 
+and turmoil!
+
+h2. Examples
+
+There's nothing like an example or two to see how something works in
+the real world. Making new examples is a priority now, so this list will
+contain more items in the near future.
+
+Unfortunately, I haven't really gotten around to making or finding examples. 
+What do I have so far?
+
+* "The COOLNAMEHERE contact page":#{contact} is written with Ruby and
+  PageTemplate.
+
+h2. Users
+
+We would love to hear about what you've done with PageTemplate.
+"Contact me":#{contact} with your stories and links, and I'll put it in this 
+section.
+
+h2. The License
+
+PageTemplate is distributed under The MIT License, which is detailed
+below.
+
+h3. The MIT License
+
+Copyright (c) 2002-2005 Brian Wisti, Greg Millam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy 
+of this software and associated documentation files (the "Software"), to 
+deal in the Software without restriction, including without limitation the 
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 
+sell copies of the Software, and to permit persons to whom the Software is 
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all 
+copies or substantial portions of the Software.
+
+<strong>
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 
+SOFTWARE.
+</strong>
+
+[install]/products/pagetemplate/install.html
+[design]/products/pagetemplate/designer.html
+[program]/products/pagetemplate/programmer.html
+[ref]/products/pagetemplate/doc/index.html

data/site/src/install

@@ -0,0 +1,80 @@
+# 'title' = 'Getting It'
+
+h2. The Easy Way
+
+I finally got around to making a 
+"RubyGems":http://rubygems.rubyforge.org/wiki/wiki.pl gem package of 
+PageTemplate available. This means that you can install the latest 
+release of PageTemplate with one simple command:
+
+<pre class="console">
+gem install -r PageTemplate
+</pre>
+
+You can always download your own copy of the gem file and install
+locally, if that's your preference:
+
+<pre class="console">
+gem install -l PageTemplate
+</pre>
+
+h2. The Slightly Less Easy Way
+
+Maybe you don't use RubyGems, or you just don't feel like mucking
+about with the gem system at all. That's okay, I've got you covered.
+You only need to download and install the source package from Rubyforge.
+
+h3. Download
+
+In order to save on the bandwidth for my home machine, I've opened
+a "RubyForge":http://rubyforge.org/ account for
+PageTemplate. That means that you can always find the latest version
+of the PageTemplate package from my project download page:
+
+bq. "http://rubyforge.org/projects/pagetemplate/":http://rubyforge.org/projects/pagetemplate/
+
+Once you've downloaded the latest version, unpack it into a temporary or 
+source directory.
+
+<pre class="console">
+$ tar xfvzC PageTemplate-1_2_0.tar.gz ~/src/
+</pre>
+
+h3. Test
+
+If you have Ruby 1.8, or <a href="http://testunit.talbott.ws/">Test::Unit</a>
+installed on your machine, you can run the test cases that are
+used during development of PageTemplate.
+
+<pre class="console">
+$ ruby -w TC_PageTemplate.rb
+</pre>
+
+If you get messages about any sort of failures, please let me know! I know 
+that the tests run smoothly on my machine, but I have no idea how it'll work 
+on yours.
+
+h3. Install
+
+h4. Using @install.rb@
+
+PageTemplate uses the standard ruby @install.rb@ script for installation, 
+which makes the process very easy:
+
+<pre class="console">
+ruby install.rb config
+ruby install.rb setup
+(su or sudo)
+ruby install.rb install
+</pre>
+
+h4. Using Rake
+
+If you have the "Rake":http://rake.rubyforge.org/ tool, you can use that to 
+take care of testing and installing PageTemplate.
+
+<pre class="console">
+rake
+sudo rake install
+</pre>
+

data/site/src/metadata.txt

@@ -0,0 +1,4 @@
+'renderers' = ['PageNavRenderer', 'MySubpageRenderer', 'MetadataRenderer', 'RedClothRenderer', 'XhtmlTemplateRenderer', 'FooterRenderer', 'RelativeRenderer', 'HeaderRenderer']
+'footer' = File.open('footer.txt').read()
+'header' = File.open('header.txt').read()
+'stylesheet' = 'base.css'

data/site/src/programmer

@@ -0,0 +1,235 @@
+# 'title' = "The Programmer's Perspective"
+
+h2. Getting Started
+
+Before you dig into the code, you might want to take a look at
+the "designer":designer perspective of PageTemplate.
+
+h2. Using PageTemplate In Your Ruby Code
+
+This is a _very_ quick overview, because I have realized lately that _more_
+documentation isn't necessarily _better_ documentation. "Send me":#{contact} 
+any questions you have, or clarifications you'd like to see, and I will be 
+happy to incorporate them into future revisions of this article.
+
+First, of course, you'll want to "install":install the PageTemplate package. 
+Once that's done, @require@ the package.
+
+<pre class="code">
+require "PageTemplate"
+</pre>
+
+You'll need a PageTemplate object to hold values and parse template files.
+
+<pre class="code">
+template = PageTemplate.new()
+</pre>
+
+At some point, you will want the PageTemplate object to load a
+template text file, bristling with directives. The template file should
+be readable by the script, and the path must be either absolute
+or relative to the script's working directory.
+
+<pre class="code">
+template.load("/var/www/templates/template.txt")
+</pre>
+
+To assign a value for use by PageTemplate, use hash-style
+assignment, with the name to be used by the template as the key,
+and the value assigned as ... well ... the value. The only rule is
+that the value must evaluate to a String (either it _is_ a
+String or it has a @to_s@ method). Page designers
+would probably be grateful if the key was a string, too. Much
+easier to type it into a text template that way.
+
+<pre class="code">
+template["title"] = "My PageTemplate Script"
+</pre>
+
+The easiest way to handle flags used in @if@ directives
+is to take advantage of Ruby's boolean values.
+
+<pre class="code">
+template["flag"] = true
+template["otherflag"] = false
+</pre>
+
+You can use the truth of a regular variable or loop variable in
+an @if@ directive, but remember that Ruby is more specific
+about @false@ than other languages you might be used to.
+For example, the number zero is not false, it's just zero. Same
+with empty strings. If you want a variable to be interpreted as 
+@false@, you should explicitly set it.
+
+PageTemplate uses arrays of objects for lists.  Each object provides a local 
+namespace which lasts only for the current iteration through the chunk of 
+content. Otherwise, you'd have to manually set loop variables, and I don't 
+like that idea!
+
+The classic approach is to borrow from HTML::Template and use a list of hashes 
+for your namespaces.
+
+<pre class="code">
+listing = [
+ { "name" => "Swordfishtrombones", "artist" => "Tom Waits" },
+ { "name" => "Dirt Track Date", "artist" => "Southern Culture On The Skids"},
+ { "name" => "Amnesiac", "artist" => "Radiohead" }
+]
+   
+template["albums"] = listing
+</pre>
+
+What about nested lists? They are handled the same way. One of
+the keys in your item hash points to another array of hashes, which
+will be used for the inner loop.
+
+<pre class="code">
+favorites = [
+  { "topic"  => "Interesting Comic Books",
+    "items"    => [
+    { "title"   => "Dropsie Avenue", 
+      "creator" => "Will Eisner"},
+    { "title"   => "Cerebus", 
+      "creator" => "Dave Sim"},
+    { "title"   => "Jar Of Fools", 
+      "creator" => "Jason Lutes"}
+  ]},
+  { "topic"  => "Favorite Albums",
+    "items"    => [
+    { "title"   => "Amnesiac", 
+      "creator" => "Radiohead"},
+    { "title"   => "The Moon and Antarctica", 
+      "creator" => "Modest Mouse"},
+    { "title"   => "Dirt Track Date", 
+      "creator" => "Southern Culture On The Skids"},
+    { "title"   => "My Motor", 
+      "creator" => "Dorkweed"},
+    { "title"   => "Swordfishtrombones", 
+      "creator" => "Tom Waits"}
+  ]}
+]
+</pre>
+
+Using objects in a list requires a little more research, but it's
+still a practical solution. Say you're trying to figure out how
+to use PageTemplate in an image gallery.  You might have an Image class with 
+accessors that look something like this:
+
+<pre class="code">
+class Image
+  attr_reader :url, :height, :width, :caption
+end
+</pre>
+
+You can build your template armed with this knowledge.
+
+<pre>
+[%in images%]
+<td>
+  <img src="[%var url%]" height="[%var height%]" width="[%var width%]" alt="[%var caption%]" /><br />
+  [%var caption%]
+</td>
+[%endin%]
+</pre>
+
+Then, rather than waste precious minutes altering class
+<code>Image</code> to respond to hash-based access, you can 
+assign a list of <code>Image</code> objects to the template list.
+
+<pre class="code">
+gallery = Gallery.new()
+# ...
+galleryPage['images'] = gallery.current.images
+</pre>
+
+This approach definitely encourages maintaining a consistent 
+interface. I wouldn't want to go altering my template files (or 
+telling the designer to alter her files) every time I get a bright
+idea for how <code>Image</code> should work.
+
+You can also refer to public methods of the object in your
+template, but that's still a bit shaky. The methods have to accept
+calls with no arguments or blocks (Ex: 
+<code>image.thumbnail()</code> would be referenced as 
+<code>[%var thumbnail%]</code>).
+
+Once you've told your PageTemplate object which file to load and
+what values to remember, you'll probably want to display the
+neat custom page.
+
+<pre class="code">
+output = template.output
+print output
+</pre>
+
+Of course, if you do things this way you'll have to remember all of
+the <acronym title="Hypertext Transfer Protocol">HTTP</acronym>
+header information. Life will be much easier for you if you just use
+the functionality provided by the standard CGI module for ruby.
+
+<pre class="code">
+cgi.out { template.output }
+</pre>
+
+h3. Including Files
+
+PageTemplate lets you insert text from other files. Even better: PageTemplate
+will parse those files as templates, using your current Namespace. The only
+issue that you must be aware of as a developer is the search path used by
+PageTemplate. 
+
+* Variable includes
+* Filenames, relative to the search path.
+
+Now I will explain each of these.
+
+h4. Variable Includes
+
+<pre>[%include weather%]</pre>
+
+<pre class="code">
+weather = some_file_path_returned_by_a_method()
+template['weather'] = weather
+</pre>
+
+h4. Filenames
+
+<pre>[%include weather.html%]</pre>
+
+The include path defaults to the script's working directory (accessed via
+@Dir.getwd@). You can add additional paths if this isn't good enough
+for you.
+
+<pre class="code">
+template = PageTemplate.new(
+  'include_paths' => ["/var/www/templates"]
+)
+</pre>
+
+@template@ now has an include path of the script's working directory and @/var/www/templates/@.
+The include path Array is accessible via the @paths@ accessor.
+
+<pre class="code">
+template = PageTemplate.new()
+template.paths.source += [ 'templates/blue', 'templates/alpha' ]
+</pre>
+
+h3. Digging Deeper
+
+The stuff covered in this tutorial should remain pretty consistent
+through future versions. If you're curious to see inside 
+PageTemplate.rb, though, you will definitely want to go over the
+"reference pages":ref. It describes PageTemplate and the classes that back it 
+up. Be warned, though: anything not described in this page is definitely 
+subject to change, so your clever hack might be useless with the next release. 
+That never stopped me, though. Go, have fun!
+
+h3. Creating Your Own Syntax
+
+Syntax glossaries are high on the list of things I want to change,
+so I'm not going to write an extensive tutorial on creating your
+own custom syntax yet. For now, use the "reference pages":ref as a guideline.
+
+[designer]/products/pagetemplate/designer.html
+[install]/products/pagetemplate/install.html
+[ref]/products/pagetemplate/doc/