Permalink
Browse files

improve documentation

  • Loading branch information...
1 parent e6308a4 commit cb01e061f9ed8970c5f9a5a222c428b853766a9d @alexch alexch committed Oct 6, 2011
Showing with 101 additions and 37 deletions.
  1. +1 −1 web/developers.rb
  2. +2 −2 web/example.rb
  3. +37 −0 web/rails.html
  4. +14 −11 web/rails.rb
  5. +19 −2 web/release_notes.html
  6. +5 −0 web/section.rb
  7. +2 −2 web/source.rb
  8. +21 −19 web/userguide.rb
View
@@ -61,7 +61,7 @@ def body_content
pre "git clone git@github.com:pivotal/erector.git"
p "To push your changes back to the main git repository:"
- source :sh, <<END
+ source_code :sh, <<END
git commit -a
git pull
# Deal with merge issues if any.
View
@@ -7,15 +7,15 @@ def example ruby, html
table {
tr {
td.before {
- source :ruby, ruby
+ source_code :ruby, ruby
}
td.separator {
span.separator {
text character(:rightwards_arrow)
}
}
td.after {
- source :html, html
+ source_code :html, html
}
}
}
View
@@ -239,6 +239,7 @@ <h1 class="name">Erector On Rails</h1>
<li><a href="#tool">Erector tool: Command-line conversion to and from HTML</a></li>
<li><a href="#pagelayoutinheritance">Page Layout Inheritance</a></li>
<li><a href="#erectorlayoutsinrails">Erector Layouts in Rails</a></li>
+ <li><a href="#instancevariables">Instance Variables</a></li>
</ol>
</div>
<div class="clear"></div>
@@ -456,6 +457,42 @@ <h1 class="name">Erector On Rails</h1>
</pre>
<p>[TODO: more explanation]</p>
</p>
+ <a name="instancevariables"></a>
+ <h2>6. Instance Variables</h2>
+ <p>Controller instance variables (sometimes called &quot;assigns&quot;) are available to
+the view, and also to any partial
+that gets rendered by the view, no matter how deeply-nested. This effectively
+makes controller instance variables &quot;globals&quot;. In small view hierarchies this
+probably isn't an issue, but in large ones it can make debugging and
+reasoning about the code very difficult.
+</p>
+ <p>Often, large Rails applications will assign many controller instance variables.
+Sometimes these aren't used by a view: ApplicationController might assign
+variables that are used by many, but not all, views; and various other things
+may accumulate, especially if you've been using templating systems that are
+more forgiving than Erector. Erector's &quot;needs&quot; mechanism helps enforce
+stricter encapsulation. But if you migrate from a promiscuous Rails app
+to Erector, you're stuck using
+no &quot;needs&quot; declaration at all, because it needs to contain every assigned
+variable, or Erector will raise an exception.
+</p>
+ <p>Two widget-class-level settings can help you with these problems.</p>
+ <h3>controller_assigns_propagate_to_partials</h3>
+ <p>If you set this to true (and it's inherited through to subclasses), then any
+widget that's getting rendered as a partial will only have access to locals
+explicitly passed to it (render :partial =&gt; ..., :locals =&gt; ...). (This
+doesn't change the behavior of widgets that are explicitly rendered, as they
+don't have this issue.) This can allow for cleaner encapsulation of partials,
+as they must be passed everything they use and can't rely on controller
+instance variables.
+</p>
+ <h3>ignore_extra_controller_assigns</h3>
+ <p>If you set this to true (and it's inherited through to subclasses), however,
+then &quot;needs&quot; declarations on the widget will cause excess controller variables
+to be ignored -- they'll be unavailable to the widget (so 'needs' still means
+something), but they won't cause widget instantiation to fail, either. This
+can let a large Rails project transition to Erector more smoothly.
+</p>
</div>
</div>
</div>
View
@@ -3,8 +3,11 @@
require "#{dir}/navbar"
require "#{dir}/article"
require "#{dir}/section"
+require "#{dir}/source"
class Rails < Page
+ include Source
+
def initialize
super(:page_title => "Erector On Rails")
end
@@ -38,7 +41,7 @@ def article
"When installing this way, erector is automatically available to your Rails code (no require directive is needed)."
}
end
-
+
a.add(:name => "Using Erector from Ruby on Rails", :href => "rails") do
p do
text "Your views are just ruby classes. Your controller can either call Rails' "
@@ -49,7 +52,7 @@ def article
p "For example:"
code "app/controllers/welcome_controller.rb:"
- source :ruby, <<-DONE
+ source_code :ruby, <<-DONE
class WelcomeController < ApplicationController
def index
render :template => 'welcome/show'
@@ -58,7 +61,7 @@ def index
DONE
code "app/views/welcome/show.rb:"
- source :ruby, <<-DONE
+ source_code :ruby, <<-DONE
class Views::Welcome::Show < Erector::Widget
def content
html {
@@ -111,7 +114,7 @@ def content
p "Here's a little command-line howto for erecting a scaffold Rails app:"
- source :sh, <<-DONE
+ source_code :sh, <<-DONE
# create a toy Rails app
rails foo
cd foo
@@ -150,7 +153,7 @@ def content
p do
text "For example:"
- source :ruby, <<-DONE
+ source_code :ruby, <<-DONE
class Views::Layouts::Page < Erector::Widget
def content
html {
@@ -186,7 +189,7 @@ def footer
end
DONE
- source :ruby, <<-DONE
+ source_code :ruby, <<-DONE
class Views::Faq::Index < Views::Layouts::Page
def initialize
super(:page_title => "FAQ")
@@ -238,7 +241,7 @@ def navbar
text "To use an Erector widget as a regular Rails layout, you'll have to set things up a bit differently."
br
code "app/views/layouts/application.rb:"
- source :ruby, <<-RUBY
+ source_code :ruby, <<-RUBY
class Views::Layouts::Application < Erector::Widget
def content
html {
@@ -278,7 +281,7 @@ def footer
br
code "app/views/faq/index.rb:"
- source :ruby, <<-RUBY
+ source_code :ruby, <<-RUBY
class Views::Faq::Index < Erector::Widget
def content
content_for :navbar do
@@ -296,7 +299,7 @@ def content
end
end
- a.add(:title => "Instance Variables") do
+ a.add(:name => "Instance Variables") do
p <<-TEXT
Controller instance variables (sometimes called "assigns") are available to
the view, and also to any partial
@@ -332,7 +335,7 @@ def content
instance variables.
TEXT
- example
+ # example
h3 "ignore_extra_controller_assigns"
@@ -343,8 +346,8 @@ def content
something), but they won't cause widget instantiation to fail, either. This
can let a large Rails project transition to Erector more smoothly.
TEXT
-
+ end
}
end
end
View
@@ -249,7 +249,7 @@
</p>
</li>
<li><p>
-&#8216;render&#8217; method as preferred synonym for to_html (since we now
+&#8216;emit&#8217; method as preferred synonym for to_html (since we now
support non-HTML widgets)
</p>
</li>
@@ -266,6 +266,11 @@
remove dependency on rake gem
</p>
</li>
+<li><p>
+rename &#8216;render&#8217; method to &#8216;emit&#8217; (to reduce
+confusion with Rails&#8217; &#8220;render&#8221; methods)
+</p>
+</li>
</ul>
<p>
Deprecated or Removed:
@@ -288,7 +293,19 @@
</p>
</li>
<li><p>
-to_s &#8212; use render or to_html instead
+to_s &#8212; use emit or to_html instead
+</p>
+</li>
+<li><p>
+join &#8212; use the :join option instead
+</p>
+</li>
+</ul>
+<h2>0.8.3</h2>
+<ul>
+<li><p>
+Finally merged bigfix/rails3 branch - Erector now works with either Rails 2
+or Rails 3 (or neither)
</p>
</li>
</ul>
View
@@ -1,4 +1,9 @@
+dir = File.dirname(__FILE__)
+require "#{dir}/source"
+
class Section < Erector::InlineWidget
+ include Source # todo: make it not an InlineWidget after all
+
needs :name, :href => nil, :sections => []
attr_reader :name, :sections
View
@@ -5,8 +5,8 @@ def self.included into
into.external :css, "css/sh_style.css"
end
- def source lang, source_code
+ def source_code lang, text
sh_lang = "sh_#{lang}"
- pre source_code, :class => sh_lang
+ pre text, :class => sh_lang
end
end
Oops, something went wrong.

0 comments on commit cb01e06

Please sign in to comment.