README_for_rails2.textile in bullet-2.0.1 vs README_for_rails2.textile in bullet-2.1.0
- old
+ new
@@ -4,12 +4,10 @@
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 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
There is a large refactor from gem 1.4 to 1.5, so if you upgrade to 1.5 gem, please read the Configuration section again and rewrite your configuration.
@@ -25,32 +23,25 @@
****************************************************************************
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
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
Bullet.disable_browser_cache = true
Bullet.xmpp = { :account => 'bullets_account@jabber.org',
@@ -58,31 +49,12 @@
:receiver => 'your_account@jabber.org',
:show_online_status => true }
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>
+The notifier of bullet is a wrap of "uniform_notifier":https://github.com/flyerhzm/uniform_notifier
-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 code above will enable all five of the Bullet notification systems:
* <code>Bullet.enable</code>: enable Bullet plugin/gem, otherwise do nothing
* <code>Bullet.alert</code>: pop up a JavaScript alert in the browser
* <code>Bullet.bullet_logger</code>: log to the Bullet log file (RAILS_ROOT/log/bullet.log)
* <code>Bullet.rails_logger</code>: add warnings directly to the Rails log
@@ -126,14 +98,14 @@
****************************************************************************
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 => '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.
****************************************************************************
@@ -141,10 +113,21 @@
ruby-growl gem has an issue about md5 in ruby 1.9, if you use growl and ruby 1.9, check this gist http://gist.github.com/300184
****************************************************************************
+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:
<pre><code>
@@ -207,13 +190,13 @@
Bullet is designed to function as you browse through your application in development. It will alert you whenever it encounters N+1 queries or unused eager loading.
1. setup test environment
<pre><code>
-$ rails test
-$ cd test
-$ script/generate scaffold post name:string
+$ rails test_bullet
+$ cd test_bullet
+$ script/generate scaffold post name:string
$ script/generate scaffold comment name:string post_id:integer
$ rake db:migrate
</code></pre>
2. change <code>app/model/post.rb</code> and <code>app/model/comment.rb</code>
@@ -294,22 +277,22 @@
<pre><code>
2009-08-20 09:12:19[INFO] N+1 Query: PATH_INFO: /posts; model: Post => assocations: [comments]
Add your finder: :include => [:comments]
2009-08-20 09:12:19[INFO] N+1 Query: method call stack:
-/Users/richard/Downloads/test/app/views/posts/index.html.erb:11:in `_run_erb_app47views47posts47index46html46erb'
-/Users/richard/Downloads/test/app/views/posts/index.html.erb:8:in `each'
-/Users/richard/Downloads/test/app/views/posts/index.html.erb:8:in `_run_erb_app47views47posts47index46html46erb'
-/Users/richard/Downloads/test/app/controllers/posts_controller.rb:7:in `index'
+/Users/flyerhzm/Downloads/test_bullet/app/views/posts/index.html.erb:11:in `_run_erb_app47views47posts47index46html46erb'
+/Users/flyerhzm/Downloads/test_bullet/app/views/posts/index.html.erb:8:in `each'
+/Users/flyerhzm/Downloads/test_bullet/app/views/posts/index.html.erb:8:in `_run_erb_app47views47posts47index46html46erb'
+/Users/flyerhzm/Downloads/test_bullet/app/controllers/posts_controller.rb:7:in `index'
</code></pre>
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>
9. fix the N+1 query, change <code>app/controllers/posts_controller.rb</code> file
@@ -318,21 +301,21 @@
@posts = Post.find(:all, :include => :comments)
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.
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!
11. now simulate unused eager loading. Change <code>app/controllers/posts_controller.rb</code> and <code>app/views/posts/index.html.erb</code>
@@ -342,12 +325,12 @@
@posts = Post.find(:all, :include => :comments)
respond_to do |format|
format.html # index.html.erb
format.xml { render :xml => @posts }
- end
- end
+ end
+ end
</code></pre>
<pre><code>
<% @posts.each do |post| %>
<tr>
@@ -382,12 +365,12 @@
@posts = Post.find(:all)
respond_to do |format|
format.html # index.html.erb
format.xml { render :xml => @posts }
- end
- end
+ end
+ end
</code></pre>
<pre><code>
<% @posts.each do |post| %>
<tr>
@@ -415,6 +398,6 @@
</code></pre>
****************************************************************************
-Copyright (c) 2009 - 2010 Richard Huang (flyerhzm@gmail.com), released under the MIT license
+Copyright (c) 2009 - 2011 Richard Huang (flyerhzm@gmail.com), released under the MIT license