PageTemplate 2.1.5 → 2.1.6

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