Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A new plugin approach to attempting to solve the usage of subdomains in linking and routing in Rails projects.
tag: v0.4.0

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
rails
spec
.gitignore
CHANGELOG
MIT-LICENSE
README.rdoc
Rakefile
VERSION.yml
init.rb
install.sh
subdomain-fu.gemspec

README.rdoc

SubdomainFu

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.

Installation

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"

Examples

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

Note that this plugin does not honor the :only_path notion of routing when doing so would go against the intent of the command. For example, 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.

Configuration

You may need to configure SubdomainFu based on your development setup. The configuration required is:

TLD Size

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

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)

Preferred Mirror

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.

Routing

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

Resources

Copyright © 2008 Michael Bleigh (www.mbleigh.com/) and Intridea, Inc. (www.intridea.com/). Released under the MIT license

Something went wrong with that request. Please try again.