Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

update documents

  • Loading branch information...
commit 8335facbb91df90ef1ac3147112223846b484ef4 1 parent 3360553
@flyerhzm authored
Showing with 61 additions and 127 deletions.
  1. +9 −40 Hacking.textile
  2. +24 −42 README.textile
  3. +28 −45 README_for_rails2.textile
View
49 Hacking.textile
@@ -5,64 +5,37 @@ it (hopefully) easier to extend or enhance the Bullet gem.
h2. General Control Flow aka. 10000 Meter View
When Rails is initialized, Bullet will extend ActiveRecord (and if you're using
Rails 2.x ActiveController too) with the relevant modules and methods found
-in lib/bullet/active_recordX.rb and lib/bullet/action_controller2.rb. If you're
+in lib/bullet/active_recordX.rb and lib/bullet/action_controller2.rb. If you're
running Rails 3, Bullet will integrate itself as a middleware into the Rack
stack, so ActionController does not need to be extended.
-The ActiveRecord extensions will call methods in a given detector class, when
-certain methods are called.
+The ActiveRecord extensions will call methods in a given detector class, when
+certain methods are called.
-Detector classes contain all the logic to recognize
+Detector classes contain all the logic to recognize
a noteworthy event. If such an event is detected, an instance of the
corresponding Notification class is created and stored in a Set instance in the
-main Bullet module (the 'notification collector').
+main Bullet module (the 'notification collector').
Notification instances contain the message that will be displayed, and will
use a Presenter class to display their message to the user.
-Each Presenter knows how to present the message either "inline" (as in: the
-message text will be inlined into the request response, such as javascript
-alerts) or "out-of-channel" (completely independent of the request response,
-such as growl or xmpp).
-
So the flow of a request goes like this:
1. Bullet.start_request is called, which resets all the detectors and empties
the notification collector
2. The request is handled by Rails, and the installed ActiveRecord extensions
trigger Detector callbacks
-3. Detectors once called, will determine whether something noteworthy happend.
+3. Detectors once called, will determine whether something noteworthy happend.
If yes, then a Notification is created and stored in the notification collector.
4. Rails finishes handling the request
5. For each notification in the collector, Bullet will iterate over each
Presenter and will try to generate an inline message that will be appended to
- the generated reponse body.
+ the generated response body.
6. The response is returned to the client.
7. Bullet will try to generate an out-of-channel message for each notification.
8. Bullet calls end_request for each detector.
9. Goto 1.
-h2. Adding Presenters
-To add a presenter, you will need to:
-* Add the class to the PRESENTERS constant in the main Bullet module
-* Add an autoload directive to lib/bullet/presenter.rb
-* Create your presenter class in the Bullet::Presenter namespace
-
-Presenter classes will need the following class methods:
-* .active? which returns a boolean to indicate if the presenter is active (so
-* that presenters the user doesn't want can be skipped).
-
-and at least one of:
-* .out_of_channel_notify( notification ) which will display the notification to the
- user outside of the request response
-or
-* .inline_notify( notification ) which will generate the notification presentation fit
- to be appended to the generated HTML request response (if you want to inject
- content on the result page, such as a javascript alert).
-
-Have a look at lib/bullet/javascript_alert.rb as a trivial example for an
-inline presenter and lib/bullet/rails_logger.rb to see how a minimal
-out-of-channel presenter looks like.
-
h2. Adding Notification Types
If you want to add more kinds of things that Bullet can detect, a little more
work is needed than if you were just adding a Presenter, but the concepts are
@@ -70,7 +43,6 @@ similar.
* Add the class to the DETECTORS constant in the main Bullet module
* Add (if needed) Rails monkey patches to Bullet.enable
-* Create your presenter class in the Bullet::Detector namespace
* Add an autoload directive to lib/bullet/detector.rb
* Create a corresponding notification class in the Bullet::Notification namespace
* Add an autoload directive to lib/bullet/notification.rb
@@ -86,7 +58,7 @@ a feel for what is needed to get off the ground.
h3. Detectors
The only things you'll need to consider when building your Detector class is
that it will need to supply the .start_request, .end_request and .clear class
-methods.
+methods.
Simple implementations are provided by Bullet::Detector::Base for start_request
and end_request, you will have to supply your own clear method.
@@ -94,7 +66,4 @@ and end_request, you will have to supply your own clear method.
h3. Notifications
For notifications you will want to supply a #title and #body instance method,
and check to see if the #initialize and #full_notice methods in the
-Bullet::Notification::Base class fit your needs.
-
-The interaction with the presenters encapsulated in the Base class, so you
-won't have to worry about that.
+Bullet::Notification::Base class fit your needs.
View
66 README.textile
@@ -4,20 +4,22 @@ The Bullet plugin/gem is designed to help you increase your application's perfor
Best practice is to use Bullet in development mode or custom mode (staging, profile, etc.). The last thing you want is your clients getting alerts about how lazy you are.
-The Bullet plugin/gem now supports rails 2.1, 2.2, 2.3 and 3.0, tested in rails 2.1.2, 2.2.2, 2.3.2 and 3.0.0.beta.
+The Bullet plugin/gem now supports rails 2.1, 2.2, 2.3 and 3.0.
****************************************************************************
h2. Install
-You can add Bullet to your Rails gem requirements:
-<pre><code>config.gem 'bullet', :source => 'http://gemcutter.org'</code></pre>
-
You can install it as a gem:
<pre><code>
-sudo gem install bullet --pre
+gem install bullet
</code></pre>
+or add it into a Gemfile (Bundler):
+<pre><code>
+gem "bullet", :group => "development"
+</code></code>
+
****************************************************************************
h2. Configuration
@@ -25,9 +27,9 @@ h2. Configuration
Bullet won't do ANYTHING unless you tell it to explicitly. Append to <code>config/environments/development.rb</code> initializer with the following code:
<pre><code>
config.after_initialize do
- Bullet.enable = true
+ Bullet.enable = true
Bullet.alert = true
- Bullet.bullet_logger = true
+ Bullet.bullet_logger = true
Bullet.console = true
Bullet.growl = true
Bullet.xmpp = { :account => 'bullets_account@jabber.org',
@@ -39,27 +41,7 @@ config.after_initialize do
end
</code></pre>
-It is recommended to config growl notification as follows if your collaborators are not using MacOS
-<pre><code>
- begin
- require 'ruby-growl'
- Bullet.growl = true
- rescue MissingSourceFile
- end
-</code></pre>
-
-and similarly for XMPP:
-<pre><code>
- begin
- require 'xmpp4r'
- Bullet.xmpp = { :account => 'bullets_account@jabber.org',
- :password => 'bullets_password_for_jabber',
- :receiver => 'your_account@jabber.org',
- :show_online_status => true }
- rescue MissingSourceFile
- end
-</code></pre>
-
+The notifier of bullet is a wrap of "uniform_notifier":https://github.com/flyerhzm/uniform_notifier
The code above will enable all six of the Bullet notification systems:
* <code>Bullet.enable</code>: enable Bullet plugin/gem, otherwise do nothing
@@ -109,10 +91,10 @@ These two lines are notifications that unused eager loadings have been encounter
h2. Growl Support
To get Growl support up-and-running for Bullet, follow the steps below:
-* Install the ruby-growl gem: <code>sudo gem install ruby-growl</code>
+* Install the ruby-growl gem: <code>gem install ruby-growl</code>
* Open the Growl preference pane in Systems Preferences
* Click the "Network" tab
-* Make sure both "Listen for incoming notifications" and "Allow remote application registration" are checked. *Note*: If you set a password, you will need to set <code>Bullet.growl_password = 'your_growl_password</code>' in the config file.
+* Make sure both "Listen for incoming notifications" and "Allow remote application registration" are checked. *Note*: If you set a password, you will need to set <code>Bullet.growl_password = { :password => 'growl password' }</code> in the config file.
* Restart Growl ("General" tab -> Stop Growl -> Start Growl)
* Boot up your application. Bullet will automatically send a Growl notification when Growl is turned on. If you do not see it when your application loads, make sure it is enabled in your initializer and double-check the steps above.
@@ -200,7 +182,7 @@ Bullet is designed to function as you browse through your application in develop
<pre><code>
$ rails test
$ cd test
-$ script/rails g scaffold post name:string
+$ script/rails g scaffold post name:string
$ script/rails g scaffold comment name:string post_id:integer
$ rake db:migrate
</code></pre>
@@ -299,9 +281,9 @@ In the meanwhile, there's a log appended into <code>log/bullet.log</code> file
The generated SQLs are
<pre><code>
- Post Load (1.0ms) SELECT * FROM "posts"
- Comment Load (0.4ms) SELECT * FROM "comments" WHERE ("comments".post_id = 1)
- Comment Load (0.3ms) SELECT * FROM "comments" WHERE ("comments".post_id = 2)
+ Post Load (1.0ms) SELECT * FROM "posts"
+ Comment Load (0.4ms) SELECT * FROM "comments" WHERE ("comments".post_id = 1)
+ Comment Load (0.3ms) SELECT * FROM "comments" WHERE ("comments".post_id = 2)
</code></pre>
@@ -314,8 +296,8 @@ The generated SQLs are
respond_to do |format|
format.html # index.html.erb
format.xml { render :xml => @posts }
- end
- end
+ end
+ end
</code></pre>
10. refresh http://localhost:3000/posts page, no alert box and no log appended.
@@ -323,8 +305,8 @@ The generated SQLs are
The generated SQLs are
<pre><code>
- Post Load (0.5ms) SELECT * FROM "posts"
- Comment Load (0.5ms) SELECT "comments".* FROM "comments" WHERE ("comments".post_id IN (1,2))
+ Post Load (0.5ms) SELECT * FROM "posts"
+ Comment Load (0.5ms) SELECT "comments".* FROM "comments" WHERE ("comments".post_id IN (1,2))
</code></pre>
a N+1 query fixed. Cool!
@@ -338,8 +320,8 @@ a N+1 query fixed. Cool!
respond_to do |format|
format.html # index.html.erb
format.xml { render :xml => @posts }
- end
- end
+ end
+ end
</code></pre>
<pre><code>
@@ -378,8 +360,8 @@ Remove from your finder: :include => [:comments]
respond_to do |format|
format.html # index.html.erb
format.xml { render :xml => @posts }
- end
- end
+ end
+ end
</code></pre>
<pre><code>
View
73 README_for_rails2.textile
@@ -6,8 +6,6 @@ Best practice is to use Bullet in development mode or custom mode (staging, prof
The Bullet plugin/gem now supports rails 2.1, 2.2 and 2.3, tested in rails 2.1.2, 2.2.2 and 2.3.2.
-*Important: bullet gem has been moved to gemcutter.org*
-
****************************************************************************
h2. Change
@@ -27,18 +25,11 @@ rainux added group style console.log.
h2. Install
-You can add Bullet to your Rails gem requirements:
-<pre><code>config.gem 'bullet', :source => 'http://gemcutter.org'</code></pre>
-
You can install it as a gem:
<pre><code>
-sudo gem sources -a http://gemcutter.org
sudo gem install bullet
</code></pre>
-Or you can install it as a rails plugin:
-<pre><code>script/plugin install git://github.com/flyerhzm/bullet.git</code></pre>
-
****************************************************************************
h2. Configuration
@@ -46,9 +37,9 @@ h2. Configuration
Bullet won't do ANYTHING unless you tell it to explicitly. Append to <code>config/environments/development.rb</code> initializer with the following code:
<pre><code>
config.after_initialize do
- Bullet.enable = true
+ Bullet.enable = true
Bullet.alert = true
- Bullet.bullet_logger = true
+ Bullet.bullet_logger = true
Bullet.console = true
Bullet.growl = true
Bullet.rails_logger = true
@@ -60,26 +51,7 @@ config.after_initialize do
end
</code></pre>
-It is recommended to config growl notification as follows if your collaborators are not using MacOS
-<pre><code>
- begin
- require 'ruby-growl'
- Bullet.growl = true
- rescue MissingSourceFile
- end
-</code></pre>
-
-and similarly for XMPP:
-<pre><code>
- begin
- require 'xmpp4r'
- Bullet.xmpp = { :account => 'bullets_account@jabber.org',
- :password => 'bullets_password_for_jabber',
- :receiver => 'your_account@jabber.org',
- :show_online_status => true }
- rescue MissingSourceFile
- end
-</code></pre>
+The notifier of bullet is a wrap of "uniform_notifier":https://github.com/flyerhzm/uniform_notifier
The code above will enable all five of the Bullet notification systems:
* <code>Bullet.enable</code>: enable Bullet plugin/gem, otherwise do nothing
@@ -128,10 +100,10 @@ These two lines are notifications that unused eager loadings have been encounter
h2. Growl Support
To get Growl support up-and-running for Bullet, follow the steps below:
-* Install the ruby-growl gem: <code>sudo gem install ruby-growl</code>
+* Install the ruby-growl gem: <code>gem install ruby-growl</code>
* Open the Growl preference pane in Systems Preferences
* Click the "Network" tab
-* Make sure both "Listen for incoming notifications" and "Allow remote application registration" are checked. *Note*: If you set a password, you will need to set <code>Bullet.growl_password = 'your_growl_password</code>' in the config file.
+* Make sure both "Listen for incoming notifications" and "Allow remote application registration" are checked. *Note*: If you set a password, you will need to set <code>Bullet.growl_password = { :password => 'growl password' }</code> in the config file.
* Restart Growl ("General" tab -> Stop Growl -> Start Growl)
* Boot up your application. Bullet will automatically send a Growl notification when Growl is turned on. If you do not see it when your application loads, make sure it is enabled in your initializer and double-check the steps above.
@@ -143,6 +115,17 @@ ruby-growl gem has an issue about md5 in ruby 1.9, if you use growl and ruby 1.9
****************************************************************************
+h2. XMPP/Jabber Support
+
+To get XMPP support up-and-running for Bullet, follow the steps below:
+* Install the xmpp4r gem: <code>sudo gem install xmpp4r</code>
+* Make both the bullet and the receipient account add each other as contacts.
+ This will require you to manually log into both accounts, add each other
+ as contact and confirm each others contact request.
+* Boot up your application. Bullet will automatically send an XMPP notification when XMPP is turned on.
+
+****************************************************************************
+
h2. Important
If you encounter the following errors in development environment:
@@ -211,7 +194,7 @@ Bullet is designed to function as you browse through your application in develop
<pre><code>
$ rails test
$ cd test
-$ script/generate scaffold post name:string
+$ script/generate scaffold post name:string
$ script/generate scaffold comment name:string post_id:integer
$ rake db:migrate
</code></pre>
@@ -305,9 +288,9 @@ Add your finder: :include => [:comments]
The generated SQLs are
<pre><code>
- Post Load (1.0ms) SELECT * FROM "posts"
- Comment Load (0.4ms) SELECT * FROM "comments" WHERE ("comments".post_id = 1)
- Comment Load (0.3ms) SELECT * FROM "comments" WHERE ("comments".post_id = 2)
+ Post Load (1.0ms) SELECT * FROM "posts"
+ Comment Load (0.4ms) SELECT * FROM "comments" WHERE ("comments".post_id = 1)
+ Comment Load (0.3ms) SELECT * FROM "comments" WHERE ("comments".post_id = 2)
</code></pre>
@@ -320,8 +303,8 @@ The generated SQLs are
respond_to do |format|
format.html # index.html.erb
format.xml { render :xml => @posts }
- end
- end
+ end
+ end
</code></pre>
10. refresh http://localhost:3000/posts page, no alert box and no log appended.
@@ -329,8 +312,8 @@ The generated SQLs are
The generated SQLs are
<pre><code>
- Post Load (0.5ms) SELECT * FROM "posts"
- Comment Load (0.5ms) SELECT "comments".* FROM "comments" WHERE ("comments".post_id IN (1,2))
+ Post Load (0.5ms) SELECT * FROM "posts"
+ Comment Load (0.5ms) SELECT "comments".* FROM "comments" WHERE ("comments".post_id IN (1,2))
</code></pre>
a N+1 query fixed. Cool!
@@ -344,8 +327,8 @@ a N+1 query fixed. Cool!
respond_to do |format|
format.html # index.html.erb
format.xml { render :xml => @posts }
- end
- end
+ end
+ end
</code></pre>
<pre><code>
@@ -384,8 +367,8 @@ Remove from your finder: :include => [:comments]
respond_to do |format|
format.html # index.html.erb
format.xml { render :xml => @posts }
- end
- end
+ end
+ end
</code></pre>
<pre><code>
Please sign in to comment.
Something went wrong with that request. Please try again.