Installation

In Rails 3:

$ rails plugin install git://github.com/lassebunk/sitemap_notifier.git

Example

Start by generating initializer and route:

$ rails generate sitemap_notifier sitemap_notifier

In config/initializers/sitemap_notifier.rb:

# wait 10 minutes between notifications
SitemapNotifier::Notifier.delay = 600

# replace this with your own url
SitemapNotifier::Notifier.sitemap_url = "http://example.com/sitemap.xml"

After installation

After you install and configure the plugin, it’ll automatically notify Google, Bing, and Yahoo every time you update a model. After each notification, it’ll wait 10 minutes (by default) before notifying again. This is to ensure that for example a batch update won’t trigger an equal amount of notifications.

Follow me on Twitter

Like this:

In app/views/api/users/index.apibuilder:

array :users do
  @users.each do |user|
    element :user do
      id @user.id
      name @user.name
    end
  end
end

Returns:

[
  {
    "id": 1234,
    "name": "Peter Jackson"
  },
  {
    "id": 1235,
    "name": "Marilyn Monroe"
  }
]

And the equivalent XML.

In app/views/api/users/show.apibuilder:

element :user do
  id @user.id
  name @user.name
  address do
    street @user.street
    city @user.city
  end
  array :interests do
    @user.interests.each do |interest|
      element :interest, interest.name
    end
  end
end

Returns:

{
  "id": 1234,
  "name": "Peter Jackson",
  "address": {
    "street": "123 High Way",
    "city": "Gotham City"
  },
  "interests": [
    "Movies",
    "Computers",
    "Internet"
  ]
}

And the equivalent XML.

You can then call your API like this:

http://example.com/api/users?format=json

or

http://example.com/api/users?format=xml

and so on.

Installation:

$ rails plugin install git://github.com/lassebunk/api_builder.git

Documentation and examples: Check out ApiBuilder at GitHub.
Looking forward to comments and suggestions

Follow me on Twitter

In this example, I’ll show how to create a location aware website using Ruby on Rails, PostgreSQL, and PostGIS. The application, when finished, will be able to store your current location – or a check-in – in the database, show all your check-ins on a map, and show check-ins nearby check-ins.

This app is written in Rails 3.1 but it could just as well be written in another version. As of writing, the current version of the spatial_adapter gem has an issue in Rails 3.1 but we will create a workaround for this until it gets fixed.

You can view the complete source code or see the final application in action.

Creating the PostGIS enabled database

We will first create our geospatially enabled database. First check out out my post on installing PostgreSQL and PostGIS on Mac OS X.

Create your database:

$ createdb -h localhost my_checkins_development

Install PostGIS in your database:

$ cd /opt/local/share/postgresql90/contrib/postgis-1.5/
$ psql -d my_checkins_development -f postgis.sql -h localhost
$ psql -d my_checkins_development -f spatial_ref_sys.sql -h localhost

Your database is now ready for geospatial queries.

Creating the geospatially enabled Rails app

Create your app:

$ rails new my_checkins

The spatial_adapter gem is a plugin that adds geospatial functionality to Rails when using a PostgreSQL and PostGIS. It uses GeoRuby for data types. Add this and the pg (Postgres) gem to your Gemfile:

gem 'spatial_adapter'
gem 'pg'

Run bundle install:

$ bundle install

Setup your config/database.yml:

development:
  adapter: postgresql
  database: my_checkins_development
  host: localhost

And your app is geospatially enabled

Creating the code to handle check-ins

Let’s create some scaffold code to handle our check-ins:

$ rails g scaffold checkin title:string location:point

Take notice of the point data type – that’s a geospatial type.
Before running your migrations, edit db/migrate/create_checkins.rb, replacing this:

t.point :location

with this:

t.point :location, :geographic => true

This tells your migration to add a geographic column that is set up to handle geographic coordinates, also known as latitudes and longitudes.

Run your migrations:

$ rake db:migrate

We are now ready to store our check-ins.

The Checkin model now contains a location field which is a data type of GeoRuby::SimpleFeatures::Point. This data type has properties of x and y. We will expose these as properties directly on the model. In app/models/checkin.rb:

class Checkin < ActiveRecord::Base
  def latitude
    (self.location ||= Point.new).y
  end

  def latitude=(value)
    (self.location ||= Point.new).y = value
  end

  def longitude
    (self.location ||= Point.new).x
  end

  def longitude=(value)
    (self.location ||= Point.new).x = value
  end
end

Latitude and longitude are now exposed.

In app/views/checkins/_form.html.erb, replace this:

