Skip to content
Newer
Older
100644 318 lines (220 sloc) 8.46 KB
ca39d2f * tools/rakehelp.rb: Rake convenience methods ripped from mongrel.
_why authored Feb 2, 2006
1 = Markaby (Markup as Ruby)
f24aaa1 Initial import
_why authored Jan 6, 2006
2
ca39d2f * tools/rakehelp.rb: Rake convenience methods ripped from mongrel.
_why authored Feb 2, 2006
3 Markaby is a very short bit of code for writing HTML pages in pure Ruby.
4 It is an alternative to ERb which weaves the two languages together.
5 Also a replacement for templating languages which use primitive languages
6 that blend with HTML.
7
f4b2b30 @smtlaissezfaire README updates
smtlaissezfaire authored Aug 13, 2010
8 == Using Markaby as a Rails plugin / gem
f24aaa1 Initial import
_why authored Jan 6, 2006
9
10 Write Rails templates in pure Ruby. Example layout:
11
12 html do
13 head do
14 title 'Products: ' + action_name
15 stylesheet_link_tag 'scaffold'
16 end
acb563e @smtlaissezfaire Remove trailing whitespace
smtlaissezfaire authored Jun 1, 2010
17
f24aaa1 Initial import
_why authored Jan 6, 2006
18 body do
19 p flash[:notice], :style => "color: green"
acb563e @smtlaissezfaire Remove trailing whitespace
smtlaissezfaire authored Jun 2, 2010
20
f4b2b30 @smtlaissezfaire README updates
smtlaissezfaire authored Aug 13, 2010
21 div.signup! do
22 form_for @user do |f|
23 f.text_field :email
24 end
25 end
26
6ff5b18 @smtlaissezfaire update README to use yield syntax
smtlaissezfaire authored Aug 13, 2010
27 yield
f24aaa1 Initial import
_why authored Jan 6, 2006
28 end
29 end
30
566b50e @smtlaissezfaire readme updates
smtlaissezfaire authored Aug 15, 2010
31 Markaby templates end in .mab
32
33 Markaby supports many versions of rails, including the latest rails:
299c2a6 @smtlaissezfaire Add supported rails versions to README
smtlaissezfaire authored Oct 6, 2009
34
1139562 @smtlaissezfaire update README with this info.
smtlaissezfaire authored Oct 12, 2009
35 1.2.2, 1.2.3, 1.2.4, 1.2.5, 1.2.6, 2.2.0,
36 2.2.1, 2.2.2, 2.2.3, 2.3.1, 2.3.2, 2.3.2.1,
8257f2d @smtlaissezfaire update docs with latest rails support
smtlaissezfaire authored Jun 2, 2010
37 2.3.3, 2.3.3.1, 2.3.4, 2.3.5, 2.3.6, 2.3.7,
38 2.3.8
299c2a6 @smtlaissezfaire Add supported rails versions to README
smtlaissezfaire authored Oct 7, 2009
39
566b50e @smtlaissezfaire readme updates
smtlaissezfaire authored Aug 15, 2010
40 Rails 3.0 support is planned.
41
f4b2b30 @smtlaissezfaire README updates
smtlaissezfaire authored Aug 13, 2010
42 === Install it as a plugin
28ceaa0 @smtlaissezfaire update docs for installation in rails. Closes #15
smtlaissezfaire authored Jun 2, 2010
43
44 script/plugin install git://github.com/markaby/markaby.git
45
f4b2b30 @smtlaissezfaire README updates
smtlaissezfaire authored Aug 13, 2010
46 === Install it as a gem
47
48 gem install markaby
49
3ff9a5c @smtlaissezfaire update instructions for rails usage.
smtlaissezfaire authored Jul 28, 2010
50 If you are loading it in a different way (from a gem), make sure
f4b2b30 @smtlaissezfaire README updates
smtlaissezfaire authored Aug 13, 2010
51 it's on the $LOAD_PATH, and add the following in
3ff9a5c @smtlaissezfaire update instructions for rails usage.
smtlaissezfaire authored Jul 28, 2010
52 an initializer (config/initializers/markaby.rb will work):
28ceaa0 @smtlaissezfaire update docs for installation in rails. Closes #15
smtlaissezfaire authored Jun 2, 2010
53
54 require 'markaby'
55 require 'markaby/rails'
56
57 Markaby::Rails.load
58
f4b2b30 @smtlaissezfaire README updates
smtlaissezfaire authored Aug 13, 2010
59 Or, you could try config.gem, but that's now known as a bad idea.
60
28ceaa0 @smtlaissezfaire update docs for installation in rails. Closes #15
smtlaissezfaire authored Jun 2, 2010
61
566b50e @smtlaissezfaire readme updates
smtlaissezfaire authored Aug 15, 2010
62 == Using Markaby with Sinatra (1.0+)
63
64 require 'markaby/sinatra'
65
66 get '/foo' do
67 mab :my_template # my_template.mab in the sinatra view path
68 end
69
70 If you are looking for sinatra support pre 0.7, see http://github.com/sbfaulkner/sinatra-markaby
71
72
73 == Using Markaby with other frameworks
74
25e21c0 @smtlaissezfaire use the markaby module now built into tilt. Closes #24
smtlaissezfaire authored Dec 11, 2010
75 Tilt has a Markaby module, so in principle, any web framework that supports
76 Tilt will also support Markaby. See the appropriate tilt documentation:
77
78 http://github.com/rtomayko/tilt
566b50e @smtlaissezfaire readme updates
smtlaissezfaire authored Aug 15, 2010
79
80
ca39d2f * tools/rakehelp.rb: Rake convenience methods ripped from mongrel.
_why authored Feb 2, 2006
81 == Using Markaby as a Ruby class
f24aaa1 Initial import
_why authored Jan 6, 2006
82
ca39d2f * tools/rakehelp.rb: Rake convenience methods ripped from mongrel.
_why authored Feb 2, 2006
83 Markaby is flaming easy to call from your Ruby classes.
84
85 require 'markaby'
86
87 mab = Markaby::Builder.new
88 mab.html do
89 head { title "Boats.com" }
90 body do
91 h1 "Boats.com has great deals"
92 ul do
93 li "$49 for a canoe"
94 li "$39 for a raft"
95 li "$29 for a huge boot that floats and can fit 5 people"
96 end
97 end
98 end
99 puts mab.to_s
100
101 Markaby::Builder.new does take two arguments for passing in variables and
102 a helper object. You can also affix the block right on to the class.
103
104 See Markaby::Builder for all of that.
105
106 = A Note About <tt>instance_eval</tt>
107
108 The Markaby::Builder class is different from the normal Builder class,
109 since it uses <tt>instance_eval</tt> when running blocks. This cleans
110 up the appearance of the Markaby code you write. If <tt>instance_eval</tt>
111 was not used, the code would look like this:
112
113 mab = Markaby::Builder.new
114 mab.html do
115 mab.head { mab.title "Boats.com" }
116 mab.body do
117 mab.h1 "Boats.com has great deals"
118 end
119 end
120 puts mab.to_s
121
122 So, the advantage is the cleanliness of your code. The disadvantage is that
123 the block will run inside the Markaby::Builder object's scope. This means
124 that inside these blocks, <tt>self</tt> will be your Markaby::Builder object.
125 When you use instance variables in these blocks, they will be instance variables
126 of the Markaby::Builder object.
127
fea7766 @tim * CHANGELOG: correct string escaping usage
tim authored Oct 9, 2006
128 This doesn't affect Rails users, but when used in regular Ruby code, it can
ca39d2f * tools/rakehelp.rb: Rake convenience methods ripped from mongrel.
_why authored Feb 2, 2006
129 be a bit disorienting. You are recommended to put your Markaby code in a
130 module where it won't mix with anything.
131
7f73c14 * README: updated all rdoc and package docs to 0.5 and its conventions.
_why authored Oct 3, 2006
132 = The Six Steps of Markaby
ca39d2f * tools/rakehelp.rb: Rake convenience methods ripped from mongrel.
_why authored Feb 2, 2006
133
134 If you dive right into Markaby, it'll probably make good sense, but you're
7f73c14 * README: updated all rdoc and package docs to 0.5 and its conventions.
_why authored Oct 3, 2006
135 likely to run into a few kinks. Why not review these six steps and commit
136 them memory so you can really *know* what you're doing?
ca39d2f * tools/rakehelp.rb: Rake convenience methods ripped from mongrel.
_why authored Feb 2, 2006
137
7f73c14 * README: updated all rdoc and package docs to 0.5 and its conventions.
_why authored Oct 3, 2006
138 == 1. Element Classes
ca39d2f * tools/rakehelp.rb: Rake convenience methods ripped from mongrel.
_why authored Feb 2, 2006
139
140 Element classes may be added by hooking methods onto container elements:
f24aaa1 Initial import
_why authored Jan 6, 2006
141
142 div.entry do
143 h2.entryTitle 'Son of WebPage'
144 div.entrySection %{by Anthony}
145 div.entryContent 'Okay, once again, the idea here is ...'
146 end
147
ca39d2f * tools/rakehelp.rb: Rake convenience methods ripped from mongrel.
_why authored Feb 2, 2006
148 Which results in:
149
150 <div class="entry">
151 <h2 class="entryTitle">Son of WebPage</h2>
152 <div class="entrySection">by Anthony</div>
153 <div class="entryContent">Okay, once again, the idea here is ...</div>
154 </div>
155
7f73c14 * README: updated all rdoc and package docs to 0.5 and its conventions.
_why authored Oct 3, 2006
156 == 2. Element IDs
ca39d2f * tools/rakehelp.rb: Rake convenience methods ripped from mongrel.
_why authored Feb 2, 2006
157
158 IDs may be added by the use of bang methods:
159
d341de6 @tim merging in the xhtml-careful branch
tim authored May 29, 2006
160 div.page! {
161 div.content! {
ca39d2f * tools/rakehelp.rb: Rake convenience methods ripped from mongrel.
_why authored Feb 2, 2006
162 h1 "A Short Short Saintly Dog"
d341de6 @tim merging in the xhtml-careful branch
tim authored May 29, 2006
163 }
164 }
ca39d2f * tools/rakehelp.rb: Rake convenience methods ripped from mongrel.
_why authored Feb 2, 2006
165
166 Which results in:
167
168 <div id="page">
169 <div id="content">
170 <h1>A Short Short Saintly Dog</h1>
171 </div>
172 </div>
173
acb563e @smtlaissezfaire Remove trailing whitespace
smtlaissezfaire authored Jun 2, 2010
174 == 3. Validate Your XHTML 1.0 Output
ca39d2f * tools/rakehelp.rb: Rake convenience methods ripped from mongrel.
_why authored Feb 2, 2006
175
7f73c14 * README: updated all rdoc and package docs to 0.5 and its conventions.
_why authored Oct 3, 2006
176 If you'd like Markaby to help you assemble valid XHTML documents,
177 you can use the <tt>xhtml_transitional</tt> or <tt>xhtml_strict</tt>
178 methods in place of the normal <tt>html</tt> tag.
ca39d2f * tools/rakehelp.rb: Rake convenience methods ripped from mongrel.
_why authored Feb 2, 2006
179
180 xhtml_strict do
7f73c14 * README: updated all rdoc and package docs to 0.5 and its conventions.
_why authored Oct 3, 2006
181 head { ... }
182 body { ... }
ca39d2f * tools/rakehelp.rb: Rake convenience methods ripped from mongrel.
_why authored Feb 2, 2006
183 end
184
7f73c14 * README: updated all rdoc and package docs to 0.5 and its conventions.
_why authored Oct 3, 2006
185 This will add the XML instruction and the doctype tag to your document.
186 Also, a character set meta tag will be placed inside your <tt>head</tt>
187 tag.
d341de6 @tim merging in the xhtml-careful branch
tim authored May 29, 2006
188
7f73c14 * README: updated all rdoc and package docs to 0.5 and its conventions.
_why authored Oct 3, 2006
189 Now, since Markaby knows which doctype you're using, it checks a big
d341de6 @tim merging in the xhtml-careful branch
tim authored May 29, 2006
190 list of valid tags and attributes before printing anything.
191
192 >> div :styl => "padding: 10px" do
193 >> img :src => "samorost.jpg"
194 >> end
195 InvalidHtmlError: no such attribute `styl'
196
7f73c14 * README: updated all rdoc and package docs to 0.5 and its conventions.
_why authored Oct 3, 2006
197 Markaby will also make sure you don't use the same element ID twice!
198
199 == 4. Escape or No Escape?
200
201 Markaby uses a simple convention for escaping stuff: if a string
202 is an argument, it gets escaped. If the string is in a block, it
203 doesn't.
204
205 This is handy if you're using something like RedCloth or
206 RDoc inside an element. Pass the string back through the block
207 and it'll skip out of escaping.
208
209 div.comment { RedCloth.new(str).to_html }
210
211 But, if we have some raw text that needs escaping, pass it in
212 as an argument:
213
214 div.comment raw_str
215
216 One caveat: if you have other tags inside a block, the string
217 passed back will be ignored.
218
219 div.comment {
220 div.author "_why"
221 div.says "Torpedoooooes!"
222 "<div>Silence.</div>"
223 }
224
225 The final div above won't appear in the output. You can't mix
226 tag modes like that, friend.
227
228 == 5. Auto-stringification
d341de6 @tim merging in the xhtml-careful branch
tim authored May 29, 2006
229
230 If you end up using any of your Markaby "tags" as a string, the
231 tag won't be output. It'll be up to you to add the new string
232 back into the HTML output.
233
234 This means if you call <tt>to_s</tt>, you'll get a string back.
235
236 div.title { "Rock Bottom" + span(" by Robert Wyatt").to_s }
237
238 But, when you're adding strings in Ruby, <tt>to_s</tt> happens automatically.
239
240 div.title { "Rock Bottom" + span(" by Robert Wyatt") }
241
242 Interpolation works fine.
ca39d2f * tools/rakehelp.rb: Rake convenience methods ripped from mongrel.
_why authored Feb 2, 2006
243
d341de6 @tim merging in the xhtml-careful branch
tim authored May 29, 2006
244 div.title { "Rock Bottom #{span(" by Robert Wyatt")}" }
ca39d2f * tools/rakehelp.rb: Rake convenience methods ripped from mongrel.
_why authored Feb 2, 2006
245
d341de6 @tim merging in the xhtml-careful branch
tim authored May 29, 2006
246 And any other operation you might perform on a string.
ca39d2f * tools/rakehelp.rb: Rake convenience methods ripped from mongrel.
_why authored Feb 2, 2006
247
248 div.menu! \
249 ['5.gets', 'bits', 'cult', 'inspect', '-h'].map do |category|
d341de6 @tim merging in the xhtml-careful branch
tim authored May 29, 2006
250 link_to category
ca39d2f * tools/rakehelp.rb: Rake convenience methods ripped from mongrel.
_why authored Feb 2, 2006
251 end.
252 join( " | " )
253
7f73c14 * README: updated all rdoc and package docs to 0.5 and its conventions.
_why authored Oct 3, 2006
254 == 6. The <tt>tag!</tt> Method
ca39d2f * tools/rakehelp.rb: Rake convenience methods ripped from mongrel.
_why authored Feb 2, 2006
255
256 If you need to force a tag at any time, call <tt>tag!</tt> with the
257 tag name followed by the possible arguments and block. The CssProxy
258 won't work with this technique.
259
260 tag! :select, :id => "country_list" do
261 countries.each do |country|
262 tag! :option, country
263 end
264 end
265
7f73c14 * README: updated all rdoc and package docs to 0.5 and its conventions.
_why authored Oct 3, 2006
266 = A Note About Rails Helpers
267
acb563e @smtlaissezfaire Remove trailing whitespace
smtlaissezfaire authored Jun 2, 2010
268 When used in Rails templates, the Rails helper object is passed into
7f73c14 * README: updated all rdoc and package docs to 0.5 and its conventions.
_why authored Oct 3, 2006
269 Markaby::Builder. When you call helper methods inside Markaby, the output
270 from those methods will be output to the stream. This is incredibly
271 handy, since most Rails helpers output HTML tags.
272
273 head do
274 javascript_include_tag 'prototype'
275 autodiscovery_link_tag
276 end
277
278 However, some methods are designed to give back a String which you can use
279 elsewhere. That's okay! Every method returns a Fragment object, which can
280 be used as a string.
281
282 p { "Total is: #{number_to_human_size @file_bytes}" }
283
284 Also see the Quick Tour above, specifically the stuff about auto-stringification.
285
286 If for any reason you have trouble with fragments, you can just
287 call the <tt>@helpers</tt> object with the method and you'll get
288 the String back and nothing will be output.
289
fea7766 @tim * CHANGELOG: correct string escaping usage
tim authored Oct 9, 2006
290 p { "Total is: #{@helpers.number_to_human_size @file_bytes}" }
7f73c14 * README: updated all rdoc and package docs to 0.5 and its conventions.
_why authored Oct 3, 2006
291
292 Conversely, you may call instance variables from your controller by using
293 a method and its value will be returned, nothing will be output.
294
295 # Inside imaginary ProductController
296 def list
297 @products = Product.find :all
298 end
299
300 # Inside app/views/product/list.mab
301 products.each do |product|
302 p product.title
303 end
304
ca39d2f * tools/rakehelp.rb: Rake convenience methods ripped from mongrel.
_why authored Feb 2, 2006
305 = Credits
306
307 Markaby is a work of immense hope by Tim Fletcher and why the lucky stiff.
ce39a8b @smtlaissezfaire Add credit where credit is due
smtlaissezfaire authored Oct 6, 2009
308 It is maintained by joho, spox, and smtlaissezfaire.
ca39d2f * tools/rakehelp.rb: Rake convenience methods ripped from mongrel.
_why authored Feb 2, 2006
309 Thankyou for giving it a whirl.
310
311 Markaby is inspired by the HTML library within cgi.rb. Hopefully it will
312 turn around and take some cues.
ef5366e littleears - just testing
Kelly Felkins authored Nov 24, 2007
313
5a7daf3 @smtlaissezfaire update contributors
smtlaissezfaire authored Dec 11, 2010
314 == Patches from contributors:
315
316 aredridel (Aria Stewart - aredridel@nbtsc.org)
317 - Make exceptions inherit from StandardError (f259c0)
Something went wrong with that request. Please try again.