PageTemplate 2.1.5 → 2.1.6

data/site/src/index

@@ -1,165 +0,0 @@
-# '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

@@ -1,80 +0,0 @@
-# '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

@@ -1,4 +0,0 @@
-'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

@@ -1,235 +0,0 @@
-# '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/