<div class="field">
  <%= f.label :location %><br />
  <%= f.text_field :location %>
</div>

With this:

<div class="field">
  <%= f.label :latitude %><br />
  <%= f.text_field :latitude %>
</div>
<div class="field">
  <%= f.label :longitude %><br />
  <%= f.text_field :longitude %>
</div>

If it wasn’t for a little bug in spatial_adapter under Rails 3.1, we would now be able to save locations from our Rails app. However, what the bug does is that it cannot create records when the location field is set. It can update them so what we will do is to make sure it first creates the check-in with a location set to nil and then updates it with the correct location. Like this, in app/controllers/checkins_controller.rb in the create method, replace this:

def create
  ...
  if @checkin.save
    ...

With this:

def create
  ...
  if @checkin.valid?
    location = @checkin.location
    @checkin.location = nil
    @checkin.save!
    @checkin.location = location
    @checkin.save!
    ...

And it should work.
Try and fire up your server:

$ rails s

And go to http://localhost:3000/checkins/new in your browser.

Next, in app/views/checkins/show.html.erb, replace this:

<p>
  <b>Location:</b>
  <%= @checkin.location %>
</p>

With this:

<p>
  <b>Location:</b>
  <%= @checkin.latitude %>, <%= @checkin.longitude %>
</p>

And it will show the latitude and longitude you just entered.

Getting our current location

We would like to be able to create check-ins from our current location. Modern browsers exposes this functionality via a JavaScript API. Create app/assets/javascripts/checkins.js and add this:

function findMe() {
  if(navigator.geolocation) {
    navigator.geolocation.getCurrentPosition(function(position) {
      document.getElementById('checkin_latitude').value = position.coords.latitude;
      document.getElementById('checkin_longitude').value = position.coords.longitude;
    }, function() {
      alert('We couldn\'t find your position.');
    });
  } else {
    alert('Your browser doesn\'t support geolocation.');
  }
}

And a button in the top of app/views/checkins/_form.html.erb:

<input type="button" value="Find me!" onclick="findMe();" />

Try it in your browser. If it gives you a JavaScript error saying the findMe method isn’t defined, try restarting your server to get the new javascript loaded. You should now be able to get your current location by clicking the Find me! button.

Finding nearby check-ins

Let’s create a method for finding nearby check-ins. PostGIS has a function named ST_DWithin which returns true if two locations are within a certain distance of each other. In app/models/checkin.rb, add the following to the top of the class:

class Checkin < ActiveRecord::Base
  scope :nearby_to,
    lambda { |location, max_distance|
      where("ST_DWithin(location, ?, ?) AND id != ?", checkin.location, max_distance, checkin.id)
    }
  ...

In app/controllers/checkins_controller.rb, add the following:

def show
  @checkin = Checkin.find(params[:id])
  @nearby_checkins = Checkin.nearby_to(@checkin, 1000)
  ...

In app/views/checkins/show.html.erb, add the following just before the links in the bottom:

<h2>Nearby check-ins</h2>
<ul>
  <% @nearby_checkins.each do |checkin| %>
    <li><%= link_to checkin.title, checkin %></li>
  <% end %>
</ul>

It now shows all nearby checkins. Try adding a couple more based on your current location and see it in action.

Creating a map with all check-ins

Wouldn’t it be nice to show all our check-in on a map? We will do this using the Google Maps API.

In app/views/checkins/index.html.erb, clear out the table and list, and add the following:

<script type="text/javascript" src="http://maps.googleapis.com/maps/api/js?sensor=false"></script>

That loads the Google Maps JavaScript API functionality.

Create a div for the map:

<div id="map" style="width: 600px; height: 500px;"></div>

And add the following script at the bottom:

<script type="text/javascript">
  // Create the map
  var map = new google.maps.Map(document.getElementById("map"), {
    mapTypeId: google.maps.MapTypeId.ROADMAP
  });

  // Initialize the bounds container
  var bounds = new google.maps.LatLngBounds();

  <% @checkins.each do |checkin| %>
    // Create the LatLng
    var latLng = new google.maps.LatLng(<%= checkin.latitude %>, <%= checkin.longitude %>);

    // Create the marker
    var marker = new google.maps.Marker({
        position: latLng,
        map: map,
        title: '<%= escape_javascript(checkin.title) %>'
    });

    // Add click event
    google.maps.event.addListener(marker, 'click', function() {
      document.location = '<%= checkin_path(checkin) %>';
    });

    // Extend the bounds
    bounds.extend(latLng);
  <% end %>

  // Fit to bounds
  map.fitBounds(bounds);
