chrisjpowers / giftwrap

A Rails plugin leveraging Ruby blocks to DRY up and modularize views using wrapper classes. 

Fixed a couple Rdoc formatting issues.
chrisjpowers (author)
Mon Jun 09 12:43:35 -0700 2008
commit  4de0695e7ec9b476b3ba624a1812e4656d616ea1
tree    1f7039f45ef799a55368460625ee63c07d5175ef
parent  a5e66ed3f90f793aba2105fd72fcb45422cf9d36
giftwrap / README.rdoc
raw normal view history
f40c24f3 » chrisjpowers 2008-06-02 Changed README file to rdoc... 1 == GiftWrap
2
900d4a3a » chrisjpowers 2008-06-02 Formatting tweaks to README. 3 <em>Developed by Chris Powers, The Killswitch Collective (http://killswitchcollective.com) 06/01/2008</em>
f40c24f3 » chrisjpowers 2008-06-02 Changed README file to rdoc... 4
5 The GiftWrap class is meant to be subclassed by the developer to allow for
6 the easy creation and implementation of Helper Wrapper classes. Here's the
7 three steps to creating your own wrapper classes.
8
a5e66ed3 » chrisjpowers 2008-06-09 GiftWrap can now wrap block... 9 1. Create a class that subclasses GiftWrap
4de0695e » chrisjpowers 2008-06-09 Fixed a couple Rdoc formatt... 10 2. You may pass a partial's name as a string to the +use_partial+ method. The block will be available as the 'body' local variable within your partial. The instance of GiftWrap will be available as the <tt>:object</tt> in the partial.
a5e66ed3 » chrisjpowers 2008-06-09 GiftWrap can now wrap block... 11 3. You may pass a list of method names (or Proc objects, or simply strings) to the +before_yield+ and +after_yield+ class methods to determine what will be called at the beginning and end of your block. These methods can be used instead of, or in conjunction with, the +use_partial+ method.
12 4. Use the dynamically created wrapper helper method in your views to initialize and use your class. For example, if your class is named +RoundCornerBox+, the method +round_corner_box+ will be dynamically created and will accept the same parameters as your class' +initialize+ method.
f40c24f3 » chrisjpowers 2008-06-02 Changed README file to rdoc... 13
14 +ActionView+ helper methods can be used within a +GiftWrap+ subclass transparently.
15
a5e66ed3 » chrisjpowers 2008-06-09 GiftWrap can now wrap block... 16 === Example of subclassing +GiftWrap+ with +use_partial+:
17
18 class RoundCornerBox < GiftWrap
19 use_partial 'shared/round_corner_box'
20
21 attr_reader :name, :header
22
23 # A new instance of RoundCornerBox will be instantiated each time the
24 # dynamic round_corner_box is called in the view. The arguments passed into
25 # the helper method are passed on directly to the initialize method.
26 def initialize(name, options={})
27 @name = name
28 @header = options[:header]
29 end
30
31 # # # These methods can be used within your wrapper block and partial. # # #
32
33 def subheader(text)
34 "<h4 class='subheader'>#{text}</h4>"
35 end
36
37 def more_button(text, url)
38 "<p class='more_button'>#{link_to text, url}</p>"
39 end
40 end
41
4de0695e » chrisjpowers 2008-06-09 Fixed a couple Rdoc formatt... 42 === Example of the <tt>shared/_round_corner_box.html.erb</tt> partial file:
a5e66ed3 » chrisjpowers 2008-06-09 GiftWrap can now wrap block... 43
44 <pre>
45 <% if round_corner_box.header %>
46 <h3 class='round_corner_box_header'><%= round_corner_box.header %></h3>
47 <% end %>
48 <div class="round_corner_box_top">
49 <div class="round_corner_box_bottom" id="<%= round_corner_box.name %>_round_corner_box">
50 <%= body %>
51 </div>
52 </div>
53 </pre>
54
55 === Example of subclassing +GiftWrap+ with +before_yield+ and +after_yield+:
f40c24f3 » chrisjpowers 2008-06-02 Changed README file to rdoc... 56
57 class RoundCornerBox < GiftWrap
58 before_yield :header, :open_divs
59 after_yield :close_divs
60
61 # A new instance of RoundCornerBox will be instantiated each time the
62 # dynamic round_corner_box is called in the view. The arguments passed into
63 # the helper method are passed on directly to the initialize method.
64 def initialize(name, options={})
65 @name = name
66 @header = options[:header]
67 end
68
69 # # # These methods can be used within your wrapper block. # # #
70
71 def subheader(text)
72 "<h4 class='subheader'>#{text}</h4>"
73 end
74
75 def more_button(text, url)
76 "<p class='more_button'>#{link_to text, url}</p>"
77 end
78
79 private
80
81 # # # These methods will only be used internally for creating the wrapper markup. # # #
82
83 def header
84 @header ? "<h3 class='round_corner_box_header'>#{@header}</h3>" : ''
85 end
86
87 def open_divs
88 %Q{
89 <div class="round_corner_box_top">
90 <div class="round_corner_box_bottom" id="#{@name}_round_corner_box">
91 }
92 end
93
94 def close_divs
95 "</div>\n</div>"
96 end
97 end
98
99 === Example of using this +GiftWrap+ subclass in the view:
100
101 <% round_corner_box :news, :header => "Today's News" do |b| %>
102 <%= b.subheader "Top Story" %>
103 <p>Today was a very exciting day in the news...</p>
104 <%= b.more_button "Full Story", top_story_path %>
105
106 <%= b.subheader "Lesser Story" %>
107 <p>This story is definitely less important than the top story...</p>
108 <%= b.more_button "Full Story", bottom_story_path %>
109 <% end %>