PageTemplate 2.1.3 → 2.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,267 @@
1
+ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head>
2
+ <title>PageTemplate</title>
3
+ <link rel="STYLESHEET" href="base.css" type="text/css" title="base.css">
4
+ </head>
5
+ <body>
6
+ <h1>Yo!</h1>
7
+ <hr />
8
+ <p class="navbar">
9
+ <a href="SiteMap.html">Sitemap</a> || PageTemplate</p>
10
+ <h1>PageTemplate</h1>
11
+ <hr />
12
+
13
+ <table width='100%' border='0'><tr>
14
+ <td><p>&lt;- <a href='SiteMap.html'>SiteMap</a></p>
15
+ </td>
16
+ <td align='right'><p><a href='install.html'>Getting It</a>- &gt;</p>
17
+ </td>
18
+ </tr></table>
19
+
20
+ <h2>Vital Information and Links</h2>
21
+
22
+
23
+ <table>
24
+ <tr>
25
+ <td>Version</td>
26
+ <td>2.0.0</td>
27
+ </tr>
28
+ <tr>
29
+ <td>Project Page</td>
30
+ <td><a href="http://rubyforge.org/projects/pagetemplate">PageTemplate on RubyForge</a></td>
31
+ </tr>
32
+ <tr>
33
+ <td>Instructions</td>
34
+ <td>Start with <a href="products/pagetemplate/install.html">Installing It</a></td>
35
+ </tr>
36
+ <tr>
37
+ <td>API Documenation</td>
38
+ <td><a href="products/pagetemplate/doc/index.html">Generated by RDoc</a></td>
39
+ </tr>
40
+ <tr>
41
+ <td>Download</td>
42
+ <td><a href="http://rubyforge.org/frs/?group_id=407">Grab the File</a></td>
43
+ </tr>
44
+ <tr>
45
+ <td>Forums</td>
46
+ <td><a href="http://rubyforge.org/forum/?group_id=407">Talk about PageTemplate</a></td>
47
+ </tr>
48
+ <tr>
49
+ <td>Bugs</td>
50
+ <td><a href="http://rubyforge.org/tracker/?atid=1626&amp;group_id=407&#38;func=browse">Report a Bug</a></td>
51
+ </tr>
52
+ <tr>
53
+ <td>Features</td>
54
+ <td><a href="http://rubyforge.org/tracker/?atid=1629&amp;group_id=407&#38;func=browse">Request a Feature</a></td>
55
+ </tr>
56
+ <tr>
57
+ <td>Project Changes</td>
58
+ <td><a href="http://rubyforge.org/cgi-bin/viewcvs.cgi/*checkout*/PageTemplate/Changes?cvsroot=pagetemplate">Latest <span class="caps">CVS </span>Copy of Changes</a></td>
59
+ </tr>
60
+ </table>
61
+
62
+
63
+
64
+
65
+ <p class="note">PageTemplate 2.x is in a major state of flux. Loads of new features were added by Greg Millam in
66
+ short order, and we are still streamlining and testing the code. All that means for you is that the docs
67
+ are not as up to date as we would like. Still, we try. Shouldn&#8217;t be <em>too</em> bad. Until then, look at
68
+ the <a href="products/pagetemplate/version2.html">2.0 overview page</a>.</p>
69
+
70
+
71
+ <h2>Introduction</h2>
72
+
73
+
74
+ <p>PageTemplate is a Ruby package which allows you to utilize text
75
+ templates for your Web projects. It is mainly intended for use in
76
+ a <span class="caps">CGI</span> environment, but has been designed to be useful in a broad
77
+ range of similar applications. It is inspired by, yet almost entirely
78
+ unlike, the <a href="http://html-template.sourceforge.net/">HTML::Template</a> package
79
+ available for Perl. It has many features in common with other templating
80
+ engines:</p>
81
+
82
+
83
+ <ul>
84
+ <li>Variable substitution</li>
85
+ <li>&#8220;if/else&#8221; blocks &#8211; inserting chunks of content depending on the
86
+ existence of a flag variable</li>
87
+ <li>&#8220;loop/no&#8221; blocks &#8211; repeatedly inserting a chunk of content, using
88
+ values from a list</li>
89
+ <li>A simple default syntax</li>
90
+ <li>The ability to include external files</li>
91
+ </ul>
92
+
93
+
94
+ <p>It also has a few features of its own <em>(otherwise, where&#8217;s the fun?)</em>.</p>
95
+
96
+
97
+ <ul>
98
+ <li>Customizable markup syntax to simplify integration with your own
99
+ tools.</li>
100
+ <li>Loop metavariables for special cases like the first or last step through
101
+ a loop.</li>
102
+ <li>Variable preprocessor to handle things like escaping <span class="caps">HTML</span> entities and
103
+ displaying <span class="caps">URL</span>-encoded strings.</li>
104
+ <li>Access to the accessors of a variable. <em>(like <code>circle.radius</code>)</em></li>
105
+ </ul>
106
+
107
+
108
+ <p>More features are planned, such as support for localization to allow
109
+ native-language markup. PageTemplate already does what I want it to do, so it
110
+ has hit the stage of refinement and addition of requested features.</p>
111
+
112
+
113
+ <h2>What PageTemplate Is Not</h2>
114
+
115
+
116
+ <ul>
117
+ <li>It&#8217;s not a programming language. If you want a programming language
118
+ for your Web pages, try <a href="http://www.php.net/">PHP</a>.</li>
119
+ <li>It&#8217;s not a tool for embedding Ruby code into your Web pages.
120
+ <a href="http://www.modruby.org/">eruby</a> already does a fine job of that.</li>
121
+ <li>It is <em>definitely</em> not <span class="caps">XML</span>. PageTemplate serves a much narrower field.
122
+ If you want to use Ruby with <span class="caps">XML</span>, there are
123
+ <a href="http://www.rubyxml.com/">excellent resources</a> for that.</li>
124
+ <li>PageTemplate is a personal project, which means that it&#8217;s not a
125
+ commercial product. As much as I hope that it&#8217;s useful and stable on
126
+ your computer, I can&#8217;t make any promises. If installing PageTemplate
127
+ levels New Jersey, there&#8217;s nothing I can do about it. This is my
128
+ version of the standard <b>no warranty</b> warranty.</li>
129
+ <li>Last but not least, PageTemplate is not <span class="caps">HTML</span>::Template. <span class="caps">HTML</span>::Template
130
+ has been growing and evolving for a few years, while PageTemplate was originally
131
+ the result of a week alone with 5 pounds of coffee. PageTemplate has
132
+ matured over the last couple of years, but it is still just a small
133
+ project maintained by a couple of guys in their spare time.</li>
134
+ </ul>
135
+
136
+
137
+ <h2>Motivation</h2>
138
+
139
+
140
+ <p>I&#8217;ve been a fan of Perl&#8217;s <span class="caps">HTML</span>::Template package for a long time, and I
141
+ miss its robust usefulness whenever I&#8217;m using a language that isn&#8217;t Perl.
142
+ After delving deeper into other languages, I thought it might be fun to make
143
+ some of that usefulness available in <a href="geekery/ruby/index.html">Ruby</a>.
144
+ It would give me a decent-sized personal project, which would help me stretch
145
+ my skills with project development and unit testing. Plus, if I had a
146
+ templating system available to me, maybe I wouldn&#8217;t miss Perl so badly.</p>
147
+
148
+
149
+ <p>So those are my primary motivations: personal education and homesickness.</p>
150
+
151
+
152
+ <p>Once the code started taking shape, though, I decided that I wanted
153
+ this to be useful for other people. &#8220;Download and use&#8221; kind
154
+ of useful.</p>
155
+
156
+
157
+ <p>The road since PageTemplate 1.0 has been shaped almost entirely by
158
+ user suggestions. My own needs for PT were modest, and it&#8217;s
159
+ pretty much been complete for me since 0.3. All of the additions since
160
+ then, such as include, unless, comments, and loop metavariables, have
161
+ been added because <em>you</em> wanted more out of PT. If it wasn&#8217;t you, then
162
+ maybe it was that guy behind you. I&#8217;m delighted that people have
163
+ been pushing and redefining PageTemplate to fit their own nefarious
164
+ goals. And heck, I&#8217;ll admit it. Loop metavariables are cool.</p>
165
+
166
+
167
+ <p>So if there&#8217;s anything I can do to make it easier for you
168
+ to put it to use in your own projects, please <a href="contact">tell me</a>!</p>
169
+
170
+
171
+ <h2>Using PageTemplate</h2>
172
+
173
+
174
+ <p>First, you&#8217;ll want to <a href="products/pagetemplate/install.html">download and install</a> the latest version of
175
+ PageTemplate. Then, <a href="products/pagetemplate/designer.html">designers</a> will make templates,
176
+ <a href="products/pagetemplate/programmer.html">programmers</a> will write code, and some of us will do both.
177
+ Eventually, you will probably get tired of the default syntax, and want to
178
+ make your own. If you&#8217;re an especially geeky sort of person, you&#8217;ll no doubt
179
+ want to look at the
180
+ <a href="products/pagetemplate/doc/index.html">reference</a> to classes and methods that are available in the PageTemplate
181
+ package.</p>
182
+
183
+
184
+ <p>Most importantly, <em>enjoy yourself</em>! PageTemplate is
185
+ supposed to be good geeky fun, not hard work with lots of sweat
186
+ and turmoil!</p>
187
+
188
+
189
+ <h2>Examples</h2>
190
+
191
+
192
+ <p>There&#8217;s nothing like an example or two to see how something works in
193
+ the real world. Making new examples is a priority now, so this list will
194
+ contain more items in the near future.</p>
195
+
196
+
197
+ <p>Unfortunately, I haven&#8217;t really gotten around to making or finding examples.
198
+ What do I have so far?</p>
199
+
200
+
201
+ <ul>
202
+ <li><a href="contact">The <span class="caps">COOLNAMEHERE</span> contact page</a> is written with Ruby and
203
+ PageTemplate.</li>
204
+ </ul>
205
+
206
+
207
+ <h2>Users</h2>
208
+
209
+
210
+ <p>We would love to hear about what you&#8217;ve done with PageTemplate.
211
+ <a href="contact">Contact me</a> with your stories and links, and I&#8217;ll put it in this
212
+ section.</p>
213
+
214
+
215
+ <h2>The License</h2>
216
+
217
+
218
+ <p>PageTemplate is distributed under The <span class="caps">MIT </span>License, which is detailed
219
+ below.</p>
220
+
221
+
222
+ <h3>The <span class="caps">MIT </span>License</h3>
223
+
224
+
225
+ <p>Copyright&#169; 2002-2005 Brian Wisti, Greg Millam</p>
226
+
227
+
228
+ <p>Permission is hereby granted, free of charge, to any person obtaining a copy
229
+ of this software and associated documentation files (the &#8220;Software&#8221;), to
230
+ deal in the Software without restriction, including without limitation the
231
+ rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
232
+ sell copies of the Software, and to permit persons to whom the Software is
233
+ furnished to do so, subject to the following conditions:</p>
234
+
235
+
236
+ <p>The above copyright notice and this permission notice shall be included in all
237
+ copies or substantial portions of the Software.</p>
238
+
239
+
240
+ <p><strong>
241
+ <span class="caps">THE SOFTWARE IS PROVIDED </span>&#8220;AS IS&#8221;, <span class="caps">WITHOUT WARRANTY OF ANY KIND</span>, EXPRESS <span class="caps">OR </span>
242
+ <span class="caps">IMPLIED</span>, INCLUDING <span class="caps">BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY</span>,
243
+ <span class="caps">FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT</span>. IN <span class="caps">NO EVENT SHALL THE </span>
244
+ <span class="caps">AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM</span>, DAMAGES <span class="caps">OR OTHER </span>
245
+ <span class="caps">LIABILITY</span>, WHETHER <span class="caps">IN AN ACTION OF CONTRACT</span>, TORT <span class="caps">OR OTHERWISE</span>, ARISING <span class="caps">FROM</span>,
246
+ <span class="caps">OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE </span>
247
+ <span class="caps">SOFTWARE</span>.
248
+ </strong></p>
249
+
250
+
251
+ <h2>Subpages:</h2>
252
+
253
+ <ul>
254
+ <li><A HREF="install.html">Getting It</A></li>
255
+ <li><A HREF="designer.html">The Designer&#8217;s Perspective</A></li>
256
+ <li><A HREF="programmer.html">The Programmer&#8217;s Perspective</A></li>
257
+ <li><A HREF="version2.html">PageTemplate Version 2: What&#8217;s New?</A></li>
258
+ <li><A HREF="SiteMap.html">SiteMap</A></li>
259
+ </ul><hr />
260
+
261
+ <p class="navbar">
262
+ <a href="SiteMap.html">Sitemap</a> || PageTemplate</p>
263
+
264
+ <h1>Yo!</h1>
265
+ <hr />
266
+ </body>
267
+ </html>
@@ -0,0 +1,125 @@
1
+ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head>
2
+ <title>Getting It</title>
3
+ <link rel="STYLESHEET" href="base.css" type="text/css" title="base.css">
4
+ </head>
5
+ <body>
6
+ <h1>Yo!</h1>
7
+ <hr />
8
+ <p class="navbar">
9
+ <a href="SiteMap.html">Sitemap</a> || <a href="index.html">PageTemplate</a>
10
+ / Getting It</p>
11
+ <h1>Getting It</h1>
12
+ <hr />
13
+
14
+ <table width='100%' border='0'><tr>
15
+ <td><p>&lt;- <a href='index.html'>PageTemplate</a></p>
16
+ </td>
17
+ <td align='right'><p><a href='designer.html'>The Designer&#8217;s Perspective</a>- &gt;</p>
18
+ </td>
19
+ </tr></table>
20
+
21
+ <h2>The Easy Way</h2>
22
+
23
+
24
+ <p>I finally got around to making a
25
+ <a href="http://rubygems.rubyforge.org/wiki/wiki.pl">RubyGems</a> gem package of
26
+ PageTemplate available. This means that you can install the latest
27
+ release of PageTemplate with one simple command:</p>
28
+
29
+
30
+ <pre class="console">
31
+ gem install -r PageTemplate
32
+ </pre>
33
+
34
+ <p>You can always download your own copy of the gem file and install
35
+ locally, if that&#8217;s your preference:</p>
36
+
37
+
38
+ <pre class="console">
39
+ gem install -l PageTemplate
40
+ </pre>
41
+
42
+ <h2>The Slightly Less Easy Way</h2>
43
+
44
+
45
+ <p>Maybe you don&#8217;t use RubyGems, or you just don&#8217;t feel like mucking
46
+ about with the gem system at all. That&#8217;s okay, I&#8217;ve got you covered.
47
+ You only need to download and install the source package from Rubyforge.</p>
48
+
49
+
50
+ <h3>Download</h3>
51
+
52
+
53
+ <p>In order to save on the bandwidth for my home machine, I&#8217;ve opened
54
+ a <a href="http://rubyforge.org/">RubyForge</a> account for
55
+ PageTemplate. That means that you can always find the latest version
56
+ of the PageTemplate package from my project download page:</p>
57
+
58
+
59
+ <blockquote>
60
+ <p><a href="http://rubyforge.org/projects/pagetemplate/">http://rubyforge.org/projects/pagetemplate/</a></p>
61
+ </blockquote>
62
+
63
+
64
+ <p>Once you&#8217;ve downloaded the latest version, unpack it into a temporary or
65
+ source directory.</p>
66
+
67
+
68
+ <pre class="console">
69
+ $ tar xfvzC PageTemplate-1_2_0.tar.gz ~/src/
70
+ </pre>
71
+
72
+ <h3>Test</h3>
73
+
74
+
75
+ <p>If you have Ruby 1.8, or <a href="http://testunit.talbott.ws/">Test::Unit</a>
76
+ installed on your machine, you can run the test cases that are
77
+ used during development of PageTemplate.</p>
78
+
79
+
80
+ <pre class="console">
81
+ $ ruby -w TC_PageTemplate.rb
82
+ </pre>
83
+
84
+ <p>If you get messages about any sort of failures, please let me know! I know
85
+ that the tests run smoothly on my machine, but I have no idea how it&#8217;ll work
86
+ on yours.</p>
87
+
88
+
89
+ <h3>Install</h3>
90
+
91
+
92
+ <h4>Using <code>install.rb</code></h4>
93
+
94
+
95
+ <p>PageTemplate uses the standard ruby <code>install.rb</code> script for installation,
96
+ which makes the process very easy:</p>
97
+
98
+
99
+ <pre class="console">
100
+ ruby install.rb config
101
+ ruby install.rb setup
102
+ (su or sudo)
103
+ ruby install.rb install
104
+ </pre>
105
+
106
+ <h4>Using Rake</h4>
107
+
108
+
109
+ <p>If you have the <a href="http://rake.rubyforge.org/">Rake</a> tool, you can use that to
110
+ take care of testing and installing PageTemplate.</p>
111
+
112
+
113
+ <pre class="console">
114
+ rake
115
+ sudo rake install
116
+ </pre><hr />
117
+
118
+ <p class="navbar">
119
+ <a href="SiteMap.html">Sitemap</a> || <a href="index.html">PageTemplate</a>
120
+ / Getting It</p>
121
+
122
+ <h1>Yo!</h1>
123
+ <hr />
124
+ </body>
125
+ </html>
@@ -0,0 +1,289 @@
1
+ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head>
2
+ <title>The Programmer's Perspective</title>
3
+ <link rel="STYLESHEET" href="base.css" type="text/css" title="base.css">
4
+ </head>
5
+ <body>
6
+ <h1>Yo!</h1>
7
+ <hr />
8
+ <p class="navbar">
9
+ <a href="SiteMap.html">Sitemap</a> || <a href="index.html">PageTemplate</a>
10
+ / The Programmer's Perspective</p>
11
+ <h1>The Programmer's Perspective</h1>
12
+ <hr />
13
+
14
+ <table width='100%' border='0'><tr>
15
+ <td><p>&lt;- <a href='designer.html'>The Designer&#8217;s Perspective</a></p>
16
+ </td>
17
+ <td align='right'><p><a href='version2.html'>PageTemplate Version 2</a>- &gt;</p>
18
+ </td>
19
+ </tr></table>
20
+
21
+ <h2>Getting Started</h2>
22
+
23
+
24
+ <p>Before you dig into the code, you might want to take a look at
25
+ the <a href="products/pagetemplate/designer.html">designer</a> perspective of PageTemplate.</p>
26
+
27
+
28
+ <h2>Using PageTemplate In Your Ruby Code</h2>
29
+
30
+
31
+ <p>This is a <em>very</em> quick overview, because I have realized lately that <em>more</em>
32
+ documentation isn&#8217;t necessarily <em>better</em> documentation. <a href="contact">Send me</a>
33
+ any questions you have, or clarifications you&#8217;d like to see, and I will be
34
+ happy to incorporate them into future revisions of this article.</p>
35
+
36
+
37
+ <p>First, of course, you&#8217;ll want to <a href="products/pagetemplate/install.html">install</a> the PageTemplate package.
38
+ Once that&#8217;s done, <code>require</code> the package.</p>
39
+
40
+
41
+ <pre class="code">
42
+ require "PageTemplate"
43
+ </pre>
44
+
45
+ <p>You&#8217;ll need a PageTemplate object to hold values and parse template files.</p>
46
+
47
+
48
+ <pre class="code">
49
+ template = PageTemplate.new()
50
+ </pre>
51
+
52
+ <p>At some point, you will want the PageTemplate object to load a
53
+ template text file, bristling with directives. The template file should
54
+ be readable by the script, and the path must be either absolute
55
+ or relative to the script&#8217;s working directory.</p>
56
+
57
+
58
+ <pre class="code">
59
+ template.load("/var/www/templates/template.txt")
60
+ </pre>
61
+
62
+ <p>To assign a value for use by PageTemplate, use hash-style
63
+ assignment, with the name to be used by the template as the key,
64
+ and the value assigned as &#8230; well &#8230; the value. The only rule is
65
+ that the value must evaluate to a String (either it <em>is</em> a
66
+ String or it has a <code>to_s</code> method). Page designers
67
+ would probably be grateful if the key was a string, too. Much
68
+ easier to type it into a text template that way.</p>
69
+
70
+
71
+ <pre class="code">
72
+ template["title"] = "My PageTemplate Script"
73
+ </pre>
74
+
75
+ <p>The easiest way to handle flags used in <code>if</code> directives
76
+ is to take advantage of Ruby&#8217;s boolean values.</p>
77
+
78
+
79
+ <pre class="code">
80
+ template["flag"] = true
81
+ template["otherflag"] = false
82
+ </pre>
83
+
84
+ <p>You can use the truth of a regular variable or loop variable in
85
+ an <code>if</code> directive, but remember that Ruby is more specific
86
+ about <code>false</code> than other languages you might be used to.
87
+ For example, the number zero is not false, it&#8217;s just zero. Same
88
+ with empty strings. If you want a variable to be interpreted as
89
+ <code>false</code>, you should explicitly set it.</p>
90
+
91
+
92
+ <p>PageTemplate uses arrays of objects for lists. Each object provides a local
93
+ namespace which lasts only for the current iteration through the chunk of
94
+ content. Otherwise, you&#8217;d have to manually set loop variables, and I don&#8217;t
95
+ like that idea!</p>
96
+
97
+
98
+ <p>The classic approach is to borrow from <span class="caps">HTML</span>::Template and use a list of hashes
99
+ for your namespaces.</p>
100
+
101
+
102
+ <pre class="code">
103
+ listing = [
104
+ { "name" =&gt; "Swordfishtrombones", "artist" =&gt; "Tom Waits" },
105
+ { "name" =&gt; "Dirt Track Date", "artist" =&gt; "Southern Culture On The Skids"},
106
+ { "name" =&gt; "Amnesiac", "artist" =&gt; "Radiohead" }
107
+ ]
108
+
109
+ template["albums"] = listing
110
+ </pre>
111
+
112
+ <p>What about nested lists? They are handled the same way. One of
113
+ the keys in your item hash points to another array of hashes, which
114
+ will be used for the inner loop.</p>
115
+
116
+
117
+ <pre class="code">
118
+ favorites = [
119
+ { "topic" =&gt; "Interesting Comic Books",
120
+ "items" =&gt; [
121
+ { "title" =&gt; "Dropsie Avenue",
122
+ "creator" =&gt; "Will Eisner"},
123
+ { "title" =&gt; "Cerebus",
124
+ "creator" =&gt; "Dave Sim"},
125
+ { "title" =&gt; "Jar Of Fools",
126
+ "creator" =&gt; "Jason Lutes"}
127
+ ]},
128
+ { "topic" =&gt; "Favorite Albums",
129
+ "items" =&gt; [
130
+ { "title" =&gt; "Amnesiac",
131
+ "creator" =&gt; "Radiohead"},
132
+ { "title" =&gt; "The Moon and Antarctica",
133
+ "creator" =&gt; "Modest Mouse"},
134
+ { "title" =&gt; "Dirt Track Date",
135
+ "creator" =&gt; "Southern Culture On The Skids"},
136
+ { "title" =&gt; "My Motor",
137
+ "creator" =&gt; "Dorkweed"},
138
+ { "title" =&gt; "Swordfishtrombones",
139
+ "creator" =&gt; "Tom Waits"}
140
+ ]}
141
+ ]
142
+ </pre>
143
+
144
+ <p>Using objects in a list requires a little more research, but it&#8217;s
145
+ still a practical solution. Say you&#8217;re trying to figure out how
146
+ to use PageTemplate in an image gallery. You might have an Image class with
147
+ accessors that look something like this:</p>
148
+
149
+
150
+ <pre class="code">
151
+ class Image
152
+ attr_reader :url, :height, :width, :caption
153
+ end
154
+ </pre>
155
+
156
+ <p>You can build your template armed with this knowledge.</p>
157
+
158
+
159
+ <pre>
160
+ [%in images%]
161
+ &lt;td&gt;
162
+ &lt;img src="[%var url%]" height="[%var height%]" width="[%var width%]" alt="[%var caption%]" /&gt;&lt;br /&gt;
163
+ [%var caption%]
164
+ &lt;/td&gt;
165
+ [%endin%]
166
+ </pre>
167
+
168
+ Then, rather than waste precious minutes altering class
169
+ <code>Image</code> to respond to hash-based access, you can
170
+ assign a list of <code>Image</code> objects to the template list.
171
+
172
+ <pre class="code">
173
+ gallery = Gallery.new()
174
+ # ...
175
+ galleryPage['images'] = gallery.current.images
176
+ </pre>
177
+
178
+ <p>This approach definitely encourages maintaining a consistent
179
+ interface. I wouldn&#8217;t want to go altering my template files (or
180
+ telling the designer to alter her files) every time I get a bright
181
+ idea for how <code>Image</code> should work.</p>
182
+
183
+
184
+ You can also refer to public methods of the object in your
185
+ template, but that&#8217;s still a bit shaky. The methods have to accept
186
+ calls with no arguments or blocks (Ex:
187
+ <code>image.thumbnail()</code> would be referenced as
188
+ <code>[%var thumbnail%]</code>).
189
+
190
+ <p>Once you&#8217;ve told your PageTemplate object which file to load and
191
+ what values to remember, you&#8217;ll probably want to display the
192
+ neat custom page.</p>
193
+
194
+
195
+ <pre class="code">
196
+ output = template.output
197
+ print output
198
+ </pre>
199
+
200
+ <p>Of course, if you do things this way you&#8217;ll have to remember all of
201
+ the <acronym title="Hypertext Transfer Protocol"><span class="caps">HTTP</span></acronym>
202
+ header information. Life will be much easier for you if you just use
203
+ the functionality provided by the standard <span class="caps">CGI</span> module for ruby.</p>
204
+
205
+
206
+ <pre class="code">
207
+ cgi.out { template.output }
208
+ </pre>
209
+
210
+ <h3>Including Files</h3>
211
+
212
+
213
+ <p>PageTemplate lets you insert text from other files. Even better: PageTemplate
214
+ will parse those files as templates, using your current Namespace. The only
215
+ issue that you must be aware of as a developer is the search path used by
216
+ PageTemplate.</p>
217
+
218
+
219
+ <ul>
220
+ <li>Variable includes</li>
221
+ <li>Filenames, relative to the search path.</li>
222
+ </ul>
223
+
224
+
225
+ <p>Now I will explain each of these.</p>
226
+
227
+
228
+ <h4>Variable Includes</h4>
229
+
230
+
231
+ <pre>[%include weather%]</pre>
232
+
233
+ <pre class="code">
234
+ weather = some_file_path_returned_by_a_method()
235
+ template['weather'] = weather
236
+ </pre>
237
+
238
+ <h4>Filenames</h4>
239
+
240
+
241
+ <pre>[%include weather.html%]</pre>
242
+
243
+ <p>The include path defaults to the script&#8217;s working directory (accessed via
244
+ <code>Dir.getwd</code>). You can add additional paths if this isn&#8217;t good enough
245
+ for you.</p>
246
+
247
+
248
+ <pre class="code">
249
+ template = PageTemplate.new(
250
+ 'include_paths' =&gt; ["/var/www/templates"]
251
+ )
252
+ </pre>
253
+
254
+ <p><code>template</code> now has an include path of the script&#8217;s working directory and <code>/var/www/templates/</code>.
255
+ The include path Array is accessible via the <code>paths</code> accessor.</p>
256
+
257
+
258
+ <pre class="code">
259
+ template = PageTemplate.new()
260
+ template.paths.source += [ 'templates/blue', 'templates/alpha' ]
261
+ </pre>
262
+
263
+ <h3>Digging Deeper</h3>
264
+
265
+
266
+ <p>The stuff covered in this tutorial should remain pretty consistent
267
+ through future versions. If you&#8217;re curious to see inside
268
+ PageTemplate.rb, though, you will definitely want to go over the
269
+ <a href="products/pagetemplate/doc/">reference pages</a>. It describes PageTemplate and the classes that back it
270
+ up. Be warned, though: anything not described in this page is definitely
271
+ subject to change, so your clever hack might be useless with the next release.
272
+ That never stopped me, though. Go, have fun!</p>
273
+
274
+
275
+ <h3>Creating Your Own Syntax</h3>
276
+
277
+
278
+ <p>Syntax glossaries are high on the list of things I want to change,
279
+ so I&#8217;m not going to write an extensive tutorial on creating your
280
+ own custom syntax yet. For now, use the <a href="products/pagetemplate/doc/">reference pages</a> as a guideline.</p><hr />
281
+
282
+ <p class="navbar">
283
+ <a href="SiteMap.html">Sitemap</a> || <a href="index.html">PageTemplate</a>
284
+ / The Programmer's Perspective</p>
285
+
286
+ <h1>Yo!</h1>
287
+ <hr />
288
+ </body>
289
+ </html>