</script>

There’s our map Check it out at http://localhost:3000/checkins. Try creating some check-ins around the world to see the map expand.

Conclusion

That’s a location aware app that stores check-ins based on our current location, shows nearby check-ins, and displays check-ins on a map.

View the complete source code or see the final application in action.

Follow me on Twitter

In config/routes.rb:

scope 'my_subdir' do
  # all resources and routes go here
end

In your Apache configuration file:

Alias /my_subdir /var/www/my_subdir/public
<Location /my_subdir>
  SetEnv RAILS_RELATIVE_URL_ROOT "/my_subdir"
  PassengerAppRoot /var/www/my_subdir
</Location>

And it should work, including automatically pointing all your assets to /my_subdir.

Follow me on Twitter

Ruby (the programming language)

From Wikipedia: “Ruby is a dynamic, reflective, general-purpose object-oriented programming language that combines syntax inspired by Perl with Smalltalk-like features. Ruby originated in Japan during the mid-1990s and was first developed and designed by Yukihiro “Matz” Matsumoto. It was influenced primarily by Perl, Smalltalk, Eiffel, and Lisp.” Ruby is a beautiful language – you’ll love it. Read more on ruby-lang.org and try it here.

Rails (the framework)

Rails is a web framework built on Ruby, hence the name Ruby on Rails. It enables the programmer to easily create advanced websites, following convention over configuration, which means that if you stick to a certain set of conventions, a lot of features will work right out of the box with very little code.

MVC (Model-View-Controller)

Rails is based on a programming pattern called MVC, which stands for Model-View-Controller. Here I’ll try to explain what it is and why it makes sense to use it.

Model

The model in MVC is a class for each entity in your application. Example models are User, Category, or Product. The models hold all business logic, for example what should happen if you delete a product, add a new category, or create a new user.

View

The views in MVC hold all your presentation and presentation logic, normally HTML. It is based on ERuby which is a templating system that allows for Ruby embedded into HTML and other languages. You probably know this kind of templating system from ASP, PHP, or JSP.

Controller

The controller is what binds together the models and views, for example tells the show product view which product it should show, or handles the data from a form post when a user updates a shopping basket.

Why does MVC make sense?

MVC allows for perfect separation of business logic from presentation logic, giving you a much cleaner application that is easier to maintain and, on top of that, a lot more fun to develop.

Routing

So, how does is a request from a visitors browser sent down to the controller that handles this request? This is done by a routing engine that interprets the request and passes it on to the matching controller.

CRUD (Create, Read, Update, Delete)

In the heart of the Rails routing engine lies CRUD, or Create, Read, Update, Delete, which comes from a notion that all web pages are made up of these four actions. For example, you create a product, view, or read a user, edit, or update a category, and delete an order.

If you follow this pattern, you’ll get a lot of work done for you. For example, all it takes to create all of these actions for a product is to tell the routing engine that you have an entity called product, and it will wire up all the routing logic that binds the request to the matching controller for you.

ActiveRecord

ActiveRecord is a pattern that allows for all database access to be written without a single line of database access. You tell the class, or model, what kind of entity you want it to be, which relations it has, and it automagically does the rest for you, creating properties based on the fields from the database, giving you database operation methods like create, update, and delete for free. You write only your custom business logic. The ActiveRecord classes are almost always what makes up the Model part of the aforementioned MVC pattern.

Database migrations

In Ruby on Rails you almost never talk directly to your database like you know it from PHP or other scripting languages. Instead, as part of ActiveRecord, comes a complete database migration framework. Database migrations mean that you create Ruby code for creating tables and adding columns instead of doing this directly in your database. What this does it that it allows for migrating multiple databases with the same changes, for example a development and production database, without having to remember what changes you made in your development database when deploying to production – you just run the same migrations in a different environment.

Separation of environments (development, production, etc.)

In Rails, you have a perfect separation of environments. This means that you can run your system with different settings based on which environment you are currently in, for example you want your development environment to display verbose error messages where your production site shows a user friendly message to the end user.

Assets management (images, stylesheets, and javascripts)

The Rails 3.1 assets pipeline allows for all your assets (images, stylesheets, and javascripts) to be managed for you. In your development environment you have your full folder structure with stylesheets and javascripts written in different languages like CoffeeScript and SCSS. When you deploy, all your assets are compiled and fetched from the same folder, all stylesheets compiled together, the same with your javascripts. This also means that you don’t have to include for example jQuery – this is included for you via the jQuery Rails plugin.

Plugins (RubyGems etc.)

