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.
- data/Changes +1 -1
- data/Rakefile +1 -1
- data/lib/PageTemplate/parser.rb +13 -8
- data/setup-usage.txt +1 -1
- data/site/Makefile +15 -0
- data/site/MySubpageRenderer.rb +43 -0
- data/site/PageNavRenderer.rb +37 -0
- data/site/RedClothRenderer.rb +20 -0
- data/site/Site.rb +11 -0
- data/site/SiteNewsRenderer.rb +23 -0
- data/site/XhtmlTemplateRenderer.rb +141 -0
- data/site/base.css +4 -0
- data/site/footer.txt +2 -0
- data/site/header.txt +2 -0
- data/site/html/SiteMap.html +43 -0
- data/site/html/base.css +4 -0
- data/site/html/designer.html +524 -0
- data/site/html/index.html +267 -0
- data/site/html/install.html +125 -0
- data/site/html/programmer.html +289 -0
- data/site/html/version2.html +103 -0
- data/site/src/SiteMap +8 -0
- data/site/src/designer +410 -0
- data/site/src/index +165 -0
- data/site/src/install +80 -0
- data/site/src/metadata.txt +4 -0
- data/site/src/programmer +235 -0
- data/site/src/version2 +59 -0
- data/test.rb +3 -1
- metadata +29 -2
|
@@ -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><- <a href='SiteMap.html'>SiteMap</a></p>
|
|
15
|
+
</td>
|
|
16
|
+
<td align='right'><p><a href='install.html'>Getting It</a>- ></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&group_id=407&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&group_id=407&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’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>“if/else” blocks – inserting chunks of content depending on the
|
|
86
|
+
existence of a flag variable</li>
|
|
87
|
+
<li>“loop/no” blocks – 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’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’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’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’s not a
|
|
125
|
+
commercial product. As much as I hope that it’s useful and stable on
|
|
126
|
+
your computer, I can’t make any promises. If installing PageTemplate
|
|
127
|
+
levels New Jersey, there’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’ve been a fan of Perl’s <span class="caps">HTML</span>::Template package for a long time, and I
|
|
141
|
+
miss its robust usefulness whenever I’m using a language that isn’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’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. “Download and use” 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’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’t you, then
|
|
162
|
+
maybe it was that guy behind you. I’m delighted that people have
|
|
163
|
+
been pushing and redefining PageTemplate to fit their own nefarious
|
|
164
|
+
goals. And heck, I’ll admit it. Loop metavariables are cool.</p>
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
<p>So if there’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’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’re an especially geeky sort of person, you’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’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’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’ve done with PageTemplate.
|
|
211
|
+
<a href="contact">Contact me</a> with your stories and links, and I’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© 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 “Software”), 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>“AS IS”, <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’s Perspective</A></li>
|
|
256
|
+
<li><A HREF="programmer.html">The Programmer’s Perspective</A></li>
|
|
257
|
+
<li><A HREF="version2.html">PageTemplate Version 2: What’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><- <a href='index.html'>PageTemplate</a></p>
|
|
16
|
+
</td>
|
|
17
|
+
<td align='right'><p><a href='designer.html'>The Designer’s Perspective</a>- ></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’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’t use RubyGems, or you just don’t feel like mucking
|
|
46
|
+
about with the gem system at all. That’s okay, I’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’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’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’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><- <a href='designer.html'>The Designer’s Perspective</a></p>
|
|
16
|
+
</td>
|
|
17
|
+
<td align='right'><p><a href='version2.html'>PageTemplate Version 2</a>- ></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’t necessarily <em>better</em> documentation. <a href="contact">Send me</a>
|
|
33
|
+
any questions you have, or clarifications you’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’ll want to <a href="products/pagetemplate/install.html">install</a> the PageTemplate package.
|
|
38
|
+
Once that’s done, <code>require</code> the package.</p>
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
<pre class="code">
|
|
42
|
+
require "PageTemplate"
|
|
43
|
+
</pre>
|
|
44
|
+
|
|
45
|
+
<p>You’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’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 … well … 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’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’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’d have to manually set loop variables, and I don’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" => "Swordfishtrombones", "artist" => "Tom Waits" },
|
|
105
|
+
{ "name" => "Dirt Track Date", "artist" => "Southern Culture On The Skids"},
|
|
106
|
+
{ "name" => "Amnesiac", "artist" => "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" => "Interesting Comic Books",
|
|
120
|
+
"items" => [
|
|
121
|
+
{ "title" => "Dropsie Avenue",
|
|
122
|
+
"creator" => "Will Eisner"},
|
|
123
|
+
{ "title" => "Cerebus",
|
|
124
|
+
"creator" => "Dave Sim"},
|
|
125
|
+
{ "title" => "Jar Of Fools",
|
|
126
|
+
"creator" => "Jason Lutes"}
|
|
127
|
+
]},
|
|
128
|
+
{ "topic" => "Favorite Albums",
|
|
129
|
+
"items" => [
|
|
130
|
+
{ "title" => "Amnesiac",
|
|
131
|
+
"creator" => "Radiohead"},
|
|
132
|
+
{ "title" => "The Moon and Antarctica",
|
|
133
|
+
"creator" => "Modest Mouse"},
|
|
134
|
+
{ "title" => "Dirt Track Date",
|
|
135
|
+
"creator" => "Southern Culture On The Skids"},
|
|
136
|
+
{ "title" => "My Motor",
|
|
137
|
+
"creator" => "Dorkweed"},
|
|
138
|
+
{ "title" => "Swordfishtrombones",
|
|
139
|
+
"creator" => "Tom Waits"}
|
|
140
|
+
]}
|
|
141
|
+
]
|
|
142
|
+
</pre>
|
|
143
|
+
|
|
144
|
+
<p>Using objects in a list requires a little more research, but it’s
|
|
145
|
+
still a practical solution. Say you’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
|
+
<td>
|
|
162
|
+
<img src="[%var url%]" height="[%var height%]" width="[%var width%]" alt="[%var caption%]" /><br />
|
|
163
|
+
[%var caption%]
|
|
164
|
+
</td>
|
|
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’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’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’ve told your PageTemplate object which file to load and
|
|
191
|
+
what values to remember, you’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’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’s working directory (accessed via
|
|
244
|
+
<code>Dir.getwd</code>). You can add additional paths if this isn’t good enough
|
|
245
|
+
for you.</p>
|
|
246
|
+
|
|
247
|
+
|
|
248
|
+
<pre class="code">
|
|
249
|
+
template = PageTemplate.new(
|
|
250
|
+
'include_paths' => ["/var/www/templates"]
|
|
251
|
+
)
|
|
252
|
+
</pre>
|
|
253
|
+
|
|
254
|
+
<p><code>template</code> now has an include path of the script’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’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’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>
|