Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 116 lines (69 sloc) 3.673 kB
d271843 @floere + modernized README
authored
1 h1. Contexts
2
1a4fa13 @floere Edited README.textile via GitHub
authored
3 *A Rails 2 Plugin. This plugin is a simple alternative for components*.
d271843 @floere + modernized README
authored
4
1a4fa13 @floere Edited README.textile via GitHub
authored
5 Feedback please to @florian.hanke+contexts at gmail.com@, thanks! :)
d271843 @floere + modernized README
authored
6
7 h2. Simple components alternative
8
9 This plugin is a simple alternative for components.
10
11 It is not a full replacement, however. It aims lower, namely:
12 * Sub-per-action component definitions.
13 * Built-in caching.
14
49fcdbd @floere Edited README.textile via GitHub
authored
15 h2. It is good, when:
d271843 @floere + modernized README
authored
16
17 # You wish to define certain view parts that are used for many controller actions.
18 # You wish to cache these view parts.
19 # You wish to not have specific controllers to load the content for these view parts.
20
49fcdbd @floere Edited README.textile via GitHub
authored
21 h3. Example use cases
d271843 @floere + modernized README
authored
22
23 * Checkout Cart displayed in site sidebar.
24 * Explorative Elements (e.g. Top Ten Books) in Sidebars.
25 * Navigational Elements on almost all pages.
26
27 And so on…
28
29 h2. Usage
30
31 In the view, e.g. application.haml call
32
c6b1feb @floere + Hi stupid, meet stupid
authored
33 <pre><code>render_context context_category_name</code></pre>
17b919b @floere + end parts
authored
34
d271843 @floere + modernized README
authored
35
36 h3. Examples
37
38 h4. Context chosen defined in the controller.
39
c6b1feb @floere + Hi stupid, meet stupid
authored
40 <pre><code>render_context :left_sidebar</code></pre>
17b919b @floere + end parts
authored
41
d271843 @floere + modernized README
authored
42
43 In this case, the specific context is determined by the controller, just
44 define the context for this controller as follows:
45
c2a5958 @floere + nicefy
authored
46 <pre><code>context context_category_name,
d271843 @floere + modernized README
authored
47 default_context_name,
48 [action_name, other_action_name] => action_specific_context_name,
c6b1feb @floere + Hi stupid, meet stupid
authored
49 some_other_action_name => yet_another_action_specific_context_name</code></pre>
17b919b @floere + end parts
authored
50
d271843 @floere + modernized README
authored
51
52 *OR* by using a block
53
c6b1feb @floere + Hi stupid, meet stupid
authored
54 <pre><code>context context_category_name do
d271843 @floere + modernized README
authored
55 # determine a context type as you wish (e.g. randomly),
56 # then return the context name
c6b1feb @floere + Hi stupid, meet stupid
authored
57 end</code></pre>
17b919b @floere + end parts
authored
58
d271843 @floere + modernized README
authored
59
60 Use @top_ten_books@ as context for the context category @left_sidebar@ in _all_ actions:
61
c6b1feb @floere + Hi stupid, meet stupid
authored
62 <pre><code>context :left_sidebar, :top_ten_books</code></pre>
17b919b @floere + end parts
authored
63
d271843 @floere + modernized README
authored
64
65
66 Use top_ten_books as context for the context category @left_sidebar@ in all
67 actions _except_ @buy@, @browse@ and @login@. Use @other_books_you_might_like@
68 for @buy@ and @browse@, and @welcome@ for the @login@ action:
69
c6b1feb @floere + Hi stupid, meet stupid
authored
70 <pre><code>context :left_sidebar, :top_ten_books,
d271843 @floere + modernized README
authored
71 [:buy, :browse] => :other_books_you_might_like,
c6b1feb @floere + Hi stupid, meet stupid
authored
72 :login => :welcome</code></pre>
d271843 @floere + modernized README
authored
73
74 *OR* if the specific context type should _not_ be determined by the controller.
75
c6b1feb @floere + Hi stupid, meet stupid
authored
76 <pre><code>render_context context_category_name, context_type_name</code></pre>
d271843 @floere + modernized README
authored
77
78 h4. Explicit context (Context not determined in the controller).
79
80 The following just renders the context for the top ten books in the left sidebar
81 without asking the controller to determine which context type should be used for
82 the left sidebar.
83
c6b1feb @floere + Hi stupid, meet stupid
authored
84 <pre><code>render_context :left_sidebar, :top_ten_books</code></pre>
d271843 @floere + modernized README
authored
85
86 h4. Loading variables for your contexts.
87
88 Loading variables for your contexts is done in the ApplicationController
89 (or if it should not be available everywhere in the Controller needed)
90
91 In your ApplicationController call the following to load instance variables for the context in category and type.
92
c6b1feb @floere + Hi stupid, meet stupid
authored
93 <pre><code>load_context(category, type, options = {}, &loading_instance_variables_block)</code></pre>
d271843 @floere + modernized README
authored
94
95 Currently supported options are @cache@, e.g.:
96
c6b1feb @floere + Hi stupid, meet stupid
authored
97 <pre><code>:cache => 7.minutes</code></pre>
d271843 @floere + modernized README
authored
98
99 This loads the top ten books into the variable @@books@:
100
c6b1feb @floere + Hi stupid, meet stupid
authored
101 <pre><code>load_context :left_sidebar, :top_ten_books, :cache => 5.minutes do
d271843 @floere + modernized README
authored
102 @books = Books.top(10)
c6b1feb @floere + Hi stupid, meet stupid
authored
103 end</code></pre>
d271843 @floere + modernized README
authored
104
105 which can then be used in the partial @contexts/left_sidebar/_top_ten_books.html.haml@:
106
c6b1feb @floere + Hi stupid, meet stupid
authored
107 <pre><code>%h1 Top Ten Books
d271843 @floere + modernized README
authored
108 - for book in @books do
109 %h2= book.title
110 %p= book.description
c6b1feb @floere + Hi stupid, meet stupid
authored
111 = link_to_add_to_cart(book)</code></pre>
d271843 @floere + modernized README
authored
112
113 The context view files should be in @views/contexts/<category>/<type>.html.haml@ (or @.text.erb@ or what have you, depending on the request format)
114
115 The file in the example above would be in:
116 @app/views/contexts/left_sidebar/top_ten_books.html.haml@
Something went wrong with that request. Please try again.