mab 0.0.1 → 0.0.2

Sign up to get free protection for your applications and to get access to all the features.
Files changed (88) hide show
  1. data/COPYING +19 -0
  2. data/Gemfile +10 -0
  3. data/Gemfile.lock +12 -0
  4. data/README.md +224 -0
  5. data/Rakefile +8 -0
  6. data/bench.rb +37 -0
  7. data/lib/mab/mixin.rb +58 -42
  8. data/lib/mab/version.rb +1 -1
  9. data/mab-0.0.1.gem +0 -0
  10. data/mab.gemspec +20 -0
  11. data/markaby/CHANGELOG.rdoc +106 -0
  12. data/markaby/Markaby.gemspec +109 -0
  13. data/markaby/README.rdoc +317 -0
  14. data/markaby/Rakefile +78 -0
  15. data/markaby/VERSION +1 -0
  16. data/markaby/garlic.rb +29 -0
  17. data/markaby/init.rb +6 -0
  18. data/markaby/lib/markaby.rb +30 -0
  19. data/markaby/lib/markaby/builder.rb +314 -0
  20. data/markaby/lib/markaby/builder_tags.rb +64 -0
  21. data/markaby/lib/markaby/cssproxy.rb +55 -0
  22. data/markaby/lib/markaby/kernel_method.rb +7 -0
  23. data/markaby/lib/markaby/rails.rb +75 -0
  24. data/markaby/lib/markaby/rails/current.rb +85 -0
  25. data/markaby/lib/markaby/rails/deprecated.rb +124 -0
  26. data/markaby/lib/markaby/rails/rails_builder.rb +91 -0
  27. data/markaby/lib/markaby/sinatra.rb +18 -0
  28. data/markaby/lib/markaby/tags.rb +200 -0
  29. data/markaby/lib/markaby/tilt.rb +8 -0
  30. data/markaby/spec/markaby/builder_spec.rb +118 -0
  31. data/markaby/spec/markaby/css_proxy_test.rb +47 -0
  32. data/markaby/spec/markaby/fragment_test.rb +10 -0
  33. data/markaby/spec/markaby/markaby_other_static.mab +1 -0
  34. data/markaby/spec/markaby/markaby_spec.rb +184 -0
  35. data/markaby/spec/markaby/markaby_test.rb +251 -0
  36. data/markaby/spec/markaby/rails/spec_helper.rb +29 -0
  37. data/markaby/spec/markaby/rails/views/layouts/layout.mab +11 -0
  38. data/markaby/spec/markaby/rails/views/markaby/_a_partial.mab +3 -0
  39. data/markaby/spec/markaby/rails/views/markaby/_form_for_with_body_in_erb.erb +1 -0
  40. data/markaby/spec/markaby/rails/views/markaby/_partial_child_with_locals.mab +1 -0
  41. data/markaby/spec/markaby/rails/views/markaby/access_to_helpers.mab +1 -0
  42. data/markaby/spec/markaby/rails/views/markaby/broken.mab +7 -0
  43. data/markaby/spec/markaby/rails/views/markaby/commented_out_template.mab +1 -0
  44. data/markaby/spec/markaby/rails/views/markaby/correct_template_values.mab +5 -0
  45. data/markaby/spec/markaby/rails/views/markaby/double_output.mab +8 -0
  46. data/markaby/spec/markaby/rails/views/markaby/form_for.mab +2 -0
  47. data/markaby/spec/markaby/rails/views/markaby/form_for_with_fields.mab +3 -0
  48. data/markaby/spec/markaby/rails/views/markaby/form_for_with_multiple_fields.mab +4 -0
  49. data/markaby/spec/markaby/rails/views/markaby/no_values_passed.mab +3 -0
  50. data/markaby/spec/markaby/rails/views/markaby/partial_parent.mab +1 -0
  51. data/markaby/spec/markaby/rails/views/markaby/partial_parent_with_locals.mab +7 -0
  52. data/markaby/spec/markaby/rails/views/markaby/render_erb_without_explicit_render_call.erb +1 -0
  53. data/markaby/spec/markaby/rails/views/markaby/render_explicit_but_empty_markaby_layout.mab +0 -0
  54. data/markaby/spec/markaby/rails/views/markaby/render_mab_without_explicit_render_call.mab +3 -0
  55. data/markaby/spec/markaby/rails/views/markaby/render_with_ivar.mab +3 -0
  56. data/markaby/spec/markaby/rails/views/markaby/renders_erb.rhtml +1 -0
  57. data/markaby/spec/markaby/rails/views/markaby/renders_form_for_with_erb_body.mab +3 -0
  58. data/markaby/spec/markaby/rails/views/markaby/routes.mab +1 -0
  59. data/markaby/spec/markaby/rails/views/markaby/yielding.mab +3 -0
  60. data/markaby/spec/markaby/rails/views/markaby/yielding_content_for_with_block_helper.mab +5 -0
  61. data/markaby/spec/markaby/rails/views/markaby/yielding_two.mab +7 -0
  62. data/markaby/spec/markaby/rails/views/markaby/yielding_with_content_for.mab +3 -0
  63. data/markaby/spec/markaby/rails_test.rb +380 -0
  64. data/markaby/spec/markaby/rails_version_spec.rb +37 -0
  65. data/markaby/spec/markaby/sinatra/app.rb +49 -0
  66. data/markaby/spec/markaby/sinatra/sinatra_spec.rb +67 -0
  67. data/markaby/spec/markaby/sinatra/views/helpers.mab +1 -0
  68. data/markaby/spec/markaby/sinatra/views/layout.mab +7 -0
  69. data/markaby/spec/markaby/sinatra/views/markaby_template.mab +0 -0
  70. data/markaby/spec/markaby/sinatra/views/scope_instance_variables.mab +3 -0
  71. data/markaby/spec/markaby/sinatra/views/simple_html.mab +4 -0
  72. data/markaby/spec/markaby/sinatra/views/variables.mab +3 -0
  73. data/markaby/spec/markaby/tilt/erb.erb +1 -0
  74. data/markaby/spec/markaby/tilt/locals.mab +1 -0
  75. data/markaby/spec/markaby/tilt/markaby.mab +1 -0
  76. data/markaby/spec/markaby/tilt/markaby_other_static.mab +1 -0
  77. data/markaby/spec/markaby/tilt/render_twice.mab +1 -0
  78. data/markaby/spec/markaby/tilt/scope.mab +1 -0
  79. data/markaby/spec/markaby/tilt/yielding.mab +2 -0
  80. data/markaby/spec/markaby/tilt_spec.rb +75 -0
  81. data/markaby/spec/spec.opts +2 -0
  82. data/markaby/spec/spec_helper.rb +44 -0
  83. data/test/helper.rb +4 -0
  84. data/test/test_mab_builder.rb +56 -0
  85. data/test/test_mab_indentation.rb +66 -0
  86. data/test/test_mab_kernel_method.rb +10 -0
  87. data/test/test_mab_mixin.rb +246 -0
  88. metadata +92 -6