Coding in Ruby on Rails means that you get a butt load of plugins already written for you. Not in the Rails core (it’s very clean) but as RubyGems which is a kind of packaging for Ruby. For example, you could have plugins for pagination, search engine optimization, or image processing. As of the time of writing, there are over 27,000 RubyGems to be used for free.

Conclusion

Ruby on Rails is a great framework for creating advanced web applications writing very little code in comparison to what you get. I recommend it for almost any kind of application, and especially for prototyping. To inspire you, I created a video where I create a blog in 10 minutes using Ruby on Rails. Check it out and be sold. I also recommend the documentation section of the official Ruby on Rails site. For those of you used to Ruby on Rails, I recommend this blog post about the changes from version 3.0 to version 3.1.

Follow me on Twitter

Here I will show how to use SCSS/CSS on the body-tag to differentiate between two different sites, and between the various pages on each site.

1. Differentiating your content

Let’s say that you are building a mobile and desktop site and want to differentiate your content sitewise. (If you’re building a mobile site, the actual server-side separation of the content can be done with a plugin like mobile-fu which works really great.)

Start by inserting a desktop and mobile class in your body-tags, like this:

<body class="desktop">

and for your mobile site:

<body class="mobile">

Next, add the following method to your application_helper.rb:

def find_named_routes
  routes = []

  Rails.application.routes.named_routes.each do |name, route|
    req = route.requirements
    if req[:controller] == params[:controller] && req[:action] == params[:action]
      routes << name
    end
  end

  routes
end

This method will find all named routes based on the current controller and action. It will also find duplicate routes and localized routes if you are using a route translation gem like i18n_routing.

Now you can add the method to your body-tags like this:

<body class="desktop <%= find_named_routes.join(" ") %>">

This way you’ll get body-classes like root, categories, category and so on. These can be used to differentiate your content later on. We will do this using SCSS.

2. Creating the CSS

SCSS is an extension to CSS which among a lot of other feature allows you to nest your content. Instead of:

.blah ul { ... }
.blah p { ... }
.blah a { ... }

In SCSS you can do it like this:

.blah {
  ul { ... }
  p { ... }
  a { ... }
}

And it will generate the exact same CSS. Neat, eh?

So now we can use this technique to differentiate our sites and individual pages. Like this, in desktop.css.scss:

body.desktop {
  margin: 20px;
  font-family: arial, helvetica, sans-serif;
  a { color: black }
  p { margin-bottom: 10px; }
  h1 { color: green; }
}

In categories.css.scss:

body.desktop.categories {
  h1 { color: red; }
}

And in mobile.css.scss:

body.mobile {
  margin: 10px;
  font-family: arial, helvetica, sans-serif;
  a { color: red }
  p { margin-bottom: 5px }
}

Pretty sweet. Now you just need to compile your assets, and you’re good to go.

Also see my other post about how to get your assets to work in Rails 3.1.

Update: And the answer to this Stack Overflow question: Using Rails 3.1 assets pipeline to conditionally use certain css

Follow me on Twitter

1. Upgrading to Rails 3.1

Add Rails 3.1 to your Gemfile. Add or change the gem 'rails' line:

gem 'rails', '3.1.0'

Bundle install:

$ bundle install

Run the update task to get your Rails files up to date, but beware! Just overwriting all files will probably mess up your app, so make sure to backup files or take notice of what changes you need to add to the new files before overwriting them. It will ask you what to do:

$ rake rails:update

Now your app should be running Rails 3.1. You can try running it using rails s but it probably won’t look great because we’ve not yet migrated the assets.

2. Migrating your assets

Try switching off the assets pipeline by commenting out the following line in config/application.rb:

# config.assets.enabled = true

Your app should now be running as usual. If it doesn’t, try ironing out any issues before switching on the assets again:

config.assets.enabled = true

We’re now ready to migrate the assets.

First, add this to your Gemfile:

gem 'jquery-rails'
group :assets do
  gem 'sass-rails', "  ~> 3.1.0"
  gem 'coffee-rails', "~> 3.1.0"
  gem 'uglifier'
end

And install:

$ bundle install

Now to the actual migration:

1. Make sure you have the images, javascripts, and stylesheets folders in your app/assets folder.
2. Move all content from public/images into app/assets/images.
3. Move all content from public/javascripts into app/assets/javascripts.
4. Move all content from public/stylesheets into app/assets/stylesheets.

Your javascripts and stylesheets will be compiled into a single application.js and application.css, so add or change this in your app/views/layouts/application.html.erb:

<%= stylesheet_link_tag 'application' %>
<%= javascript_include_tag 'application' %>

