SubdomainFu provides a modern implementation of subdomain handling in Rails. It takes aspects from account_location, request_routing, and other snippets found around the web and combines them to provide a single, simple solution for subdomain-based route and url management.
SubdomainFu is available both as a traditional plugin and a GemPlugin. To install it as a traditional plugin (Rails 2.1 or later):
script/plugin install git://github.com/mbleigh/subdomain-fu.git
To use it as a GemPlugin, add it to your environment.rb:
config.gem 'mbleigh-subdomain-fu', :source => "http://gems.github.com", :lib => "subdomain-fu"
SubdomainFu works inside of Rails’s URL Writing mechanisms to provide an easy and seamless way to link and otherwise understand cross-subdomain routing. You can use the :subdomain option both in named and non-named routes as well as in generated resources routes.
Let’s say my domain is ‘intridea.com’. Here are some examples of the use of the :subdomain option:
url_for(:controller => “my_controller”,
:action => "my_action", :subdomain => "awesome") # => http://awesome.intridea.com/my_controller/my_action
Now let’s say I’m at awesome.intridea.com/ and I want back to the root. Specifying “false” will remove any current subdomain:
users_url(:subdomain => false) # => intridea.com/users
You should exercise caution using the :only_path option when you want to change subdomains. If you want the plugin to insure that you switch subdomains when you mean to, you should set SubdomainFu.override_only_path to true in your application configuration. This will disregard :only_path in routing helpers. With this option, if I were at intridea.com again:
users_path(:subdomain => “fun”) # => fun.intridea.com/users users_path(:subdomain => false) # => /users
In this way you can rest assured that you will never misdirect your links to the same subdomain when you meant to change it.
Note that in the past this was the default behavior of the plugin.
You have access to current_subdomain and current_domain methods.
current_subdomain - returns all subdomains.
Example for the URL http://awesome.website.stuff.example.com current_subdomain will return "awesome.website.stuff"
current_domain - returns all subdomains except for the subdomain, including the TLD.
Example for the URL http://awesome.website.stuff.example.com current_subdomain will return "website.stuff.example.com"
If what you really want is the entire domain, then use request.domain in your controllers. The purpose of current_domain is to only strip off the first subdomain, if any, and return what’s left.
You may need to configure SubdomainFu based on your development setup. The configuration required is:
A hash for each environment of the size of the top-level domain name. (something.com = 1, localhost = 0, etc.)
SubdomainFu.tld_size = 1 # sets for current environment SubdomainFu.tld_sizes = {:development => 0,
:test => 0, :production => 1} # set all at once (also the defaults)
Mirrors are the subdomains that are equivalent to no subdomain (i.e. they ‘mirror’) the usage of the root domain.
SubdomainFu.mirrors = %w(www site we) # Defaults to %w(www)
SubdomainFu also understands the notion of a ‘preferred mirror’, that is, if you always want your links going to ‘www.yourdomain.com’ instead of ‘yourdomain.com’, you can set the preferred mirror like so:
SubdomainFu.preferred_mirror = “www”
Now when you create a link with subdomain => false in the options the subdomain will default to the preferred mirror.
SubdomainFu can also work within Rails’ routing for subdomain-specific routes. For instance, if you only wanted your administrative tools available in the “admin” subdomain you could add this to your routes.rb file:
map.with_options :conditions => {:subdomain => 'admin'} do |admin| admin.resources :posts admin.resources :users end
In addition to specifying a string, you could also specify false to require no subdomain (this includes mirrors that you’ve set up such as www) or a regular expression to match a range of subdomains.
-
GitHub Repository: github.com/mbleigh/subdomain-fu
Copyright © 2008 Michael Bleigh (www.mbleigh.com/) and Intridea, Inc. (www.intridea.com/). Released under the MIT license