data/lib/mab/version.rb CHANGED
@@ -1,4 +1,4 @@
1
1
  module Mab
2
- VERSION = "0.0.1"
2
+ VERSION = "0.0.2"
3
3
  end
4
4
 
data/mab-0.0.1.gem ADDED
Binary file
data/mab.gemspec ADDED
@@ -0,0 +1,20 @@
1
+ # -*- encoding: utf-8 -*-
2
+ require File.dirname(__FILE__) + '/lib/mab/version'
3
+ require 'date'
4
+
5
+ Gem::Specification.new do |s|
6
+ s.name = 'mab'
7
+ s.version = Mab::VERSION
8
+ s.date = Date.today.to_s
9
+
10
+ s.authors = ['Magnus Holm']
11
+ s.email = ['judofyr@gmail.com']
12
+ s.summary = 'Markup as Ruby'
13
+
14
+ s.require_paths = %w(lib)
15
+ s.files = Dir["**/*"]
16
+
17
+ s.add_development_dependency('rake')
18
+ s.add_development_dependency('minitest')
19
+ end
20
+
data/markaby/CHANGELOG.rdoc ADDED
@@ -0,0 +1,106 @@
1
+ = 0.7.1 (2010-08-19)
2
+
3
+ * Rails fixes for form_for called from erb templates
4
+
5
+ = 0.7.0
6
+
7
+ * Sinatra 1.0 support
8
+ * Full Tilt 1.0+ support, including "yield" support for layouts
9
+
10
+ = 0.6.10
11
+
12
+ * Rails fixes for form_for + content_for
13
+
14
+ = 0.6.9
15
+
16
+ * Bug fix for url_for. Previously, you'd need to capture { *_path } instead of
17
+ using the named route directly. Only affected rails 2.3.4+.
18
+
19
+ = 0.6.8 (2010-06-03)
20
+
21
+ * Add a regression for issue Github #17 (for judofyr / Camping)
22
+
23
+ = 0.6.7 (2010-06-02)
24
+
25
+ * Add rails support for 2.3.5 - 2.3.8
26
+ * Improved rails documentation
27
+
28
+ = 0.6.6 (2010-06-01)
29
+
30
+ * ruby 1.9.1 support. Closes Github Issues #10 & #11.
31
+ * Removed Tilt deprecation warnings
32
+
33
+ = 0.6.4
34
+
35
+ * Fixed a bug in which direct string values to Markaby::Builder wouldn't evaluate:
36
+ Markaby::Builder.new { 'foo' }.to_s #=> "foo"
37
+
38
+ * Fix critical bug with form_for, which was raising an error
39
+ * Introduce proxy object for form_for:
40
+
41
+ form_for :foo do |f|
42
+ f.text_field :bar
43
+ f.text_field :baz
44
+ end
45
+
46
+ * Remove support for rails 2.1.x series. We'll accept patches for them, if anyone cares enough.
47
+
48
+ == 0.6.2 / 0.6.3
49
+
50
+ * Add basic support for the Tilt templating engine (used with Sinatra):
51
+
52
+ require 'markaby'
53
+ require 'markaby/tilt'
54
+
55
+ == 0.6.1
56
+
57
+ * Support the following rails versions:
58
+ 1.2.2, 1.2.3, 1.2.4, 1.2.5, 1.2.6, 2.1.0, 2.1.1, 2.1.2, 2.2.0,
59
+ 2.2.1, 2.2.2, 2.2.3, 2.3.1, 2.3.2, 2.3.2.1, 2.3.3, 2.3.3.1, 2.3.4
60
+ * Only run rails tests when inside a rails plugins
61
+ * Run tests of the various versions of rails with garlic
62
+ * Start conversion to rspec. Use test/spec temporarily until conversion is done.
63
+
64
+ = 0.6
65
+ === 23 August, 2009
66
+
67
+ * Canonical repo changed to http://github.com/joho/markaby
68
+ * Gem moved to Github (using jeweler)
69
+ * Rails init process changed to work with rails > 2.1
70
+ * Default attributes on the root (<html>) element can now be overidden
71
+ * Reworked CssProxy, allowing attributes on hr and br
72
+ * Added Kernel#mab convenience method (require 'markaby/kernel_method')
73
+ * WhenOnRails: Can now use :locals with render_markaby
74
+ * WhenOnRails: Template errors now report line number
75
+
76
+ = 0.5
77
+ === 03 October, 2006
78
+
79
+ * XHTML Validation built in. So, if you have an invalid tag: error. Invalid attribute: error.
80
+ And two identical IDs in the same document: error. Optional, of course. But handy!
81
+ * New Markaby::Fragment class adds much flexibility. If it discovers you are using a tag as a string,
82
+ the tag is removed from the stream. (<tt>div { strong("Real") + " Giraffes" }</tt>)
83
+ * The prevailing rule now is: if you want it escaped, pass it as an arg. If not, pass it to a block.
84
+ * Again, escaped: <tt>h1("Me & You Have a Giraffe")</tt>
85
+ * And, not escaped: <tt>h1 { "<a href='/'>Home</a>" }</tt>
86
+ * Less method_missing, meaning: faster calls all around. Tag methods generated based on doctype.
87
+ * The <tt>html</tt> method doesn't write the doctype tags and meta tags. You must use <tt>xhtml_transitional</tt> or <tt>xhtml_strict</tt> methods to do that.
88
+ * The <tt>img</tt> method doesn't try to inject an empty alt tag and a zero border. No more of that.
89
+
90
+ = 0.3
91
+ === 02nd February, 2006
92
+
93
+ * Allow Markaby::Builder.new without args.
94
+ * Rails helper method render_markaby.
95
+
96
+ = 0.2
97
+ === 17th January, 2006
98
+
99
+ * Public announcement.
100
+ * DOCTYPES, head tags.
101
+ * Works with Rails helpers.
102
+
103
+ = 0.1
104
+ === 05th January, 2006
105
+
106
+ * Initial import.
data/markaby/Markaby.gemspec ADDED
@@ -0,0 +1,109 @@
1
+ # Generated by jeweler
2
+ # DO NOT EDIT THIS FILE DIRECTLY
3
+ # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
4
+ # -*- encoding: utf-8 -*-
5
+
6
+ Gem::Specification.new do |s|
7
+ s.name = %q{markaby}
8
+ s.version = "0.7.2"
9
+
10
+ s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
11
+ s.authors = [%q{_why}, %q{Tim Fletcher}, %q{John Barton}, %q{spox}, %q{smtlaissezfaire}]
12
+ s.date = %q{2011-08-23}
13
+ s.description = %q{Tim Fletcher and _why's ruby driven HTML templating system}
14
+ s.email = %q{scott@railsnewbie.com}
15
+ s.extra_rdoc_files = [
16
+ "README.rdoc"
17
+ ]
18
+ s.files = [
19
+ "CHANGELOG.rdoc",
20
+ "Markaby.gemspec",
21
+ "README.rdoc",
22
+ "Rakefile",
23
+ "VERSION",
24
+ "garlic.rb",
25
+ "init.rb",
26
+ "lib/markaby.rb",
27
+ "lib/markaby/builder.rb",
28
+ "lib/markaby/builder_tags.rb",
29
+ "lib/markaby/cssproxy.rb",
30
+ "lib/markaby/kernel_method.rb",
31
+ "lib/markaby/rails.rb",
32
+ "lib/markaby/rails/current.rb",
33
+ "lib/markaby/rails/deprecated.rb",
34
+ "lib/markaby/rails/rails_builder.rb",
35
+ "lib/markaby/sinatra.rb",
36
+ "lib/markaby/tags.rb",
37
+ "lib/markaby/tilt.rb",
38
+ "spec/markaby/builder_spec.rb",
39
+ "spec/markaby/css_proxy_test.rb",
40
+ "spec/markaby/fragment_test.rb",
41
+ "spec/markaby/markaby_other_static.mab",
42
+ "spec/markaby/markaby_spec.rb",
43
+ "spec/markaby/markaby_test.rb",
44
+ "spec/markaby/rails/spec_helper.rb",
45
+ "spec/markaby/rails/views/layouts/layout.mab",
46
+ "spec/markaby/rails/views/markaby/_a_partial.mab",
47
+ "spec/markaby/rails/views/markaby/_form_for_with_body_in_erb.erb",
48
+ "spec/markaby/rails/views/markaby/_partial_child_with_locals.mab",
49
+ "spec/markaby/rails/views/markaby/access_to_helpers.mab",
50
+ "spec/markaby/rails/views/markaby/broken.mab",
51
+ "spec/markaby/rails/views/markaby/commented_out_template.mab",
52
+ "spec/markaby/rails/views/markaby/correct_template_values.mab",
53
+ "spec/markaby/rails/views/markaby/double_output.mab",
54
+ "spec/markaby/rails/views/markaby/form_for.mab",
55
+ "spec/markaby/rails/views/markaby/form_for_with_fields.mab",
56
+ "spec/markaby/rails/views/markaby/form_for_with_multiple_fields.mab",
57
+ "spec/markaby/rails/views/markaby/no_values_passed.mab",
58
+ "spec/markaby/rails/views/markaby/partial_parent.mab",
59
+ "spec/markaby/rails/views/markaby/partial_parent_with_locals.mab",
60
+ "spec/markaby/rails/views/markaby/render_erb_without_explicit_render_call.erb",
61
+ "spec/markaby/rails/views/markaby/render_explicit_but_empty_markaby_layout.mab",
62
+ "spec/markaby/rails/views/markaby/render_mab_without_explicit_render_call.mab",
63
+ "spec/markaby/rails/views/markaby/render_with_ivar.mab",
64
+ "spec/markaby/rails/views/markaby/renders_erb.rhtml",
65
+ "spec/markaby/rails/views/markaby/renders_form_for_with_erb_body.mab",
66
+ "spec/markaby/rails/views/markaby/routes.mab",
67
+ "spec/markaby/rails/views/markaby/yielding.mab",
68
+ "spec/markaby/rails/views/markaby/yielding_content_for_with_block_helper.mab",
69
+ "spec/markaby/rails/views/markaby/yielding_two.mab",
70
+ "spec/markaby/rails/views/markaby/yielding_with_content_for.mab",
71
+ "spec/markaby/rails_test.rb",
72
+ "spec/markaby/rails_version_spec.rb",
73
+ "spec/markaby/sinatra/app.rb",
74
+ "spec/markaby/sinatra/sinatra_spec.rb",
75
+ "spec/markaby/sinatra/views/helpers.mab",
76
+ "spec/markaby/sinatra/views/layout.mab",
77
+ "spec/markaby/sinatra/views/markaby_template.mab",
78
+ "spec/markaby/sinatra/views/scope_instance_variables.mab",
79
+ "spec/markaby/sinatra/views/simple_html.mab",
80
+ "spec/markaby/sinatra/views/variables.mab",
81
+ "spec/markaby/tilt/erb.erb",
82
+ "spec/markaby/tilt/locals.mab",
83
+ "spec/markaby/tilt/markaby.mab",
84
+ "spec/markaby/tilt/markaby_other_static.mab",
85
+ "spec/markaby/tilt/render_twice.mab",
86
+ "spec/markaby/tilt/scope.mab",
87
+ "spec/markaby/tilt/yielding.mab",
88
+ "spec/markaby/tilt_spec.rb",
89
+ "spec/spec.opts",
90
+ "spec/spec_helper.rb"
91
+ ]
92
+ s.homepage = %q{http://markaby.github.com/markaby/}
93
+ s.require_paths = [%q{lib}]
94
+ s.rubygems_version = %q{1.8.6}
95
+ s.summary = %q{Markup as Ruby, write HTML in your native Ruby tongue}
96
+
97
+ if s.respond_to? :specification_version then
98
+ s.specification_version = 3
99
+
100
+ if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
101
+ s.add_runtime_dependency(%q<builder>, [">= 2.0.0"])
102
+ else
103
+ s.add_dependency(%q<builder>, [">= 2.0.0"])
104
+ end
105
+ else
106
+ s.add_dependency(%q<builder>, [">= 2.0.0"])
107
+ end
108
+ end
109
+
data/markaby/README.rdoc ADDED
@@ -0,0 +1,317 @@
1
+ = Markaby (Markup as Ruby)
2
+
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
+
8
+ == Using Markaby as a Rails plugin / gem
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
17
+
18
+ body do
19
+ p flash[:notice], :style => "color: green"
20
+
21
+ div.signup! do
22
+ form_for @user do |f|
23
+ f.text_field :email
24
+ end
25
+ end
26
+
27
+ yield
28
+ end
29
+ end
30
+
31
+ Markaby templates end in .mab
32
+
33
+ Markaby supports many versions of rails, including the latest rails:
34
+
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,
37
+ 2.3.3, 2.3.3.1, 2.3.4, 2.3.5, 2.3.6, 2.3.7,
38
+ 2.3.8
39
+
40
+ Rails 3.0 support is planned.
41
+
42
+ === Install it as a plugin
43
+
44
+ script/plugin install git://github.com/markaby/markaby.git
45
+
46
+ === Install it as a gem
47
+
48
+ gem install markaby
49
+
50
+ If you are loading it in a different way (from a gem), make sure
51
+ it's on the $LOAD_PATH, and add the following in
52
+ an initializer (config/initializers/markaby.rb will work):
53
+
54
+ require 'markaby'
55
+ require 'markaby/rails'
56
+
57
+ Markaby::Rails.load
58
+
59
+ Or, you could try config.gem, but that's now known as a bad idea.
60
+
61
+
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
+
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
79
+
80
+
81
+ == Using Markaby as a Ruby class
82
+
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
+
128
+ This doesn't affect Rails users, but when used in regular Ruby code, it can
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
+
132
+ = The Six Steps of Markaby
133
+
134
+ If you dive right into Markaby, it'll probably make good sense, but you're
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?
137
+
138
+ == 1. Element Classes
139
+
140
+ Element classes may be added by hooking methods onto container elements:
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
+
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
+
156
+ == 2. Element IDs
157
+
158
+ IDs may be added by the use of bang methods:
159
+
160
+ div.page! {
161
+ div.content! {
162
+ h1 "A Short Short Saintly Dog"
163
+ }
164
+ }
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
+
174
+ == 3. Validate Your XHTML 1.0 Output
175
+
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.
179
+
180
+ xhtml_strict do
181
+ head { ... }
182
+ body { ... }
183
+ end
184
+
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.
188
+
189
+ Now, since Markaby knows which doctype you're using, it checks a big
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
+
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
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.
243
+
244
+ div.title { "Rock Bottom #{span(" by Robert Wyatt")}" }
245
+
246
+ And any other operation you might perform on a string.
247
+
248
+ div.menu! \
249
+ ['5.gets', 'bits', 'cult', 'inspect', '-h'].map do |category|
250
+ link_to category
251
+ end.
252
+ join( " | " )
253
+
254
+ == 6. The <tt>tag!</tt> Method
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
+
266
+ = A Note About Rails Helpers
267
+
268
+ When used in Rails templates, the Rails helper object is passed into
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
+
290
+ p { "Total is: #{@helpers.number_to_human_size @file_bytes}" }
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
+
305
+ = Credits
306
+
307
+ Markaby is a work of immense hope by Tim Fletcher and why the lucky stiff.
308
+ It is maintained by joho, spox, and smtlaissezfaire.
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.
313
+
314
+ == Patches from contributors:
315
+
316
+ aredridel (Aria Stewart - aredridel@nbtsc.org)
317
+ - Make exceptions inherit from StandardError (f259c0)