It's a great plugin for classic page rendering, but what if you want to use it with AJAX, so it updates a document element (a floating window layer, for instance) with the results instead of reloading the page?

Well, inspired on Redline's blog post (which almost worked for the latest version of the will_paginate plugin), I have the solution.

Create a link renderer. I put in under lib/remote_link_renderer.rb so Rails always loads it on startup.

class RemoteLinkRenderer < WillPaginate::LinkRenderer

  def page_link_or_span(page, span_class = 'current', text = nil)
    text ||= page.to_s
    if page and page != current_page
      @template.link_to_remote(text, {:url => url_for(page), :method => :get}.merge(@remote))
    else
      @template.content_tag :span, text, :class => span_class
    end
  end
end

On the view, when you are rendering the pager, do it like this:

<%= will_paginate @collection, :renderer => 'RemoteLinkRenderer' , :remote => {:with => ’value’, :update => ‘some_div’} %>

That's it!

If you want to paginate records that are inside your database it works great.

But what if you want to paginate records that come from, say an external webservice?

Well, you can use the WillPaginate::Collection class.

This class will let you mimic the collection that will work on a pager, so you can use the view helper pager seamlessly throughout your app.

Just use it like this:

@entries = WillPaginate::Collection.create(1, 10) do |pager|
  result = Webservice.get(...) # get your results
  # inject the result array into the paginated collection:
  pager.replace(result)

  unless pager.total_entries
    # the pager didn't manage to guess the total count, do it manually
    pager.total_entries = result.count
  end
end

IDEs:

• Aptana Rad Rails - very good at Rails and Ruby. It's based on Eclipse - Java - so it tends to bloat
• gedit- Tiny footprint, simple. Great for web and PHP with the right plugins and conf tweaks

Ruby / Rails plugins:

• will_paginate - ActiveRecord pagination made easy
• fleximage - online image processing Rails plug-in based on rmagick. Very easy to manipulate
• hpricot gem - for parsing HTML and XML. Very resilient to formatting errors. Use it to parse XML feeds with wrong encoding and screen scraping.
• authlogic - for easy and extensible authentication. With care you can make it easily authenticate with anything.
• BlueCloth gem - for markdown markup
• eventmachine - scalable asynchronous Ruby servers made easy.
• styled_objects - simplify stylesheet development and maintenance. By yours truly.
• delayed_job - job queuing for Rails made easy.
• app_config gem - easy application configuration. Easily differentiate for each environment.
• acts_as_xapian - easy ruby and Rails bindings for Xapian - full text search engine. Xapian uses offline index update and does not use a daemon.
• lockdown -  authorization system for Rails
• acts_as_pingable - to expose you Rails stack to external pings. Use it for pingdom.com integration.
• resource_controller - simplifies code for resource controllers (almost no code at all for most cases !)
• aasm (acts as state machine) - easily turn your objects into state machines.

Testing

• cucumber - BDD at it's best
• mocha - intuitive mocking and stubbing
• rspec and rspec-rails - Rails testing
• factory_girl - Get rid of fixtures

Database

• MySQL - I love it, I hate it, I have to live with it...
• Tokyo Cabinet - fast single table database for key-value store (it already has multiple columns format) with a simple Ruby API. Useful for a lot of things. You can also use Tokyo Tyrant for service.

Deployment

• Capistrano - although there are some simpler alternatives around, I simply love Capistrano and use it for almost everything deployment-related.
• capistrano-ext - with multistaging deployment, among other goodies.

This tutorial covers building a web application from scratch using Rails with the styled_objects plugin.

As an example we will be building a very static front-end website, mainly to focus on stylesheets.

Everything you get from can be applied to more complex applications.

Because this is such a simple application, we won't be using scaffolding generators.

About styled_obejcts

styled_objects is a Rails plugin for simplifying stylesheet management on your application.

Instead of having one or more large stylesheets on your public folder, have many. Keep your CSS close to their respective templates. styled_objects will compile them into one file per page.

Getting started

1. Bootstrap your Rails app

$ rails testapp

2. Install the LESS gem:

Edit your config/environment.rb and place, anywhere before the "end":

config.gem 'less'

Run on the shell:

$ sudo rake gems:install

2. install the styled_objects plugin

script/plugin install git://github.com/pgte/styled_objects.git

The application

Here we will be building a simple example application for an e-commerce website.
First we will be focusing on building the controllers and the views, and finally we will learn how to style them with styled_objects.

To start we will be having products and product categories. One product can be in many categories and one category can contain many products. So, it is a many-to-many relationship.

For the sake of simplicity, let's say a product has a name and a description.

Each category have a name.

(I won't go through the building of the models, it's beyond the scope of this tutorial).

Product page

After you have your migrations and models setup, we need to configure the routes for our products controller.

Edit your config/routes.rb and add:

map.resources :products

Now build the controller under app/controllers/products_controller.rb. For now we will only have a "show" action:

class ProductsController < ApplicationController

  def show
    @product = Product.find(params[:id])
  end

