basic_assumption 0.3.1 → 0.3.2

Sign up to get free protection for your applications and to get access to all the features.
@@ -0,0 +1,139 @@
1
+ == BasicAssumption
2
+
3
+ A clone of DecentExposure with a psuedo-modular interface for providing
4
+ custom defaults.
5
+
6
+ === What is DecentExposure?
7
+
8
+ It's a plugin written by {Stephen Cuadill}[http://www.twitter.com/voxdolo] that provides a way of
9
+ cleaning up Rails controller and view code. Find it at
10
+ {its GitHub repository}[http://github.com/voxdolo/decent_exposure].
11
+
12
+ It represents an idiom for writing certain kinds of code in a declarative way.
13
+ Particularly in your Rails apps, it's worth checking out. BasicAssumption is
14
+ another implementation of the idiom. It exists largely because I felt like
15
+ practicing writing a gem, though it does have a differentiating feature or two.
16
+ Check the configuration options for enabling compatibility with the
17
+ DecentExposure API.
18
+
19
+ == Install BasicAssumption
20
+
21
+ It's a gem, so do the usual:
22
+
23
+ [sudo] gem install basic_assumption
24
+
25
+ === Using it in a Rails app
26
+
27
+ For Rails 2, in environment.rb:
28
+
29
+ gem.config 'basic_assumption'
30
+
31
+ For Rails 3, in your Gemfile:
32
+
33
+ gem 'basic_assumption', :require => ['basic_assumption', 'basic_assumption/rails']
34
+
35
+ It's possible to use BasicAssumption in your Rails 3 app without requiring
36
+ 'basic_assumption/rails', and will in fact allow more flexibility if you don't,
37
+ but will incure the cost of additional setup. See the file
38
+ 'lib/basic_assumption/rails.rb' for guidance.
39
+
40
+ To use the library in another context, it is enough to extend the
41
+ BasicAssumption module with the classes you would like to use it in.
42
+
43
+ == Examples
44
+
45
+ === Inside a Rails controller
46
+
47
+ The presumed most-common use case for BasicAssumption is in a Rails app. By
48
+ default, BasicAssumption is extended by ActionController::Base, making it
49
+ available inside your controllers.
50
+
51
+ The most important (of the few) methods made available in controller classes is
52
+ +assume+, which is used to declaratively define a resource of some kind in
53
+ controller instances and to make that resource available inside corresponding
54
+ views. For all the verbiage of the description, it's a simple concept, as
55
+ illustrated below. First, we will use +assume+ to expose a resource inside our
56
+ controller actions that will take the value resulting from the block passed to
57
+ +assume+. In this case, the resource will be called 'widget':
58
+
59
+ class WidgetController < ActionController::Base
60
+
61
+ assume(:widget) { Widget.find(params[:id]) }
62
+
63
+ ...
64
+
65
+ def purchase
66
+ current_user.purchase!(widget)
67
+ render :template => 'widgets/purchase_complete'
68
+ end
69
+ end
70
+
71
+ And then inside of the 'widgets/purchase_complete.html.haml' view:
72
+
73
+ %h2= "#{current_user.name}, your purchase is complete!
74
+ .widget
75
+ %span#thanks
76
+ = "Thank you for purchasing #{widget.name}!"
77
+ %table#details
78
+ %tr
79
+ %td Cost
80
+ %td= widget.cost
81
+ %tr
82
+ %td Manufacturer
83
+ %td= widget.manufacturer
84
+
85
+ By calling +assume+ with the symbol :widget and passing it a block, an instance
86
+ method is created on the controller class that is also exposed as a helper
87
+ inside views. For more details, please see the +Railtie+ documentation.
88
+
89
+ === Defaults
90
+
91
+ BasicAssumption allows for default behavior to be associated with methods
92
+ created by +assume+ whenever a block is not passed. Here is a simple example:
93
+
94
+ class WidgetController < ActionController::Base
95
+ default_assumption { Widget.find(params[:id]) }
96
+ assume(:widget)
97
+
98
+ ...
99
+ end
100
+
101
+ This will provide the same behavior as the similar example above. In Rails,
102
+ a helpful default is already made available. Please see +SimpleRails+ for
103
+ a discussion.
104
+
105
+ === Supplying custome default behavior classes
106
+
107
+ There is an ability to provide custom, modular default extensions to
108
+ BasicAssumption. Please see the documentation for +DefaultAssumption+
109
+ for a discussion and +SimpleRails+ for an example.
110
+
111
+ === Configuration
112
+
113
+ There are a couple of simple configuration settings that can be set inside of
114
+ a configuration block that can be used in places such as Rails initializer
115
+ blocks. For more information, see +Configuration+.
116
+
117
+ More are yet to come...
118
+
119
+ == Issues
120
+
121
+ === Memoization
122
+
123
+ Methods that are created by +assume+ memoize the result of the block the invoke
124
+ when they're called. Because of that, the block is only evaluated once during
125
+ the lifespan of each object of the class that used +assume+. This means that
126
+ a method created by assuming can be used multiple times inside of a Rails
127
+ controller object and associated view(s), but it also means that any behavior
128
+ of the block that is meant to vary over multiple invocations will not be
129
+ observerd.
130
+
131
+ == Hacking/running specs
132
+
133
+ There is nothing special about running the specs, aside from ensuring the
134
+ RUBYOPT environment variable is set to your preferred Ruby dependency
135
+ manager. For example, if RubyGems:
136
+
137
+ export RUBYOPT=rubygems
138
+
139
+ Other than that, please feel free to fork and send back pull requests! Thanks.
@@ -1,3 +1,3 @@
1
1
  module BasicAssumption
2
- VERSION = '0.3.1'
2
+ VERSION = '0.3.2'
3
3
  end
metadata CHANGED
@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
5
5
  segments:
6
6
  - 0
7
7
  - 3
8
- - 1
9
- version: 0.3.1
8
+ - 2
9
+ version: 0.3.2
10
10
  platform: ruby
11
11
  authors:
12
12
  - Matt Yoho
@@ -14,7 +14,7 @@ autorequire:
14
14
  bindir: bin
15
15
  cert_chain: []
16
16
 
17
- date: 2010-05-24 00:00:00 -05:00
17
+ date: 2010-05-25 00:00:00 -05:00
18
18
  default_executable:
19
19
  dependencies:
20
20
  - !ruby/object:Gem::Dependency
@@ -66,9 +66,9 @@ executables: []
66
66
  extensions: []
67
67
 
68
68
  extra_rdoc_files:
69
- - README.md
69
+ - README.rdoc
70
70
  files:
71
- - README.md
71
+ - README.rdoc
72
72
  - lib/basic_assumption.rb
73
73
  - lib/basic_assumption/configuration.rb
74
74
  - lib/basic_assumption/default_assumption.rb
@@ -108,7 +108,7 @@ rubyforge_project:
108
108
  rubygems_version: 1.3.6
109
109
  signing_key:
110
110
  specification_version: 3
111
- summary: Allows a simple declarative idiom for resources in controllers and views. Custom default behavior can be defined in a pluggable manner.
111
+ summary: Allows a simple declarative idiom for accessing resources in controllers and views, cleaning up controller code and removing the need to explicitly reference instance variables inside views. Custom default behavior can be defined in a pluggable manner.
112
112
  test_files:
113
113
  - spec/spec_helper.rb
114
114
  - spec/lib/basic_assumption_spec.rb
data/README.md DELETED
@@ -1,5 +0,0 @@
1
- BasicAssumption
2
- ===============
3
-
4
- A clone of decent_exposure, with less shared-state in its specs. Check the configuration options for enabling the decent_exposure API.
5
-