Posts tagged with: "plugins"
Easily Search on ActiveRecord Attributes
Rails’s named_scopes are great, and the ability to chain named_scopes together are even better. I am sure many of us have done something like this before:
User.active.live_in('Virginia')
That would give you the active users who live in the state of Virginia. You would define something like these in your User model:
named_scope :active, lambda { |status| { :conditions => { :status => status } } }
named_scope :live_in lambda { |state| { :conditions => { :state => state } } }
One recent client project has a model where the database table has 30-something columns. Doing these named_scopes became tedious and repetitive. That makes it not fun anymore.
So Dave Pranata and I wrote the searchable_attributes Rails plugin so we could stop worrying about explicitly defining these named_scopes once and for all.
To use it, you just install it like any other Rails plugin:
script/plugin install git://github.com/rayvinly/searchable_attributes.git
The plugin will automatically define a bunch of named_scopes for you if you include this in your model:
class User < ActiveRecord::Base searchable_attributes end
You can then search on your models with something like this:
def index
@users = User.with_first_name_equal('Gilbert').with_last_name_equal_if_not_null('Arenas').with_address_like('Main Street').with_age_greater_than(25).with_state_equal(['VA', 'MD', 'DC']).with_position_end_with('Guard').with_salary_within_inclusive((100..10000)).with_injured_equal(true).with_join_date_greater_than_or_equal_to(5.years.ago)
end
Take a look in the plugin’s lib/searchable_attributes.rb for a list of automatically defined named_scopes.
Fetches: Bringing Your ActionController its Slippers
There is a piece of code that shows up more than 80% of the controllers that I write, and it goes a little something like this:
class UsersController < ApplicationController
def user
@user ||= User.find(params[:id])
end
helper_method :user
end
A simple memoization method to allow me to easily grab the parameter-referred user in all of my actions. If I’m using nested routes, that means I can write two, maybe three of these methods into a controller. I’m basically using slight variations on the same code 20 different times in an application. Since we live in a world that loves to be DRY, I thought, “I can do better.”
Fetches: Memoizing Your Parameter Record Retrieval
Fetches is a simple extension to ActionController that lets you simply define those kinds of fetch methods on a one-line command. For the example above, I can rewrite it like so:
class UsersController < ApplicationController fetches :user end
That’s pretty useful! Not only can I call the “user” method from the controller, but it’s automatically helperized so that I can use the same call in my views. Of course, there are times when more advanced fetching is called for, say using a method other than find or storing to a different variable name. Let’s take a look at a slightly more complex example:
# assuming a route like /users/:user_id/articles/:id class ArticlesController < ApplicationController fetches :user, :as => :author, :from => :user_id, :using => :find_by_login fetches :article end
Now if I were to call “author” in any of my controller actions, it would be equivalent to User.find_by_login(params[:user_id]). Similarly, calling “article” is equivalent to Article.find(params[:id]). The “from” option can also take a Proc in case your fetching is not simply a parameter key:
class UsersController < ApplicationController
fetches :user, :from => Proc.new{ |c| c.params[:user_id] || c.params[:id] }
end
The main advantages to fetches are brevity, clarity and DRYness. I’ve found that this method covers every use case for parameter-based fetching that I’ve needed, and as such provides a much simpler, more readable, and shorter way to fetch models for use in your controller and views.
Installation
Fetches is available as a gem as well as in traditional plugin format. To install
as a gem, add this to your environment.rb:
config.gem 'mbleigh-fetches', :source => 'http://gems.github.com', :lib => "fetches"
To install it as a traditional plugin:
script/plugin install git://github.com/mbleigh/fetches.gitResources
The source is available on GitHub, the Acts As Community project is there for general discussion, and the Lighthouse is there for bugs and feature suggestions.
UPDATE: A commenter requested that the plugin be able to handle creation of new records in addition to fetching existing records. I have added in the :initialize option to do just this. Examples:
fetches :user, :initialize => true # initialize from params[:user]
fetches :user, :initialize => :author # initialize from params[:author]
fetches :user, :initialize => Proc.new{ |c| {:login => c.params[:login], :email => c.params[:email]} }
Mobilize Your Rails Application with Mobile Fu
Let's face it, iPhone interfaces are awesome, but they can only cater to a fraction of the mobile market. What are you to do if you want to satisfy the rest of the mobile world? Mobile Fu helps to make this job much easier by automatically detecting mobile devices that access your Rails application. People can access your site from a Palm, Blackberry, iPhone, Nokia, etc. and it will automatically adjust the format of the request from :html to :mobile.
Learn Mobile Fu
First off, just install the Mobile Fu plugin into your Rails application.
script/plugin install git://github.com/brendanlim/mobile-fu.git
Start by adding this one line to your ApplicationController.
class ApplicationController < ActionController::Base has_mobile_fu end
Once this is in place, any request that comes from a mobile device will be be set as :mobile format. It is up to you to determine how you want to handle these requests by creating the .mobile.erb versions of your views that are to be requested. Also, I recommend that you setup a before_filter that will redirect to a specific page depending on whether or not it is a mobile request. How can you check this?
is_mobile_device? # => Returns true or false depending on the device
You can also determine which format is currently set in by calling the method below.
in_mobile_view? # => Returns true or false depending on current req. format
If you want the ability to allow a user to switch between ‘mobile’ and ‘standard’ format (:html), you can just adjust the mobile_view session variable in a custom controller action.
session[:mobile_view] # => Set to true if request format is :mobile and false
if set to :html
What About Custom Mobile Styling?
Different devices need different styling. Don’t worry though, we’ve got this baked in to Mobile Fu (thanks to Intridea's own Michael Bleigh, who created Browserized Styles for letting me modify his code). If you are including a css or sass file via stylesheet_link_tag, all you have to do is add _device to the name of one of your files to override your styling for a certain device. The stylesheet that is loaded is dependant on which device is making the request.
Supported stylesheet override device extensions at the moment are: blackberry, iphone, mobileexplorer, nokia, palm
e.g., Accessing a page from a Blackberry. <%= stylesheet_link_tag 'mobile.css' %> Ends up loading mobile.css, and mobile_blackberry.css if the file exists.
Feature Requests
You can check out Mobile Fu's very own project page at Acts As Community. If you have any problems or would like me to add a certain feature, please create a ticket at http://blim.lighthouseapp.com/projects/14490-mobile-fu/. Also, feel free to fork Mobile Fu and make any enhancements you please from its GitHub location at: http://github.com/brendanlim/mobile-fu/tree/master
UberKit Update: UberForms To Ease Form Building
Last week the Uberkit kicked off with some helpers to make your menu-building much easier. This week we’re following it up with UberForms, a Form Builder that DRYs up your repetitive form stresses. Let’s see how it works!
Building an Uber-er Form
UberForms automatically generate all of the standard boilerplate HTML that goes around your forms. By wrapping everything up in an easily style-able package, it becomes a much easier business to make new forms as well as re-use form styling across projects. With the form markup taken care of, you can focus on the more important aspects of your UI building and keep your views deadly clean.
While UberForms are available as a standard form builder (Uberkit::Forms::Builder), you may find it more useful in its helper form (automatically available when the UberKit plugin is loaded:
<% uberform_for :user do |f| %> <%= f.text_field :login %> <%= f.password_field :password %> <%= f.submit "Submit"%> <% end %>
This will automatically be translated into some nice, CSS-ready HTML:
<form method="post" class="uberform" action="/users">
<div class="field_row">
<label for="user_login">Login:</label>
<input type="text" size="30" name="user[login]" id="user_login" class="text_field"/>
<br/>
</div>
<div class="field_row">
<label for="user_password">Password:</label>
<input type="password" size="30" name="user[password]" id="user_password" class="password_field"/>
<br/>
</div>
<button type="submit">Submit</button>
</form>
You can also change the label, add a description or help text to a field by adding the relevant options:
<%= f.text_field :login, :label => "Username",
:help => "Only a-z and underscores.",
:description => "The name you will use to log in." %>
Becomes…
<div class="field_row"> <label for="user_login">Username:</label> <input type="text" size="30" name="user[login]" label="Username" id="user_login" help="Only a-z and underscores." description="The name you will use to log in." class="text_field"/> <span class="help">Only a-z and underscores.</span> <span class="description">The name you will use to log in.</span> <br/> </div>
Finally, you can create custom HTML inside an UberForm field by passing a block:
<% f.custom :label => "State", :for => "user_state" do |f| %> <%= state_select :user, :state %> <% end %>
Becomes…
<div class="field_row">
<label for="user_state">State:</label>
<div class="pseudo_field">
<select id="user_state">...</select>
</div>
<br/>
</div>
Easy, right? That’s all there is to it, now you can be UberForming to your heart’s content
Installation
To install the UberKit (which includes more than just forms) you can do so either as a gem or a traditional plugin. As a gem, just add this to your environment.rb:
config.gem 'mbleigh-uberkit', :lib => 'uberkit', :source => 'http://gems.github.com'
As a traditional Rails plugin:
script/plugin install git://github.com/mbleigh/uberkit.gitThe Future of the UberKit
These two pieces are pretty helpful, but there’s more coming for the UberKit. Stay tuned for more updates, including more hooks and ways to customize the UberKit to fit your needs as a developer.
UberKit: Building A Rails UI Swiss-Army Knife
So many of components we build into our web applications have a grain of an extractable element, a standardization waiting to happen. Starting today, I am putting together a “Standard UI Kit” for all of the tools that help me build interfaces faster. Together, they are called the UberKit. This week, the first segment is coming: UberMenus.
UberMenu: Abstract Menu Generation
Most people who build interfaces will build their menus with the same structure over and over. I finally took the time to abstract this out into a single helper that can pretty much serve all of my navigational needs. Here’s how you use it in a view:
<% ubermenu do |m| %> <% m.action 'Home', '/' %> <% m.action 'Users', users_path %> <% m.action 'Log Out', logout_path, :class => "special" %> <% end %>
Becomes this HTML (assuming you’re at the document root):
<ul> <li class="first current first_current"><a href="/">Home</a></li> <li><a href="/users">Users</a></li> <li class="special last"><a href="/logout">Log Out</a></li> </ul>
The current class will automatically be set on whichever page responds to the built-in Rails helper current_page? and the action syntax behaves just like a link_to. If a given action has multiple classes, they will also be joined with underscores as an additional class for browsers that do not support multiple class declarations. But in addition to easily creating simple menus, you can also easily generate multi-level navigation menus:
<% ubermenu 'nav' do |m| %>
<% m.action 'Home', home_path %>
<% m.submenu 'Services', services_path do |s| %>
<% s.action 'Service A', service_path('a') %>
<% s.action 'Service B', service_path('b') %>
<% end %>
<% end %>
Which will become this HTML:
<ul id='nav'>
<li class='first current first_current'><a href="/">Home</a></li>
<li class='last'><a href="/services">Services</a>
<ul>
<li><a href="/services/a">Service A</a></li>
<li><a href="/services/b">Service B</a></li>
</ul>
</li>
</ul>Installation
UberKit is available both as a gem and a traditional plugin. For the gem version, add this to your environment.rb:
config.gem 'mbleigh-uberkit', :source => "http://gems.github.com/", :lib => "uberkit"
Or as a traditional plugin:
script/plugin install git://github.com/mbleigh/uberkit.gitFuture of the UberKit
While UberMenu is a useful tool, the UberKit will continue to grow over time, so stay tuned for additions (next on the slate: UberForm). It may also grow to include some common styles and javascripts that can be used in conjunction with the helpers to provide an even easier track to a full-fledged UI.
Resources
As always, the source is on GitHub and there is an Acts As Community Profile available as well. If you have any problems with it or would like to request new features, enter them on the Lighthouse project.
RankFu: Expressive user roles for Rails
Almost every Rails developer has written an app with more than one user role, but when is_admin? isn’t enough, where do you go? RankFu aims to solve this by giving you a rich toolset for roles. Now it’s free to allow users to have more than one role, so you can have modifiers such as ‘Trusted’ and ‘New’ trivially. It’s also easy to have sets of roles, with administrators outranking moderators. Sets are optional though, so you’re free not to put Telephone Sanitizers in one due to their obvious lack of importance.
Throughout this piece, I’ll be talking about the ubiquitous User model, but you can use RankFu with any model you wish to.
h3. Rankin’ Fu
When you install RankFu, you can add several new methods to your models:
User#has_role?
User#has_role
User#"#{role}?"
User#"#{role}_exactly?" #This forces an exact comparison, useful if you want to test for a role which has a superset (e.g. moderators and administrators)
User#"make_#{role}
User#"remove_#{role}"
User#rank #Returns a string listing all roles, modifiers first eg: "Trusted Administrator"
User#roles #Returns an array of role names.
There is also some sugar for disabling users, to make your code more readable. These examples assume the existence of role with :disabled as its key:
User#disable_user User#enable_user User#enabled?
Building on this, you can easily clean up your views. I DRY’d up many instances login check logic.
def logged_in_as_mod? def logged_in_as?(user) def logged_in_as_friend_of?(user) def logged_in_as_or_as_friend_of?(user)
There might have been a few others, but I don’t want to give any more ammunition to those who accuse me of pedantry.
InstallationFu
The easiest way to install is as a standard Rails plugin:
script/plugin install git://github.com/mjt/rank_fu.gitAfter installing this plugin, you’ll want to start by performing some admin:
script/generate rank_fu user script/generate rank_fu roles #create migration for roles
After that, you’ll probably want to add roles to your user model, so just add this line:
knows_rank_fu
Then you need to create some roles. I suggest using the excellent Seed Fu plugin so you can do something like this:
Role.destroy_all
roles = [ {:id => 1, :key => “root”, :name=> “Superuser”, :value => 2**22, :set => 1},
{:id => 2, :key => “admin”, :name=> “Administrator”, :value => 2**21, :set => 1},
{:id => 3, :key => “moderator”, :name=> “Editor”, :value => 2**20, :set => 1},
{:id => 5, :key => “member”, :name=> “Member”, :value => 2**10, :is_default => true}]roles.each do |role|
Role.create role
end
What’s going on here?
Not much.
Internally, bitwise arithmetic is used to store each model’s role-state. Once a model knows RankFu, you can assign and remove roles freely, knowing that RankFu is a good citizen and uses update_attribute internally.
You may also find that you can reduce your use of STI by separating users by roles.
Please feel free to leave any feedback in the comments.
Using RSpec and Autotest While Writing Rails Plugins
RSpec is a great tool that has come to replace Test::Unit for many Rails developers. Autotest makes it go even faster, and has become an indispensable part of my development environment. However, it has always been somewhat-to-extremely difficult to use RSpec when developing Rails plugins. In this post I will walk through step-by-step how to get RSpec and Autotest working with your plugin.
This plugin is assuming that you are running Rails >= 2.1 and have already installed RSpec and RSpec::Rails as plugins in your Rails project like so:
script/plugin install git://github.com/dchelimsky/rspec.git script/plugin install git://github.com/dchelimsky/rspec-rails.git
And also gotten RSpec up and running by calling script/generate rspec.
Generate It
Luckily, I wasn’t the first person who ever wanted to create a plugin that was tested with RSpec. The Rspec Plugin Generator will do most of the heavy lifting for us when we start out. Just install it like so:
script/plugin install git://github.com/pat-maddox/rspec-plugin-generator.git
And you’re ready to get started. I’m assuming here that this is a brand new plugin, if it’s already in development you may need to run this in a fresh directory and then copy/paste files as needed to glue it together. Let’s say I’m writing a plugin called new_fu. I can generate an RSpec-ready plugin simply by calling:
script/generate rspec_plugin new_fu
This will generate the standard plugin structure as well as some extra files:
create vendor/plugins/new_fu/spec create vendor/plugins/new_fu/spec/spec_helper.rb create vendor/plugins/new_fu/spec/new_fu_spec.rb
You can take a look at these to see how they work, but pretty simply they hook your plugin up so that it can be run with rake spec:plugins. Let’s add a simple example to our new_fu_spec.rb file:
require File.dirname(__FILE__) + '/spec_helper' describe "NewFu" do it "should have a pending spec" end
Now if you run rake spec:plugins you should see one pending spec. Congratulations, your plugin is now running on RSpec!
Autotest Like a Champ
Ok, so now we’re up and running with RSpec on our plugin. That’s great, but if you have several plugins in the same Rails app that all have specs, it starts to get messy when you run that rake spec:plugins. Not to mention how long it takes between runs! We need to get an autotest setup like we have for our main Rails app!
I struggled with getting this to work for a long time, so thanks to this post on Rails Symphonies for finally pointing me in the right direction. First we need to create an autotest/discover.rb file in our plugin’s lib directory. In that file, put this code:
$:.push(File.join(File.dirname(__FILE__), %w[.. .. rspec])) Autotest.add_discovery do "rspec" end
This gets us almost exactly where we want to be. However, the first time I ran it I had two problems: some specs that I had written were strangely failing, and it wasn’t in color or following the rest of my spec.opts preferences from my main app!
To remedy this, we need a spec.opts in the spec directory of the plugin. You can either copy and paste it in from your Rails app (my recommendation if you are publishing your plugin) or you can just create a softlink back to it:
ln -s ../../../../spec/spec.opts spec.opts
That’s it! Now if you run autotest you should be running all of the specs for your plugin just as you would if you were running them for your app. Note that this doesn’t hook in to your app’s autotest, which may be desirable or undesirable to your specific needs.
SubdomainFu: A New Way To Tame The Subdomain
An extremely common practice for Rails applications is to provide keyed
access through subdomains (i.e. http://someaccount.awesomeapp.com/). However,
there has never been a real unified convention for handling this functionality.
DHH’s Account Location
works for some circumstances but is more tailored for a Basecamp domain model
(i.e. the app is on a separate domain from all other functionality, so you
can always expect a subdomain) than the more common usage of one domain only.
SubdomainFu aims to provide a simple, generic toolset for dealing with subdomains
in Rails applications. Rather than tie the functionality to something specific
like an account, SubdomainFu simply provides a foundation upon which any
subdomain-keyed system can easily be built.
Usage Fu
SubdomainFu works by riding on top of the URL Rewriting engine provided with
Rails. This way you can use it anywhere you normally generate URLs: through
url_for, in named routes, and in resources-based routes. There’s a small
amount of configuration that is needed to get you running (though the defaults
should work for most).
To set it up, you can modify any of these settings (the defaults are shown):
# in environment.rb
# These are the sizes of the domain (i.e. 0 for localhost, 1 for something.com)
# for each of your environments
SubdomainFu.tld_sizes = { :development => 0,
:test => 0,
:production => 1 }
# These are the subdomains that will be equivalent to no subdomain
SubdomainFu.mirrors = ["www"]
# This is the "preferred mirror" if you would rather show this subdomain
# in the URL than no subdomain at all.
SubdomainFu.preferred_mirror = "www"
Now when you’re in your application, you will have access to two useful
features: a current_subdomain method and the URL Rewriting helpers.
The current_subdomain method will give you the current subdomain or
return nil if there is no subdomain or the current subdomain is a mirror:
# http://some_subdomain.myapp.com/ current_subdomain # => "some_subdomain" # http://www.myapp.com/ or http://myapp.com/ current_subdomain # => nil # http://some.subdomain.myapp.com current_subdomain # => "some.subdomain"
The URL rewriting features of SubdomainFu come through a :subdomain option
passed to any URL generating method. Here are some examples (in these examples,
the current page is considered to be ‘http://intridea.com/’):
url_for(:controller => "my_controller", :action => "my_action", :subdomain => "awesome") # => http://awesome.intridea.com/my_controller/my_action users_url(:subdomain => false) # => http://intridea.com/users # The full URL will be generated if the subdomain is not the same as the # current subdomain, regardless of whether _path or _url is used. users_path(:subdomain => "fun") # => http://fun.intridea.com/users users_path(:subdomain => false) # => /users
While this is just a simple set of tools, it can allow the easy creation
of powerful subdomain-using tools. Note that the easiest way to locally
test multiple subdomains on your app is to edit /etc/hosts and add
subdomains like so:
127.0.0.1 localhost subdomain1.localhost subdomain2.localhost www.localhost
Adding an entry for each subdomain you want to use locally. Then you need
to flush your local DNS cache to make sure your changes are picked up:
sudo dscacheutil -flushcache
Installation
SubdomainFu is available both as a traditional plugin and as a GemPlugin
for Rails 2.1 and later. For a traditional plugin, install like so:
script/plugin install git://github.com/mbleigh/subdomain-fu.git
For a GemPlugin, add this dependency to your environment.rb:
config.gem 'mbleigh-subdomain-fu', :source => "http://gems.github.com/", :lib => "subdomain-fu"
Implementing A Simple Account Key System
Let’s take this functionality and implement a simple account-key system based
off of the subdomain. We’ll start with some controller code (assuming that
we have an Account model with a ‘subdomain’ field):
class ApplicationController < ActionController::Base
protected
# Will either fetch the current account or return nil if none is found
def current_account
@account ||= Account.find_by_subdomain(current_subdomain)
end
# Make this method visible to views as well
helper_method :current_account
# This is a before_filter we'll use in other controllers
def account_required
unless current_account
flash[:error] = "Could not find the account '#{current_subdomain}'"
redirect_to :controller => "site", :action => "home", :subdomain => false
end
end
end
That’s really all we need for a basic setup, now let’s say we have a
ProjectsController that you must specify an account to access:
class ProjectsController < ApplicationController # Redirect users away if no subdomain is specified before_filter :account_required end
There’s lots more you can do with the plugin, but this is a simple use case
that everyone can relate to.
Resources and Plans
A feature that I hoped would make it to the first release of SubdomainFu
but is now a planned feature is subdomain-aware routing so that you can
add conditional subdomain routes to your routes.rb file. Keep an eye
out for more on that in the future.
In the meantime, the project will live at its home on Acts As Community for intermittent
updates, is available on GitHub as always, and bugs/feature requests may
be passed on through the Lighthouse.
GemPlugins: A Brief Introduction to the Future of Rails Plugins
The new Gem Dependencies of Rails 2.1 give developers an easier-than-ever ability to keep track of and maintain the various library dependencies inherent with any project. However, a much-overlooked additional feature of the Gem Dependencies is the ability to package traditional Rails plugins as a gem and have them hooked in properly. This article is designed as an introduction to how to write and use plugins as gems in Rails projects.
The Basics
The basic method by which this is achievable is that any plugin included through a config.gem command will automatically have the gem-packed file rails/init.rb run upon Rails’s initialization. All it takes is a little bit of effort, and any Rails plugin can be packaged as a gem and easily depended upon through gem dependencies.
You may be wondering why this is a “big deal.” Plugins are already dead simple to install in Rails (and you can even script/plugin install straight from Git now!), why do we need GemPlugins? It’s simple, really: RubyGems are a rock-solid established way of easily distributing versioned reusable bits of code. Using gems for plugins allows for a greater standardization of the way in which plugins are maintained and distributed, as well as a simple path for version-locking to ensure compatibility with legacy code etc.
Another reason that GemPlugins are important is that they provide a level of abstraction from Rails: by releasing a gem rails/init.rb you could also use the same exact code to release a Merb plugin or any other framework that supports gemified add-ons. I think you will begin to see a number of cross-framework plugins be developed as Rails gets some company and shares alike.
Using a GemPlugin
First, let’s go through the process required to use an existing gem plugin. I’m going to be using my Acts As Taggable On plugin as an example throughout because I just recently went through the process of making it available as a gem.
First, you will need to include the dependency in your environment.rb file. I’m assuming here that most plugins are going to be hosted on GitHub, but the same should be true for any gem source.
# in environment.rb config.gem "mbleigh-acts-as-taggable-on", :source => "http://gems.github.com", :lib => "acts-as-taggable-on"
This is the standard usage of gem dependencies, and for more info on this you can see Ryan Daigle’s post or watch the RailsCast on the subject. Now assuming that you don’t already have the gem in question installed, it’s simple to grab it:
rake gems:install
This will automatically install any gem dependencies in your project, and will tell you what’s happening the same as if you had run gem install from the command line.
That’s it! Once you have successfully installed the necessary gem, you can simply start up your Rails server and the plugin will be loaded and initialized as though it were living in your vendor/plugins directory.
Now that you know how to use a GemPlugin, I’ll show you how you can take an existing plugin and gemify it quickly and painlessly.
Making a GemPlugin
Let’s say I have a plugin called awesome_fu that lives on GitHub at mbleigh/awesome-fu. I’ve already released this plugin, it works great, and now I want to make it compatible with GemPlugins.
First, let’s create a gemspec called awesome-fu.gemspec in line with the requirements for the GitHub Gem Repository. In order to make the file list, I usually find it’s easiest to “find **” in the plugin directory, then copy it into TextMate, make the modifications I need for manifest (using a regular expression to quote each of the files), and saving it in the spec. If you have only a few files in your plugin, it may be easier just to add them by hand.
Next we need to add rails/init.rb. This is a little bit troublesome, because we still want our plugin to work if installed through the traditional method, so we also need init.rb to run the same code (this is automatically fine in edge Rails). What I did for my plugin is copy all of my init.rb code into rails/init.rb and then change init.rb to the following:
require File.dirname(__FILE__) + "/rails/init"
Now they both run the same code without any kind of replication, great! This means that now I have set up my plugin to work equally as a GemPlugin or a traditional plugin with just a couple minutes of work.
All that’s left to do is switch on the RubyGem setting for my GitHub project, update the README, and push! Now anyone will be able to easily require the plugin as a gem dependency and you will get all of the accolades associated with releasing your plugin the “new and hip” way.
Caveat Coder
The one problem with GemPlugins that I have run into is that if you unpack your gems using “rake gems:unpack” the rails/init.rb file is not run on initialization. This is a known issue that is supposed (?) to be resolved but I have still experienced this problem in my experiments. Hopefully this issue will be fully resolved in edge Rails soon and the glorious future of GemPlugins can begin.
Acts As Taggable On Grows Up
Acts As Taggable On (original post here), the tagging plugin with custom tag contexts, has gathered up some great new features over the past weeks thanks to the efforts of the community as well as fellow Intrideans Pradeep Elankumaran and Brendan Lim. I just wanted to take this opportunity to go over some of what’s new and interesting in the world of acts_as_taggable_on.
Community Fixes
First, Peter Cooper was kind enough to submit a patch that allows acts_as_taggable_on to work with Rails 2.1’s named_scope when using find_options_for_tag_counts.
Secondly, the much requested support for Single Table Inheritance is finally in! It was just a matter of using a class inheritable attribute instead of a class instance variable, and big thanks to slainer68 for hunting that down and taking the time to submit a patch.
If there’s anything you’ve hacked on to Acts As Taggable On, I urge you to submit a patch to the Lighthouse Project. I try to get new patches integrated into the codebase as quickly as possible, so please do submit anything!
During the Community Code Drive at RailsConf two great features were added: taggers and related objects.
Taggers
Tags can now have ownership, allowing for such things as User-tracked tags and more. This was a requested feature and something that I’d been looking forward to myself. Here’s the usage:
class User < ActiveRecord::Base acts_as_tagger end class Photo < ActiveRecord::Base acts_as_taggable_on :locations end @some_user.tag(@some_photo, :with => "paris, normandy", :on => :locations) @some_user.owned_taggings @some_user.owned_tags @some_photo.locations_from(@some_user)
Find Related
Another request (and another great idea) is the ability to find related objects by similar tags. This is now available through the @object.find_related_on_tags syntax:
@bobby = User.find_by_name("Bobby")
@bobby.skill_list # => ["jogging", "diving"]
@frankie = User.find_by_name("Frankie")
@frankie.skill_list # => ["hacking"]
@tom = User.find_by_name("Tom")
@tom.skill_list # => ["hacking", "jogging", "diving"]
@tom.find_related_on_skills # => [<User name="Bobby">,<User name="Frankie">]
@bobby.find_related_on_skills # => [<User name="Tom">]
@frankie.find_related_on_skills # => [<User name="Tom">]
Gemified!
Acts As Taggable On now works as a GemPlugin in Rails. This is a new way (as of Rails 2.1) of distributing plugins as gems and having them still automatically link up and do their magic. To use it as a gem, add it to your config/environment.rb like so:
config.gem "mbleigh-acts-as-taggable-on", :source => "http://gems.github.com", :lib => "acts-as-taggable-on"
Now you should be able to get the latest version of the plugin just by running rake gems:install. However, this hasn’t been working for me so the alternative is just to install the gem directly:
gem install mbleigh-acts-as-taggable-on --source http://gems.github.com/Now when you run your Rails app, even though it’s not in vendor/plugins it should be running! To make sure, look for this line on startup:
** acts_as_taggable_on: initialized properlyThere are still a couple of issues outstanding in Rails regarding GemPlugins (if you unpack it, it will not run the initialization properly for some reason), but I wanted to give everyone the latest and greatest way to install the plugin possible. It will still work fine using the conventional methods as well.
Community and Future
I’ve been really happy with the response and support of the community, and I would like to do everything possible to cultivate future participation. To that end, I have created an Acts As Community Project for acts_as_taggable_on that will hopefully provide some casual communication about the project. Feel free to post on the wall or in the forums, and look out for additions soon.
Finally, the area of the plugin that still needs some work is tag caching. This is not a particular area of my expertise, so I’m hoping that someone from the community will write up some specs that flesh out the caching functionality in new and interesting ways.
Thanks for all of the patches, and I hope you continue to enjoy using Acts As Taggable On!
UPDATE (6/10/08): The improvements keep on rolling! After writing the post, I went off on a tangent and decided to make the plugin work both traditionally and as a gem. See more details above in the “Gemified” section.
From Param: How URL-Based Fetching Ought to Be
The addition of RESTful routing and the #to_param method in Rails has undoubtedly improved both the ease and usefulness of URL generation in Rails apps. However, there has come to be a rather insidious tendency to have an auto-generated id as the true reference for a given item. This may make sense for some or even many apps, but by and large records should be referred to by their content, not their ids, in URLs if at all possible. With this goal in mind, I have released from_param, a simple addition to ActiveRecord that makes it dead simple to use better URL finders.
Example
First of all, from_param is meant to simply be the complement of to_param, that is, you should be able to pass Model.from_param(some_parameter) the same way you would pass Model.from_xml(some_xml). Let’s examine how this works in practice:
class User < ActiveRecord::Base
def to_param
"#{id}-#{login.downcase}"
end
end
class UsersController < ApplicationController
# GET /users/1-mbleigh
def show
@user = User.from_param(params[:id]) # => <User id=1 login="mbleigh">
end
end
Simple enough, and it should look very familiar except that instead of a User.find or User.find_by_id, we have User.from_param. In fact, that’s exactly what this code does: from_param by default will call find_by_id since that is how the default to_param is configured.
Now let’s take something a little more complicated: a blog post title. I definitely don’t want an id in the URL if it’s a permalink, so how can I make an arbitrary parameter found as easily as the id? Simple, just add a param column to your table! Take a look:
class Post < ActiveRecord::Base
def to_param
"#{created_at.strftime("%Y-%m-%d")}-#{title.gsub(" ","-").downcase.gsub(/[^a-z0-9-]/,"")}"
end
end
class PostsController < ApplicationController
# GET /posts/2008-04-26-from-param-plugin-released
@post = Post.from_param(params[:id]) # => <Post title="From Param: Plugin Released" created_at="2008-04-26">
end
From Param will auto-magically save the to_param of your model to the specified parameter column (defaults to “param” but you can set it by calling set_param_column) and then automatically know to find by that column if it exists when from_param is called. This way, all you have to do is define a to_param that will be unique to your record and everything else is handled for you!
This plugin is really quite simple, but it establishes a convention that I feel has been missing from Rails for some time: a standard method to call to retrieve a record based on its URL parameter.
Installation
To install the plugin on Edge Rails or Rails 2.1 and greater:
script/plugin install git://github.com/mbleigh/from_param.git
On earlier versions of Rails:
git clone git://github.com/mbleigh/from_param.git vendor/plugins/from_param
Resources
If you have any suggestions for expanding the usefulness of the plugin or run into any problems, please report them on the From Param Lighthouse Project.
Seed Fu: Simple Seed Data for Rails
The issue of pre-loading needed data for a Rails application has always been somewhat confusing and difficult. A great post on Rail Spikes discusses the issue in-depth and offers a number of different solutions, but ultimately they all seem just a little short of the desired simplicity. By combining a few of the ideas and adding a few of my own, I have created a seeding system that I feel is very straightforward and easy to use.
Borrowing the basic premise of the db-populate plugin, Seed Fu is based around loading ruby scripts located in db/fixtures via a Rake task. What db-populate doesn’t offer is a clear syntax for describing the records to be seeded. That’s where Seed Fu comes in.
Usage
First, just create a new ruby script in db/fixtures (and create the directory itself, obviously). Any script that you drop in this folder will be automatically run when you execute your seeding rake task. Additionally, you can load environment-specific data by adding scripts in a folder of the same name (i.e. db/fixtures/development. In these scripts you can execute arbitrary Ruby code with the full Rails environment loaded; however, you should remember that this code will be executed every time the rake task is called and should not cause duplication or destroy anything that can’t be retrieved. The syntax for Seed Fu works as follows (with a User model as an example):
# db/fixtures/users.rb # put as many seeds as you like in User.seed(:login, :email) do |s| s.login = "admin" s.email = "admin@adminnerson.com" s.first_name = "Bob" s.last_name = "Bobson" end User.seed(:login, :email) do |s| s.login = "michael" s.email = "michael@abc.com" s.first_name = "Michael" s.last_name = "Bleigh" end
The seed method is available on any ActiveRecord. It takes as parameters the ‘constraints’ for that seeding; in other words, the fixed attributes that will not change in the record’s life. The constraints are used to find the record and update instead of creating it with the attributes provided if it already exists. This way your seeds can change without mucking with other live data on your server.
Once you have set up your fixtures, it’s simple to run them:
rake db:seed
Or if you want to run them for a targeted environment:
rake db:seed RAILS_ENV=production
Installation
In edge Rails or Rails 2.1 and beyond:
script/plugin install git://github.com/mbleigh/seed-fu.git
In previous versions of Rails:
git clone git://github.com/mbleigh/seed-fu.git vendor/plugins/seed-fu
I have some ideas for the expansion of this plugin (loading from CSV for larger datasets, etc.), so stay tuned! If you have ideas for additional features or encounter any problems, I have set up a Lighthouse project for your enjoyment.
SMS Fu - Quickly & Easily Send Text Messages
Having had to develop apps that relied on the ability to send text messages to members, I thought that it would be a good idea to turn some of that functionality into a plugin that would be easy to use. SMS Fu gives you the ability to be able to send text messages from your Rails app in less than five minutes. There’s no third-party gateway needed, as the phone number is converted into an e-mail address, which makes it deliverable to any phone.
Installation
git clone git://github.com/brendanlim/sms-fu.git vendor/plugins/sms_fu
Usage
Supported Carriers: Alltel, Ameritech, AT&T, BellSouth Mobility, BlueSkyFrog, Boost Mobile, Cellular South, Fido, Metro PCS, PSC Wireless, Qwest, Southern Link, Sprint, Suncom, T-Mobile (US/UK/Germany), Virgin Mobile, Verizon Wireless, Vodafone (UK,Italy,Japan)
To use SMS Fu, all you have to do is include SMS Fu in one of your controllers.
class ExampleController < ApplicationController include SMSFu end
After this, go to /config/sms_fu.yml to change the default reply-to address with your own.
Phone numbers must not include any non-numeric characters, with the exception of ‘+’ for International numbers. The three required parameters are the phone number, carrier, and the message itself. To find out just what you need to pass for the carrier, check the yaml file. The one line below will deliver a nice ‘Hello World!’ straight to your phone.
deliver_sms("5555555555","AT&T","Hello World!")
Since most non smart-phones only support up to 128 characters, you’re allowed to specify a limit to truncate the message delivered.
deliver_sms("5555555555","AT&T","Really long message ...", :limit => 128)
If you feel like rolling your own mailer, and not using SMS Fu to handle this, you can retrieve the the converted e-mail address for the phone number and carrier supplied.
get_sms_address("5555555555","AT&T")
That’s all there is to it! If you want to add your own carriers, just edit sms_fu.yml.
Acts as Readable - Drop-in 'mark as read' functionality
When writing an application there’s a number of times where it can be very useful to know whether or not a user has seen or accessed a piece of information. I recently had to write a solution to such a need and have wrapped up the result in a plugin for your enjoyment.
ActsAsReadable allows you to create a generic relationship of items which can be marked as ‘read’ by users. This is useful for forums or any other kind of situation where you might need to know whether or not a user has seen a particular model.
Installation
To install the plugin just install from the GitHub repository:
git clone git://github.com/mbleigh/acts-as-readable.git vendor/plugins/acts_as_readableYou will need the readings table to use this plugin. A generator has been included,
simply type
script/generate acts_as_readable_migrationto get the standard migration created for you.
Example
class Post < ActiveRecord::Base acts_as_readable end
bob = User.find_by_name("bob")
bob.readings # => []
Post.find_unread_by(bob) # => [<Post 1>,<Post 2>,<Post 3>...]
Post.find_read_by(bob) # => []
Post.find(1).read_by?(bob) # => false
Post.find(1).read_by!(bob) # => <Reading 1>
Post.find(1).read_by?(bob) # => true
Post.find(1).users_who_read # => [<User bob>]
Post.find_unread_by(bob) # => [<Post 2>,<Post 3>...]
Post.find_read_by(bob) # => [<Post 1>]
bob.readings # => [<Reading 1>]
And that’s all there is to it! It’s not an incredibly complex set of features, but I find it to be a pretty useful one. If you have any questions or issues, please feel free to post them on the public Trac
Needy Controllers - DRYing Stylesheets, Scripts, and Fetching
After developing a number of applications, there were some actions I found myself performing over and over again with each new controller in each new application. With my DRY-sense tingling, I decided to do something about it and create a plugin to clean up some of those repetitive tasks that were vital but annoying to set up. Introducing Needy Controllers.
Needy Controllers takes care of your controllers’…well, needs. You can include stylesheets, javascripts, and memoized record helpers in your controllers and views with a single command, and even use filter-chain-esque options to specify and tailor to your needs. Basically, it simplifies the process of:
- Including stylesheets in your app on a per-controller/action basis
- Including javascripts on a per-controller/action basis
- Having helper functions to fetch records in common RESTful resource mappings
Installation
git clone git://github.com/mbleigh/needy-controllers.git vendor/plugins/needy_controllers
Usage
Styles and Scripts
To use Needy Controllers for styles and scripts, you simply call a “needs” option inside your controller like so:
class MyController < ApplicationController
needs :styles => :standard
needs :styles => :show, :only => :show
needs :scripts => :behave, :except => :show
def index
# this action will have access to the 'standard.css' stylesheet
end
def show
# this action will have access to the 'show.css' stylesheet
# in addition to 'standard.css'
# but will not have access to 'behave.js'
end
end
Now that you have created your behavior and style chains, you need to include them in the view. Luckily, this is exceedingly easy! Just include :needs in your include and link tags like so:
<%= stylesheet_link_tag 'something', :needs %>
<%= javascript_include_tag 'prototype', :needs, 'effects' %>An additional benefit of the style and behavior chains is inheritance: namely, any controller that inherits from a controller with a stylesheet or javascript included using the above method will automatically have the same stylesheet and javascript included in itself. This allows you to easily set up includes that are scoped to your exact needs with as little work as possible.
Model Fetching
To use Needy Controllers for fetching records, you use it similarly, and it creates a helper:
class MyController < ApplicationController # here's a standard problem needs :record => :user, :from => :id, :as => :user end
The :from and :as options in this example are the defaults (:id for :from and :as defaults to the name of the record). This will create a method (“user” in the example)
that will be accessible both from the controller and from the view as a helper. It will find the record with a matching ID to the URL parameter associated with the :from option. Therefore if you had nested resources you could call it as such:
needs :record => :user, :from => :user_id
That’s pretty much it, just a few simple ways to make your coding life easier. As always, there is a Trac available for any issues and I would love to hear any feedback you might have.
Announcing 'Princely' - Rails Prince XML PDF Wrapper
Recently I was implementing PDF generation for a project utilizing the fantastic library Prince XML. I came across a blog article with a basic library and helper set for Prince, which provided a great basis. I wanted to make something a little more generalized and in-keeping the Rails Way, so I have created ‘Princely’, a simple wrapper utilizing much of the code from the SubImage library but giving it better helpers and pluginizing its inclusion.
Installation
The first step is to download Prince and install it on your platform of choice (only Linux and Mac OS X supported by the plugin at this time). Next, simply install the plugin:
script/install plugin git://github.com/mbleigh/princely.git
You are now ready to get started using Princely to generate PDF. Note that Princely is only compatible with Rails >= 2.0
Usage
Princely uses the MimeTypes and respond_to blocks from Rails 2.0 to add PDF as a render option and a format. Because of this, it’s incredibly easy to implement a PDF! Simply make your XHTML or XML template and use pdf as the format (e.g. show.pdf.erb), then add code similar to this in your controller:
class Page < ApplicationController
def show
respond_to do |format|
format.html
format.pdf {
render :pdf => @page.pdf_name,
:template => "show.pdf.erb", # not required, shown for example
:layout => false # not required
}
end
end
end
And that’s all there is to it! If you add a .pdf to your properly routed path, you should be presented with a PDF version of the page generated by Prince. The README has more detailed usage information.
As always, there is a Trac available for any bugs or patches you might come across.
Announcing 'Browserized Styles'
Browser compatibility, the web designer’s nightmare, has always seemed more difficult than it has to be. Why hasn’t there been an industry-standard, simple way to target CSS to specific browsers, allowing one to style the page properly without worrying about hacks and other difficult ways of pulling all the information together? I thought that something should be done about it, so taking Richard Livsey’s ‘browser_detect’ plugin as a starting point, I developed an automatic solution for including browser-specific stylesheets.
Browserized Styles provides a dead simple way to create browser-specific CSS code for
use in a Rails application. All you need to do is create a .css file targeted to
a browser by appending an underscore and identifier to the end.
Installation
script/plugin install http://svn.intridea.com/svn/public/browserized_styles
Example
Let’s say I have some complex CSS code that looks bad in some browsers, but works in
others. Let’s also say that i’ve put it into a stylesheet in stylesheets/complex.css.
My stylesheet link tag looks something like this:
<%= stylesheet_link_tag 'complex' %>
Now all I have to do to target a browser is create a new CSS file with the browser’s
identifier appended to it with an underscore (e.g. “complex_ie6.css”). That’s it!
The same exact stylesheet link tag will automatically check the current user
agent and load a browser-specific CSS file if it exists. Ta-da! One-step browser
styles!
More information is available in the readme, but the end result is browser-targeting bliss.
The plugin is brand new and will probably see some modifications in the future. If you run into any problems or come up with a patch, feel free to submit it to the Intridea Public Trac .
Announcing 'acts_as_taggable_on'
For a number of applications, especially our Social Networking Platform I’ve found a need for advanced tagging functionality not offered by the acts_as_taggable_on_steroids plugin. Namely, there have been a number of times when I’ve wished a model could have multiple “sets” of tags that would function both independently and together. For example, a user might have tagged themselves, but they might also have skills, interests or sports that would also function like tags. That’s where acts_as_taggable_on comes in.
Installation
To install the plugin on Edge Rails or Rails 2.1 and greater:
script/plugin install git://github.com/mbleigh/acts-as-taggable-on.git
On previous versions of Rails:
git clone git://github.com/mbleigh/acts-as-taggable-on.git vendor/plugins/acts-as-taggable-on
Usage
Acts As Taggable On provides the same functionality of acts_as_taggable_on_steroids with the addition of the notion of “contexts,” or scoped areas in which taggings can live. For the user example listed above, I can now simply make a call like so:
class User < ActiveRecord::Base acts_as_taggable_on :tags, :skills, :interests, :sports end
By taking the same one-liner tack as previous implementations, we are now able to set, find, retrieve, and calculate information based on tags within a context as well as as a whole. With the user model we just created:
@user = User.new(:name => "Bobby")
@user.tag_list = "awesome, slick, hefty" # this should be familiar
@user.skill_list = "joking, clowning, boxing" # but you can do it for any context!
@user.skill_list # => ["joking","clowning","boxing"] as TagList
@user.save
@user.tags # => [<Tag name:"awesome">,<Tag name:"slick">,<Tag name:"hefty">]
@user.skills # => [<Tag name:"joking">,<Tag name:"clowning">,<Tag name:"boxing">]
User.find_tagged_with("awesome") # => [@user]
User.find_tagged_with("joking") # => [@user]
User.find_tagged_with("awesome", :on => :tags) # => [@user]
User.find_tagged_with("awesome", :on => :skills) # => []
@frankie = User.create(:name => "Frankie", :skill_list => "joking, flying, eating")
User.skill_counts # => [<Tag name="joking" count=2>,<Tag name="clowning" count=1>...]
@bobby.skill_counts
@frankie.skill_counts
And that’s all there is to it! Now you can scope your tags to whatever arbitrary name you would like. The inflector is used to create the singular/plural methods, so be careful about making sure that your nomenclature uses plurals in the acts_as_taggable_on call.
As a side note, this is meant to be used in place of acts_as_taggable_on_steroids, and the acts_as_taggable method works in acts_as_taggable_on simply by calling acts_as_taggable_on :tags. Caching has been written into the implementation but is not yet tested or verified to be working. Stay tuned for additional improvements to this plugin, and feel free to submit any bugs or patches to the Lighthouse
UPDATE 5/3/07: Acts As Taggable on is now hosted on GitHub and has a public Lighthouse available for bug tracking. Information updated above.