end

Do the show template  under app/views/products/show.html.erb:

<h1><%= h @product.name %></h1>
<p><%= h @product.description %></p>

Category page

On this page we will be presenting all products on the current category.

Build the product category routes ou config/routes.rb:

config.resources :categories

Next, build the controller under app/controllers/categories_controller.rb:

class CategoriesController < ApplicationController

  def show
    @category = Product.find(params[:id], :include => :products)
  end

end

And the view under app/views/categories/show.html.erb:

<h1><%= h @category.name%></h1>

<p>products in this category:</p>

<%= render :partial => 'products/product', :collection => @category.products %>

This template is a bit more complex than the product show one because it presents all the products inside the current category by calling the products/_product.html.erb partial for each product.

Let's do this partial (under app/views/products/_product.html.erb):

<h2><%= link_to h(product.name), product_path(product) %></h2>
<p><%= h truncate(product.description) %></p>

Here, instead of presenting the full product description, we truncate it using the ActionView truncate helper, presenting only the first 30 characters of the product description.

Styling up

So, now that we have the category and product pages in place, we need to style them.

But first we need to style the whole website.

Global styling

Personally, I feel comfortable with using this folloing setup when starting a website, but it is not a requirement for styled_objects. (We haven't got there yet).

Reset stylesheet

There are numerous reset stylesheets out there. I particulary like the one bundled inside blueprint CSS.

So, grab a copy of blueprint and extract the blueprint/src/reset.css file and copy it into public/stylesheets/ directory.

Next, edit your app/views/layouts/application.html.erb and add the following line before the </head> tag:

<%= stylesheet_link_tag 'reset' %>

Typography sytlesheet

This is where we add a special stylesheet only for defining your typography. This is where you will be styling your p, a, ul, li, table, etc. tags.

This is your job, but I like to start from the blueprint/src/typography.css bundled on blueprint.

Save this file into public/stylesheets and add the respective the stylesheet link tag right after the reset one:

<%= stylesheet_link_tag 'reset' %>
<%= stylesheet_link_tag 'typography' %>

This stylesheet you will be formatting according to the desired look of your website.

Layout stylesheet

Before building a layout stylesheet, you need to build your layout markup. This will be done inside app/layouts/application.html.erb :

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
		<title>Untitled Document</title>
		<%= javascript_include_tag 'jquery-1.3.2.min' %>
		<%= stylesheet_link_tag 'reset' %>

	</head>
	<body>
      <div class="container">
        <div id="header"><h1>Welcome to ACME</h1></div>
        <div id="main">
          <%= yield %>
        </div>
      </div>
	</body>
</html>

So, on inside our HTML body tag we have a div tag with a "container" class. This "container" class will be used to center and fix the width of our content.

This is what goes inside the layout stylesheet, under public/stylesheets/layout.css:

.container {
  width: 950px;
  margin: 0 auto;
}

So, we are setting the width of content area of our website and centering it.

A lot more could be done here, like styling the header div. This also should be done on the layout stylesheet.

The main idea here is: use the layout stylesheet to only style markup on the layout template. Don't style more than that here.

Local styling

Now we want to style our templates and partials individually. That's where styled_objects comes in.

This plugin allows you to define the styles per template or partial wiathout adding any code.

First we need to call this helper on the app/views/layouts/application.html.erb file:

<%= so_stylesheet_link_tag %>

Place it right before the </head> tag. This helper creates the link tag to the URL for the "glued" stylesheet of each page.

We now begin with the product show page.

Create app/views/products/show.css and edit it.

We want to style the title and the description:

background-color: #e0e0e0;
h1 {color: #f576d8; border-bottom: 1px solid #822321};
p {padding: 1em 0; background-color: #fff;, border-top: 1px solid #d6d6d6}

On the first line we see something that isn't pure CSS: the background color style declared on the root of the CSS document. That's there because we are styling the show.html.erb template, not any sub node.

Now we want to style the product category page.

Create app/views/categories/show.css:

border-top: 5px solid black;
background-color: #f7f7f7;
h1 {letter-spacing: -2px; color: #3e3e3e}

Here we're giving the category show template a top border (line 1), a background-color (line 2) and we're also styling the title on line 3.

This category show template also shows the products and for that it uses the products/_product.html.erb partial.

We also wish to style this partial. Create the file app/views/products/_product.css:

background-color: #999;
border: 1px solid #333;
float: left;
h2 {text-transform: uppercase}

AJAX loading

So, styled_objects collects the needed CSS fragments on each page and constructs one URL that references all the "glued" CSSes.

What if I want to have a shopping basket partial that is called by AJAX instead of normal partial rendering inside a template?

Simple: just add <%= so_include_partial(partial_path) %> (or <%= so_include_template(template_path) %> if it's a template) to anywhere on the calling template. The partial CSS will be included.

Next: See the Advanced styled_objects on Rails Tutorial

More

Read more about object-oriented CSS here:

• Object-oriented CSS by stubbornella

See the presentation video:

• Object-oriented CSS by stubbornella

Other resources

• LESS syntax
• styled_objects Rails plugin
• blueprint CSS framework

styled_objects is a Rails plugin for simplifying stylesheet management on your application.

Instead of having one or more large stylesheets on your public folder, have many. Keep your CSS close to their respective templates. styled_objects will compile them into one file per page.

Why do I need styled_objects?

Because It’s hard to keep order on your application. Having one or many big stylesheet files is not easy. It’s hard do build, maintain and debug.

Do object-oriented stylesheets. Each presentation object has its own style definitions. With styled_objects everything is where expected.

You also make your stylesheets independent from each other, making it easier to find problems extend your app.

» Check out this presentation for a full pitch on OOCSS (Object-Oriented CSS).

Check out http://wiki.github.com/pgte/styled_objects

But maintaining cache consistency across a distributed Rails application can be challenging.

When page caching, Rails writes page result in a static file on the public folder (when using the default options), allowing the web server to serve it directly.

Expiring cache

Cache expiration must be done explicitly by your app using the expire_page command. This should be done when changes are made to your model (creations, deletions and updates), and should affect one or more pages, depending on your app. The cache expiration should be placed on model sweepers, as explained here.

Distributed environment

What about whenu  you are using more than one box for serving your Rails app? When one box calls ethe expire page command, it only cleans the local cache, rendering the other boxes cache remain inconsistent.

Solutions

There are several solutions to this. Let's look at them:

1. dRb cache store

dRb (or distributed Ruby) cache store uses a singleton process to communicate your cache decisions. This is not a good solution because:

• there is a single point of failure: the dRb process
• web servers generally can't talk to dRb. even if they could, serving static files locally is much faster

2. Memcache Store

Using a memcached service is one good solution. Memcached can be use clustering and load balancing, and it is pretty fast. But, if you are using a distributed Rails environment mainly for the sake of redundancy, or don't want to complicate the environment setup, don't use memcache store.

3. Cron-based expiration

You can expire cache on a scheduled basis. This can be enough for some applications. But for some, specially when you have to keep a tight  cache consistency, this is not enough

4. Build your own distributed cache cleaning

In this solution, your model cache sweepers are responsible for cleaning the cache (deleting page cache files) on the other machines.

But how does one machine contact the other machines?

One solution I came up with envolves every machine having a Mongrel server listening on a public TCP port. (When I say public,. mean accessible to the other machines on the cluster. This is not a service that you  want to be public on the internet) .

This HTTP service is there just to listen to cache expiration events. It accepts, as arguments, the paths of the page cache

Security concerns

This service can be implemented on your Rails app, but it should not be accessible to

Drawbacks

There are several problems with this aproach:

1. Every machine must know each other

In order for one machine to contact each other when expiration must occur, every machine must know the other machines. This can be challenging using Rails config, but can be done in Capistrano tasks.

2. It does not scale well

Every time you add a machine you are increasing the cache expiration cost.

3. Fault tolerance

When you expire a cache page, you must contact EVERY other box. If the cache expiration service of one box is down, the cache expiration will fail. Error handling must be done carefully, having a fall-back mechanism like putting the cache expiration command on a queue.

A better solution

One better solution is to make cache expiration events ASYNCHRONOUS. When expiring a page, an event is triggered, and every other box is listening on this channel.

This can be achieved using UDP broadcasts, and having every box listening on this UDP port.

Drawbacks (again)

A fall-back mechanism must be in place, though, in case one box is down during the cache expiration event, rendering the cache inconsistent.

This can be done using some kind of persistent message queue instead of UDP broadcasts, but I think this can be an overkill for most applications.

Expect to hear from me soon regarding the implementation of this solution!

acts_as_xapian installs the search engine database inside the plugin directory, under xapiandbs. If you use Capistrano as a deployment tool and since the entire codebase is rewritten (including the plugin directory),  you will have to rebuild the entire index every time you do a deployment.

What you need to do is to locate Xapian somewhere capistrano deployments will not overwrite.

Fortunately you can point the Xapian DB to somewhere else more convenient. Simply create a file under config/xapian.yml. Mine looks like this:

development:
  base_db_path: xapian/database
staging:
  base_db_path: xapian/database
production:
  base_db_path: xapian/database

This is telling xapian on the development, staging and production environments to look for the database under the <RAILS_ROOT>/xapian/database.

You will have to create a folder under the deployment shared folder named "xapian/database".

Next you will have to tell Capistrano to relink <RAILS_ROOT>/xapian/database to this shared directory using a Capistrano hook:

after "deploy:symlink", "deploy:symlink_xapian_db"

...

namespace :deploy do

...

  task :symlink_xapian_db do
    xapian_database_path = 'xapian/database'
    run "mkdir -p #{shared_path}/#{xapian_database_path}"
    run "ln -sf  #{shared_path}/xapian #{release_path}/xapian"
  end

end

You will only have to build the index once using

'rake xapian:rebuild_index models="ModelName1 ModelName2"'