To make sure that the assets generator will find all your javascripts and stylesheets, we will include all your javascripts in application.js and all your stylesheets in application.css. Assuming you are using jQuery, you can delete jquery.js and jquery-ui.js as they will be required and inserted automatically. Add the following to the top of app/assets/javascripts/application.js:

//= require jquery
//= require jquery_ujs
//= require_tree .

And to the top of app/assets/stylesheets/application.css:

/*
 *= require_self
 *= require_tree .
*/

Your javascripts and stylesheets will now be included automatically.

At last update all your image paths from /images to /assets. If you’re using the image_tag helper, all paths will be updated automatically.

3. Deploying your assets

Assuming you are deploying using Capistrano, add the following to your config/deploy.rb:

before "deploy:symlink", "assets:precompile"

namespace :assets do
  desc "Compile assets"
  task :precompile, :roles => :app do
    run "cd #{release_path} && rake RAILS_ENV=#{rails_env} assets:precompile"
  end
end

Your assets will now be compiled right before your app is moved into place in your production environment.

Try deploying your app:

$ cap deploy

If the deployment went as expected, great. If you get an error complaining about a missing JavaScript engine, try adding the following to the assets section of your Gemfile:

gem 'therubyracer'

And run the deployment again.

Your assets should now be in place! If you run into other problems, please write a comment below, and I’ll see if I can help.

Follow me on Twitter

Create an Article model using scaffolding to have the controller and views generated automatically:

$ rails g scaffold Article title:string content:text format:string

Migrate:

$ rake db:migrate

In app/models/article.rb:

class Article < ActiveRecord::Base
  FORMATS = [["HTML", "html"],
             ["Markdown", "markdown"],
             ["Textile", "textile"],
             ["Plain text", "plain"]]
  validates_inclusion_of :format,
                         :in => FORMATS.collect { |name, format| format }
end

In app/views/articles/_form.html.erb:

<% form_for(@article) do |f| %>
  <p>
    <%= f.label :title %><br />
    <%= f.text_field :title %>
  </p>
  <p>
    <%= f.label :format %><br />
    <%= f.select :format, Article::FORMATS %>
  </p>
  <p>
    <%= f.label :content %><br />
    <%= f.text_area :content %>
  </p>
  <p>
    <%= f.submit %>
  </p>
<% end %>

In app/helpers/articles_helper.rb:

module ArticlesHelper
  def format_content(format, content)
    case format
    when "html"
      content.html_safe
    when "markdown"
      BlueCloth.new(content).to_html.html_safe
    when "textile"
      RedCloth.new(content).to_html.html_safe
    when "plain"
      simple_format(html_escape(content))
    else
      raise ArgumentError, "Unknown format '#{format}'."
    end
  end
end

In app/views/articles/show.html.erb:

<h1><%=h @article.title %></h1>
<%= format_content(@article.format, @article.content) %>

Add the RedCloth and BlueCloth gems to your Gemfile:

gem 'RedCloth'  # textile
gem 'bluecloth' # markdown

Install the gems:

$ bundle install

It’s as easy as that. Now you can create articles, choose a format, and this format will be used to render the content of the article.

Did you find this helpful? Please let me know in the comments.

Follow me on Twitter

In the controller:

def new
  @account = Account.new
  @user = User.new
end

In the view:

<%= form_for @account do |f| %>
  <%= f.error_messages %>
  <p>
    <%= f.label :name %><br />
    <%= f.text_field :name %>
  </p>
  <%= fields_for @user do |u| %>
    <%= u.error_messages %>
    <p>
      <%= u.label :name %><br />
      <%= u.text_field :name %>
    </p>
  <% end %>
  <p>
    <%= f.submit "Create account" %>
  </p>
<% end %>

And after you press ‘Create account’ – in the controller:

def create
  @account = Account.new(params[:account])
  @user = User.new(params[:user])

  if [@account, @user].map { |rec| rec.valid? }.all?
    [@account, @user].each { |rec| rec.save! }
    redirect_to account_path
  else
    render :new
  end
end

This way each model will only be saved if all models validate.

And, this could be done even nicer by writing a method. In your ApplicationController:

def save_all(*models)
  if models.map { |rec| rec.valid? }.all?
    models.each { |rec| rec.save! }
    true
  end
end

In your controller:

if save_all(@account, @user)
  redirect_to account_path
else
  render :new
end

Note: To use form.error_messages in Rails 3, you need this plugin.

Follow me on Twitter

But could this be done in less than 10 minutes using Rails 3? See for yourself

Download the video in HD quality

Follow me on Twitter