subdomain_fu 0 Rubygems

5 years after MIT

= 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 gem, add it to your config/environment.rb:

config.gem '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 http://awesome.intridea.com/ and I want back to the root. Specifying "false" will remove any current subdomain:

users_url(:subdomain => false) # => http://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 http://intridea.com again:

users_path(:subdomain => "fun") # => http://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.

== Use in controllers and views

You have access to current_subdomain and current_domain methods.

[current_subdomain] returns all subdomains. For the URL http://awesome.website.stuff.example.com, it will return "awesome.website.stuff"

[current_domain] returns all subdomains except for the subdomain, including the TLD. For the URL http://awesome.website.stuff.example.com, it 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.

== 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 config/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.

== Resources

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

Related Repositories

subdomain-authentication

subdomain-authentication

An example Rails 2.3 web app with subdomains and authentication (using Devise). ...

spot-us

spot-us

Community Funded Reporting ...


Top Contributors

pboling eric jcoby morhekil zachhale ajn etaque gswirski technicalpickles loe account-settings

Releases

-   v0.5.4 zip tar
-   v0.5.4-domain zip tar
-   v0.5.3 zip tar
-   v0.4.1 zip tar
-   v0.4.0 zip tar
-   v0.1.0 zip tar