atom thoughts

Ruby comes with a great utilty called RI for searching and displaying ruby documentation. I have had varying levels of success in getting this to work with ruby gems so I wanted to share my findings so others may benefit from my trials and errors.

Attempt 1

The first tip I found for this (thanks to Brandt Lofton on the RadRails mailing list) involves modifying your site_ruby/1.8/rubygems/doc_manager.rb by changing this line

r.document(['--quiet', '--op', rdoc_dir]
+ @rdoc_args.flatten + source_dirs)

To:

r.document(['--quiet', '--op', '--merge', '-r', '--ri-system', rdoc_dir]
+ @rdoc_args.flatten + source_dirs)

You must then run the command:

gem rdoc --all

This will install all of your installed gems rdoc documentation for use by Ri.

NOTE: In my experience, this command must complete or the documentation will not be installed properly. For instance, in InstantRails1.3a, the camping-unabridged.rb file causes problems so I renamed it to camping-unabriged.rb-renamed so it will be skipped.

Attempt 2

Some people have experienced problems (myself included) with those steps above. So, I recently tried to find an alternative approach. I found this
post by Eric Hodel, who implemented a different patch for ruby-core.

I tried following in his footsteps, but I was not successful. However, others seem to have gotten that one to work, so you may have better luck than I did.

Attempt 3

If all else fails, they say the third time is the charm. If you can’t get either of those methods to work, there is one more thing you can do to manually install your gem documentation.

This should work for any ruby code you have. Just change directories to the root of the code you want to be able to search with Ri and run this command:

rdoc --ri-site

This will install your documentation into the share/site directory of your ruby install where Ri will be able to read it.

NOTE: I had problems trying to generate the docs for all of my ruby gems at once so you may want to just do this individually for the ones that matter the most, such as actionpack, activerecord etc.

It may seem like a lot of effort just to be able to see your gem documentation from within Ri, but from my personal experience it is completely worth it. Having the ability to instantly look up the Rails documentation has definitely flattened the learning curve for me with Rails as I instantly can see how stuff works, or what the name of that AJAX method is etc.

Enjoy!

Just over the last month or so I started noticing a growing number of MySQL errors when developing Ruby on Rails applications on Windows. The errors would usually say something like so:

Mysql::Error: Lost connection to MySQL server during query

I have seen these in the past and there were some substantial patches that fixed them in Rails core before the 1.0 release, but all of a sudden they are back again.

I think I may have finally found a solution thanks to a post on the rails mailing list.

Just follow the steps on this blog posting to update your MySQL/Ruby driver and you should be all set:

http://www.vandomburg.net/pages/mysql-ruby-windows

I just ran across this great visual diagram of the prototype javascript library:

http://www.snook.ca/archives/prototype.png

It was put together by Jonathan Snook and is a great cheat sheet if you are working with the prototype library.

I just recently ran across another nice thing you can do with Ruby on Rails that I thought others may find useful. I have developed a few different Rails apps and in several cases, I have found that I really needed a way to perform some process in the background outside of the web server. This could serve a variety of purposes, such as for slicing and dicing your data into reports or performing some resource intensive tasks.

Ruby On Rails provides a simple way to take advantage of your existing Rails code from the command line. For this example, let’s say we want to create a script called do_something_magical. So, we can just create a file in the scripts directory of our Rails app and call it do_something_magical.rb. Then, at the top of this script, just add this one line to make your script run within the Ruby On Rails environment:

require File.join(File.dirname(__FILE__), '../config/environment')

Now this script will be able to access all of your other Rails code. For instance, to include your secret_ingredients model, you can just require it like so:

require 'secret_ingredients'

Likewise, if you have a magic_maker dependency in your lib directory you can include it as follows:

require_dependency 'magic_maker'

I found this to be a great time saver when I need to do some heavy lifting with my existing Ruby On Rails code.

So, I noticed I was receiving a random error from the Gift Hat by one of my ajax auto complete forms.

An ajax submit was occurring without any data, which is impossible from within a browser since a user has to enter data for the ajax form to submit.

Here is the Ajax code in question:

new Ajax.Autocompleter('find_hat', 'find_hat_auto_complete', '/hat/auto_complete_for_find_hat', {indicator:'indicator'})

Thanks to my Exception Notifier setup, I was receiving very detailed emails when the error occurred including this interesting tidbit:

HTTP_FROM : googlebot(at)googlebot.com

It turns out, the googlebot traverses your Ajax code, so beware of the Googlebot or any other random non-human agents. They may be doing things that would otherwise be impossible so plan for these cases as well when building your web apps.

The Gift Hat tour is complete. This provides a nice summary of the major features available within the Gift Hat. Please check it out.

Feedback is welcome in the comments for this post.

Well, I was planning on spacing out the posts of what’s in my toolbox, but another tool in my toolbox called RadRails just won the Best Developer Tool award at EclipseCon. So, it seems like now is a good time to mention it.

RadRails was put together in an incredibly short time by a team of three developers that are in college. Very impressive. It also includes the work of several others including the Eclipse Framework, RDT plugin and Subclipse plugins.

One of the coolest new features they just introduced is a key binding to intelligently switch between your Controllers and your Views based on the Rails naming conventions. This is a great time saver. This is just one of those “Why didn’t anybody else think of that” types of features that is a welcome addition to an already wonderful tool.

Other notable features include:

• An Outline view of your ruby files
• Realtime syntax checking
• Color syntax highlighting for CSS, Javascript, HTML, RHTML and Ruby files
• An RI documentation viewer for looking up Ruby APIs
• Server management tools for starting and stopping your WEBbrick servers
• Integrated debugging tools
• Source code generator tools
• And much more…

If you haven’t checked it out, I highly recommend it. I developed The GiftHat.com entirely using this tool. Give it a try. You won’t be disappointed.

When working in a web environment, it can be difficult to know the health of your application without digging through some log files or worse, waiting for the customer to complain.

Ruby On Rails provides a nice and easy alternative for emailing you whenever an error occurs within your application.

And best of all, it is a plugin called exception_notification, which requires very little effort to roll into your application. To install the exception_notification plugin, just type the following from the root of your rails app:

> ruby script\plugin install exception_notification

And then any controller that you want to notify you of errors needs to include ExceptionNotifiable. In my case, I would like to be notified for all controllers, so I added this into my application controller:

[ruby]class ApplicationController < ActionController::Base
include ExceptionNotifiable[/ruby]

Then, you just need to configure the email address to send the error notifications in your config\environment.rb file:

[ruby]ExceptionNotifier.exception_recipients =
%w(some-admin@email.com another-admin@email.com)[/ruby]

And that's it!

Note: One prerequisite to doing all of this is you must also configure your ActionMailer for sending emails.

All good things must start somewhere, and this is as good a place as any. My name is Tom Davies and I am starting this blog to share with you my thoughts on things ranging from software development to current projects that I am working on.

The first thing I would like to share is a website I developed called the GiftHat.com.

The Gift Hat is a site for storing and sharing your wishlists with your friends and family. I am currently seeking beta testers so if you have a few moments and would like to participate, please sign up.

The Gift Hat was developed using RubyOnRails. In future posts, I will expand on some of the technologies and techniques I used to develop the Gift Hat.