pinball_wizard 0.0.1.pre → 0.3.0

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,15 +1,7 @@
1
1
  ---
2
- !binary "U0hBMQ==":
3
- metadata.gz: !binary |-
4
- NGU1M2E1OTQ2MTBiM2RhMDVjZjUwNzkwMzhjZGRiZjkzMDYyZGQ4OA==
5
- data.tar.gz: !binary |-
6
- YzI0NGQwYzQyZTIzZTdiY2NmNzg5YTdhYTQ4MDdkMWEwODQ4MTA5YQ==
2
+ SHA1:
3
+ metadata.gz: 42cbebb8dd5c1c26041835f0bf8149703670e028
4
+ data.tar.gz: d9222cff9a8711eaf7a1423ecc4f5a52cc383b6f
7
5
  SHA512:
8
- metadata.gz: !binary |-
9
- MTdhOGRmMDUwZDc5YzBjZThlOTE2MDNiZjFjNTI1NjVkYTUzYmU5MTVkMzJi
10
- ODM1NzU5NjQ2ZmY1OWUwOTFmYzZmMTFiMGMyY2YzNGMzOTE5OTg4YzBkYmYz
11
- NmNhOTQ4ZDZhOTM0ZTAwNzZiMTE4NjY0ZWQ0Zjg4NDk3MWUzN2U=
12
- data.tar.gz: !binary |-
13
- MDMxNjE2ZjdhNmExYzJkNDI2MDQ1NDZjYzhhMDYxYzQ5Mzc1MjZmMDNlNjdk
14
- ZDhlZWVlZjVlYzI5ZTVmNWJlMzNjMGQzYmU2ZTljNjRhNDAyZDc4NzZkMjY2
15
- MmU1MDMxNjljNjBlZGFiYTEzMWE1NzUxZTRmZGE4ZGU1ZDM2MmQ=
6
+ metadata.gz: 473cb966be4e5ef8151fec9a9a8b49c76a810593f235478a3a69435f5c2ff4825490bff06d573aaf96ff2664ac94867536d8f147f5f7f46de106f4980b107881
7
+ data.tar.gz: e910016832eb2bb49ffc292b6e2be0c308800fbf1c46a7371c2ba2c13182d6ae61bebad9a0978d10e7ae233fefb90e97ce1e5077ec0d11b723842348a54081ae
data/.gitignore ADDED
@@ -0,0 +1,9 @@
1
+ .DS_Store
2
+ .rvmrc
3
+ vendor/ruby
4
+ .bundle
5
+ .DS_Store
6
+ node_modules
7
+ .tmp/
8
+ npm-debug.log
9
+ pkg
data/CHANGELOG.md ADDED
@@ -0,0 +1,6 @@
1
+ # v0.3.0
2
+ * [feature] Automatically add and remove CSS class `.use-{feature-name}` to `<html>` as features are enabled and disabled.
3
+ * [feature] Switch to karma for the test runner.
4
+ * [deprecated] Removed `?pinball_feature_name` query param
5
+
6
+ [Compare v0.2.0..v0.3.0](https://github.com/primedia/pinball_wizard/compare/v0.2.0...v0.3.0)
data/Gemfile ADDED
@@ -0,0 +1,8 @@
1
+ source 'https://rubygems.org'
2
+
3
+ gem 'rake'
4
+ gem 'rspec'
5
+
6
+ group :development do
7
+ gem 'pry'
8
+ end
data/Gemfile.lock ADDED
@@ -0,0 +1,32 @@
1
+ GEM
2
+ remote: https://rubygems.org/
3
+ specs:
4
+ coderay (1.1.0)
5
+ diff-lcs (1.2.5)
6
+ method_source (0.8.2)
7
+ pry (0.10.0)
8
+ coderay (~> 1.1.0)
9
+ method_source (~> 0.8.1)
10
+ slop (~> 3.4)
11
+ rake (10.3.2)
12
+ rspec (3.0.0)
13
+ rspec-core (~> 3.0.0)
14
+ rspec-expectations (~> 3.0.0)
15
+ rspec-mocks (~> 3.0.0)
16
+ rspec-core (3.0.1)
17
+ rspec-support (~> 3.0.0)
18
+ rspec-expectations (3.0.1)
19
+ diff-lcs (>= 1.2.0, < 2.0)
20
+ rspec-support (~> 3.0.0)
21
+ rspec-mocks (3.0.1)
22
+ rspec-support (~> 3.0.0)
23
+ rspec-support (3.0.0)
24
+ slop (3.5.0)
25
+
26
+ PLATFORMS
27
+ ruby
28
+
29
+ DEPENDENCIES
30
+ pry
31
+ rake
32
+ rspec
data/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ The MIT License
2
+
3
+ Copyright (c) 2014 RentPath, Inc. http://rentpath.com
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in
13
+ all copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
+ THE SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,336 @@
1
+ # Client and Server Feature Flipping
2
+
3
+ <img src="http://upload.wikimedia.org/wikipedia/commons/thumb/e/e8/Pinball_Flippers_-_Demolition_Man.JPG/1024px-Pinball_Flippers_-_Demolition_Man.JPG" width="100%">
4
+
5
+ [<img src="http://img.youtube.com/vi/DthtDjhqVOU/1.jpg" height="40"> The Who & Elton John - Pinball Wizard (Tommy 1975)](https://www.youtube.com/watch?v=DthtDjhqVOU)
6
+
7
+ `PinballWizard` brings feature flipping into a simple and uniform API in both client-side JavaScript and Ruby.
8
+
9
+ ## Why?
10
+
11
+ PinballWizard is intended to work with heavily cached pages (e.g. Varnish) that need feature flipping. It works well with third parties such as [Optimizely](http://optimizely.com/) where flipping occurs after HTML is rendered.
12
+
13
+ ## What is a *feature*?
14
+
15
+ A set of Ruby, HTML, JavaScript, and CSS that can be turned on or off.
16
+
17
+ A feature is simply a name and default state:
18
+
19
+ * *active*: If it is currently turned on and running.
20
+ * *inactive*: Not turned on.
21
+ * *disabled*: Not turned on and cannot be activated.
22
+
23
+
24
+ ## Building
25
+ 1. Define and register the feature in the [Ruby app](#ruby).
26
+ 2. Build the [JavaScript component](#javascript).
27
+ 3. Write the corresponding [HTML](#html) and [CSS](#css)
28
+ 4. [Activate and test your feature](#activating-and-testing-features).
29
+
30
+ ## Ruby
31
+
32
+ Define your feature in (typically `config/initializers/pinball_wizard.rb`).
33
+
34
+ ```ruby
35
+ PinballWizard::DSL.build do
36
+ # Active when the page loads:
37
+ feature :example, active: true
38
+
39
+ # Deactive when the page loads:
40
+ feature :example, active: false
41
+ end
42
+ ```
43
+
44
+ You can also pass in a proc for situtations where active/inactive is conditional. Returning false with make the feature inactive.
45
+
46
+ ```ruby
47
+ PinballWizard::DSL.build do
48
+ feature :example, active: proc { }
49
+ end
50
+ ```
51
+
52
+ ## HTML
53
+
54
+ Once the feature is registered, you can use Slim to include the HTML partial found at `app/views/features/example.slim`. This is only included if the feature is available, which allows the HTML to stay small.
55
+
56
+ ```slim
57
+ = feature 'example'
58
+ ```
59
+
60
+ To use a different partial for the same feature, pass in the `partial:` key. This will use `app/views/features/example_button.slim`.
61
+
62
+ If the feature is not active immediately, it's recommended to hide the HTML with inline or external CSS.
63
+
64
+ ```slim
65
+ = feature 'example', partial: :example_button'
66
+ ```
67
+
68
+ ## CSS
69
+
70
+ PinballWizard automatically adds and removes a CSS class named `.use-{feature-name}` to the `<html>` tag. This allows you to write CSS when features are active.
71
+
72
+ It is also recommended to organize your CSS similar to Ruby:
73
+
74
+ ```scss
75
+ // app/assets/stylesheets/features/_example.scss
76
+
77
+ .use-example {
78
+ // CSS when the 'example' feature is active.
79
+ }
80
+ ```
81
+
82
+ Then include it on the main file with `@import 'features/example'`
83
+
84
+
85
+ ## JavaScript
86
+
87
+ Features subscribe to events and respond when they're activated or deactivated. It no longer needs to know about Optimizely, cookies, or url params. (Single Responsibility Principle FTW)
88
+
89
+ One advantage to this approach is that you can activate features after the DOM is loaded (for testing).
90
+
91
+ When pinball runs, it will automatically activate the features.
92
+
93
+ ### Example AMD/RequireJS Module
94
+
95
+ ```coffee
96
+ define ['pinball_wizard'], (pinball) ->
97
+
98
+ # Define feature component functions here ...
99
+
100
+ pinball.subscribe 'example',
101
+ ->
102
+ # callback when activated. e.g. show it
103
+ ->
104
+ # callback when deactivated. e.g. hide it.
105
+
106
+ # Return component functions to expose.
107
+ ```
108
+
109
+ ### Example Flight Component
110
+
111
+ ```coffee
112
+ define ['pinball_wizard'], (pinball) ->
113
+
114
+ @after 'initialize', ->
115
+ pinball.subscribe 'example',
116
+ =>
117
+ # callback when activated. e.g. show it
118
+ =>
119
+ # callback when deactivated. e.g. hide it.
120
+
121
+ ```
122
+
123
+ ### Asking *(pseudo-code)*
124
+
125
+ As an alternative, a feature may check if it's active. This method is not preferred since it only occurs once during page load.
126
+
127
+ ```coffee
128
+ define ['pinball_wizard'], (pinball) ->
129
+
130
+ if pinball.isActive('example')
131
+ # Do something
132
+ ```
133
+
134
+ ## Activating and Testing Features
135
+
136
+ ### With a URL Param
137
+ Add `pinball` to the URL (e.g. `?pinball=example_a,example_b`).
138
+
139
+ ### Post-Render (after page load)
140
+
141
+ ```javascript
142
+ pinball.activate('example');
143
+ ```
144
+
145
+ ```javascript
146
+ pinball.deactivate('example');
147
+ ```
148
+
149
+ Activating a feature that is already active or disabled will have no effect.
150
+
151
+ #### Optionally Supply a Source
152
+
153
+ Add an optional source as a second argument to help know where features are
154
+ activated while debugging.
155
+
156
+ ```javascript
157
+ pinball.activate('example','source name');
158
+ ```
159
+
160
+
161
+ ## JsConfig
162
+ The application keeps a list of features and passes them in the JsConfig object (e.g. `window.ApartmentGuide`). These define what's available and activated on page load. AG is hooked up to PinballWizard to automatically be aware of these. No additional code is necessary.
163
+
164
+ `{ "feature_name": "state", "feature_name": "state" }`
165
+
166
+ e.g. `{ "feature_a": "active", "feature_b": "inactive", "feature_c": "disabled" }`
167
+
168
+ ## Debugging
169
+
170
+ Add it to the url:
171
+ `?pinball=debug`
172
+
173
+ Turn on logging in JavaScript:
174
+ ```js
175
+ pinball.debug();
176
+ ```
177
+
178
+ Show current state in the JavaScript console:
179
+ ```js
180
+ pinball.state();
181
+ ```
182
+
183
+ ## Integrations
184
+ * [Rails](https://github.com/primedia/pinball_wizard/wiki/Integrating-with-Rails)
185
+ * [Sinatra with Slim](https://github.com/primedia/pinball_wizard/wiki/Integrating-with-Sinatra)
186
+ * [Optimizely](https://github.com/primedia/pinball_wizard/wiki/Integrating-a-Feature-with-Optimizely)
187
+
188
+ For RentPath specific functionality, including ConFusion, see [pinball_wizard-rentpath](https://github.com/primedia/pinball_wizard-rentpath)
189
+
190
+ ## Extra: Custom Ruby Class
191
+
192
+ By default, features are instances of `PinballWizard::Feature`. You can define your own class and register it according to a hash key. This is useful to disable features.
193
+
194
+ ```ruby
195
+ # e.g. app/features/my_feature.rb
196
+ module PinballWizard
197
+ class MyFeature < Feature
198
+ def determine_state
199
+ if my_condition?
200
+ disable "My Feature: My Reason"
201
+ end
202
+ end
203
+ end
204
+ end
205
+
206
+ # e.g. config/initializers/pinball_wizard.rb
207
+ PinballWizard.configure do |c|
208
+ c.class_patterns = my_option: PinballWizard::MyFeature
209
+ end
210
+
211
+ # e.g. config/features.rb
212
+ PinballWizard::DSL.build do
213
+ feature :example, :my_option
214
+ end
215
+ ```
216
+
217
+ ## Getting started for development.
218
+ ```
219
+ git checkout dev
220
+ git pull origin dev
221
+ git checkout -b my_branch
222
+ npm run preversion
223
+ ```
224
+
225
+ ## A basic red-green-refactor workflow.
226
+
227
+ ```
228
+ npm install
229
+ npm run watch
230
+ npm run watch:test # in another terminal window or pane
231
+ ```
232
+
233
+ ## Examples of common tasks.
234
+
235
+ npm script commands are defined in the scripts section of package.json.
236
+ To see a full list of available npm commands, run:
237
+
238
+ ```
239
+ npm run
240
+ ```
241
+
242
+ ### Install NPM Dependencies
243
+
244
+ ```
245
+ npm install
246
+ ```
247
+
248
+ ### One-time compile of application source and tests.
249
+
250
+ ```
251
+ npm run compile
252
+ ```
253
+
254
+ ### Compile application source & tests and build the distribution as files change.
255
+
256
+ ```
257
+ npm run watch
258
+ ```
259
+
260
+ ### Running Tests.
261
+
262
+ One time.
263
+
264
+ ```
265
+ npm test
266
+ ```
267
+
268
+ Watch continuously and run tests when code or specs change.
269
+
270
+ ```
271
+ npm run watch:test
272
+ ```
273
+
274
+ ### Cleaning
275
+
276
+ Remove compiled code and tests in .tmp/.
277
+
278
+ ```
279
+ npm run clean
280
+ ```
281
+
282
+ Remove compiled code and tests, `node_modules`
283
+
284
+ ```
285
+ npm run clean:all
286
+ ```
287
+
288
+ Remove compiled code, tests, `node_modules`; reinstall
289
+ node modules; recompile code and tests.
290
+
291
+ ```
292
+ npm run reset
293
+ ```
294
+
295
+ ### Building a Distribution
296
+
297
+ To build a distribution and tag it, run one of the following commands.
298
+
299
+ ```
300
+ npm version patch -m "Bumped to %s"
301
+ npm version minor -m "Bumped to %s"
302
+ npm version major -m "Bumped to %s"
303
+ ```
304
+
305
+ There's a 'preversion' script in package.json that does the following:
306
+ - Remove the .tmp/ directory.
307
+ - Remove the node_modules directories.
308
+ - Install all npm packages.
309
+ - Compile the application source and specs.
310
+ - Run the tests.
311
+ - Rebuild the distribution.
312
+
313
+ Just build a distribution.
314
+
315
+ ```
316
+ npm run build
317
+ ```
318
+
319
+ ## Notes
320
+ - The `dist/` directory must be part of the repo - don't gitignore it!
321
+
322
+
323
+ ## Contributing
324
+
325
+ Fork and submit a pull request. This is a [README driven development](http://tom.preston-werner.com/2010/08/23/readme-driven-development.html) process, please contribute by modifying this document.
326
+
327
+
328
+ ## Credits
329
+
330
+ - Pinball photo:
331
+ - [ElHeineken](http://commons.wikimedia.org/wiki/User:ElHeineken)
332
+ - http://creativecommons.org/licenses/by/3.0/
333
+
334
+ ## License
335
+
336
+ [MIT](https://github.com/primedia/pinball_wizard/blob/master/LICENSE)
data/Rakefile ADDED
@@ -0,0 +1,4 @@
1
+ require 'bundler/gem_tasks'
2
+ require 'rspec/core/rake_task'
3
+ RSpec::Core::RakeTask.new(:spec)
4
+ task :default => :spec