Simone Carletti's Blog » plugins

BreadcrumbOnRails now open-source

Simone Carletti — Fri, 27 Nov 2009 21:07:30 +0000

A few months ago I created BreadcrumbsOnRails to solve the recurrent pattern of creating breadcrumb navigations with Ruby on Rails. Today I’m open-sourcing the project and the code is now available on GitHub.

BreadcrumbsOnRails is a simple Ruby on Rails plugin for creating and managing a breadcrumb navigation for a Rails project. It provides helpers for creating navigation elements with a flexible interface.

You can install BreadcrumbsOnRails as a Gem

1	$ gem install breadcrumbs_on_rails --source http://gemcutter.org

1
2
3
4
5
6
7
8

Rails::Initializer.run do |config|

# other configurations
# ...

config.gem "breadcrumbs_on_rails", :source => "http://gemcutter.org"

end

or as a Rails plugin

1	$ script/plugin install git://github.com/weppos/breadcrumbs_on_rails.git

Usage

Creating a breadcrumb navigation menu in your Rails app using BreadcrumbsOnRails is really straightforward.

In your controller, call add_breadcrumb to push a new element on the breadcrumb stack. add_breadcrumb requires two arguments: the name of the breadcrumb and the target path.

1
2
3
4
5
6
7
8
9
10
11
12

class MyController

add_breadcrumb "home", root_path
add_breadcrumb "my", my_path

def index
# ...

add_breadcrumb "index", index_path
end

end

In your view, you can render the breadcrumb menu with the render_breadcrumbs helper.

1
2
3
4
5
6
7
8
9
10
11
12

DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

untitled

<%= render_breadcrumbs %>

render_breadcrumbs understands a limited set of options. For example, you can pass change the default separator with the :separator option.

1
2
3

<%= render_breadcrumbs :separator => ' / ' %>

More complex customizations require a custom Builder.

Breadcrumb Element

A breadcrumbs menu is composed by a number of Element objects. Each object contains two attributes: the name of the breadcrumb and the target path.

When you call add_breadcrumb, the method automatically creates a new Element object for you and append it to the breadcrumbs stack. Element name and path can be one of the following Ruby types:

Symbol
Proc
String

Symbol

If the value is a Symbol, the library calls the corresponding method defined in the same context the and sets the Element attribute to the returned value.

1
2
3
4
5
6
7
8
9
10
11
12
13

class MyController

# The Name is set to the value returned by
# the :root_name method.
add_breadcrumb :root_name, root_path

protected

def root_name
"the name"
end

end

Proc

If the value is a Proc, the library calls the proc passing the current view context as argument and sets the Element attribute to the returned value. This is useful if you want to postpone the execution to get access to some special methods/variables created in your controller action.

1
2
3
4
5
6
7
8

class MyController

# The Name is set to the value returned by
# the :root_name method.
add_breadcrumb Proc.new { |c| c.my_helper_method },
root_path

end

String

If the value is a Proc, the library sets the Element attribute to the string value.

1
2
3
4
5
6
7

class MyController

# The Name is set to the value returned by
# the :root_name method.
add_breadcrumb "homepage", "http://example.com/"

end

Restricting breadcrum scope

The add_breadcrumb method understands all options you are used to pass to a Rails controller filter.
In fact, behind the scenes this method uses a before_filter to store the tab in the @breadcrumbs variable.

Taking advantage of Rails filter options, you can restrict a tab to a selected group of actions in the same controller.

1
2
3
4
5
6
7
8
9
10
11
12

class PostsController < ApplicationController
add_breadcrumb "admin", admin_path
add_breadcrumb "posts, posts_path, :only => %w(index show)
end

class ApplicationController < ActionController::Base
add_breadcrumb "admin", admin_path, :if => :admin_controller?

def admin_controller?
self.class.name =~ /^Admin(::|Controller)/
end
end

Internationalization and Localization

BreadcrumbsOnRails is compatible with the standard Rails internationalization framework.

For example, if you want to localize your menu, define a new breadcrumbs node in your .yml file with all the keys for your elements.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# config/locales/en.yml
en:
breadcrumbs:
homepage: Homepage
first: First
second: Second
third: Third

# config/locales/it.yml
it:
breadcrumbs:
homepage: Homepage
first: Primo
second: Secondo
third: Terzo

In your controller, use the I18n.t method.

1
2
3
4
5
6
7

class PostsController < ApplicationController add_breadcrumb I18n.t("breadcrumbs.first"), first_path add_breadcrumb I18n.t("breadcrumbs.second"), second_path, :only => %w(second)
add_breadcrumb I18n.t("breadcrumbs.third"), third_path, :only => %w(third)
end

class ApplicationController < ActionController::Base
add_breadcrumb I18n.t("breadcrumbs.homepage"), root_path
end

Resources

BreadcrumbsOnRails is released under the terms of the MIT License. The source code is available on GitHub.

BreadcrumbsOnRails is not suitable for a generic navigation menu. If you are looking for a way to create a generic or a tabbed navigation menu, check out my TabsOnRails plugin.

TabsOnRails 0.3.0 with concurrent tabs support aka namespaces

Simone Carletti — Sat, 02 May 2009 12:35:31 +0000

TabsOnRails is a simple Rails plugin for creating and managing Tabs in Rails projects. It provides helpers for creating tabs with a flexible interface.

The release 0.3.0 is now available as a GEM. The most important feature is the concurrent tabs support, also known as multi-tabs or namespaces. Namespaces enable you to create and manage tabs in parallels. Let me show you an example.

Let’s assume your application provides a first level navigation menu with 3 elements: :home, :dashboard, :projects. The relationship between your tabs and your controllers is 1:1 so you should end up with the following source code.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

class HomeController
set_tab :home
end

class DashboardController
set_tab :dashboard
end

class ProjectsController
set_tab :projects

def first; end
def second; end
def third; end
end

The project controller contains 3 actions and you might want to create a second-level navigation menu. This menu should reflect the navigation status of the user in the project page.

Without namespaces, you wouldn’t be able to accomplish this task because you already set the current tab value to :projects. You need to create a concurrent navigation menu and uniquely identify it with a custom namespace.
Let’s call it :navigation.

1
2
3
4
5
6
7
8
9
10
11
12

class ProjectsController
set_tab :projects

# Create an other tab navigation level
set_tab :first, :navigation, :only => %w(first)
set_tab :second, :navigation, :only => %w(second)
set_tab :third, :navigation, :only => %w(third)

def first; end
def second; end
def third; end
end

Voilà! That’s all you need to do. And you can create an unlimited number of namespace as long as you use an unique name to identify them.

The default namespace is called :default. Passing :default as name is the same as don’t using any namespace at all. The following lines are equivalent.

1 2	set_tab :projects set_tab :projects, :default

Namespaces supports all the other features already available in TabsOnRails including custom Builders for your Rails tabs. See the documentation page for further information.

You can install/upgrade TabsOnRails by running

1	$ sudo gem install weppos-tabs_on_rails --source http://gems.github.com

ActiveRecord::MultiConditions development discontinued

Simone Carletti — Sun, 26 Apr 2009 19:55:49 +0000

As of April 2009, I decided to discontinue the development of ActiveRecord::MultiConditions to concentrate my efforts on other projects.

If you are looking for a good alternative, I encourage you to have a look at Ben Johnson’s Searchlogic library. SearchLogic provides all ActiveRecord::Multiconditions features along with many other cool stuff.

There are many other projects that needs my assistance at the moment. I’m planning to release a new version of Tabs On Rails with multiple tabs support, the Google Analytics on Rails plugin needs to be completed and I’m working on a couple of Rails products. I definitely want to make a private beta version of GetLinkTo available in a couple of months.

TabsOnRails: creating and managing Tabs with Ruby on Rails

Simone Carletti — Sat, 25 Apr 2009 14:42:48 +0000

TabsOnRails is a simple Rails plugin for creating and managing Tabs. It provides helpers for creating tabs with a flexible interface.

If you ever had to create a tab-based navigation menu at least once, you perfectly know how much it can annoying. You have to create the menu, set active status in your controllers and reflect selection status in your view. TabsOnRails does all the boring stuff for you and let you focus on the customization.

Let me show you how it works.

Quick Start

In your template use the tabs_tag helper to create your tab.

1
2
3
4
5

<%= tabs_tag do |tab| %>
<%= tab.home 'Homepage', root_path %>
<%= tab.dashboard 'Dashboard', dashboard_path %>
<%= tab.account 'Account', account_path %>
<% end %>

The example above produces the following HTML output.

1
2
3
4
5

<ul>
<li><a href="/">Homepage</a></li>
<li><a href="/dashboard">Dashboard</a></li>
<li><a href="/account">Account</a></li>
</ul>

The usage is similar to the Rails route.rb file. You create named tabs with the syntax tab.name_of_tab. The name you use creating a tab is the same you’re going to refer to in your controller when you want to flag the tab as active with current_tab.

1
2
3

class DashboardController < ApplicationController
current_tab :dashboard
end

Now, for any action defined in the DashboardController, the template will automatically render the following HTML code.

1
2
3
4
5

<ul>
<li><a href="/">Homepage</a></li>
<li><span>Dashboard</span></li>
<li><a href="/account">Account</a></li>
</ul>

Restricting current_tab scope

Off course, there are specific situations where you need to change current_tag only for some specific action in your controller.

The current_tab method understands all options you are used to pass to a Rails controller filter. In fact, behind the scenes this method uses a before_filter to set a special @current_tab variable. Taking advantage of Rails filter options, you can restrict a tab to a selected group of actions in the same controller.

1
2
3
4
5
6
7
8
9
10
11
12

class PostsController < ApplicationController
current_tab :admin
current_tab :posts, :only => [ :index, :show ]
end

class ApplicationController < ActionController::Base
current_tab :admin, :if => :admin_controller?

def admin_controller?
self.class.name =~ /^Admin(::|Controller)/
end
end

Customizations

All your tabs belongs to you! Easily to understand, your tab structure might be slightly different that the default one. For example, you might want to flag the active tab with a current CSS class and preserve the link with a nice hover effect. Or perhaps your tab is an ordered list (

No problem! The library is completely customizable using custom builders. See the documentation for further details on how to create and use a custom Tab Builder.

Here’s just a couple of examples created using custom builders.

Cool! How do I get the plugin?

Source code and issue management is powered by GitHub, the project homepage and documentation are hosted on this site. The plugin is available both as a GEM and as a Rails plugin. See the documentation page to learn how to install it.

Helperful 0.3.0

Simone Carletti — Mon, 16 Mar 2009 23:46:34 +0000

Last week I released a new minor version of the Helperful GEM. This is essentially a bugfix release, although it comes with one minor new feature: the javascript_content_for tag. The following overview is taken directly from the documentation.

The javascript_content_for helper combines the features of content_for and javascript_tag into a single helper.

1
2
3

<% javascript_content_for :head do %>
$("#id").hide();
<% end %>

The block is passed as it is to javascript_tag, then the result is stored as content_for :head.

Now you can call yield and output your javascript content.

1 2	<%= yield :head %>

This example is equal to the following statements.

1
2
3
4

<% javascript_content_for :head do; javascript_tag do %> $("#id").hide(); <% end; end %>
<% javascript_content_for :head do %>

<% end %>

This feature also addresses an annoying bug in the has_content helper method caused by an undefined variable.

To install or upgrade:

1	gem install weppos-helperful --source http://gems.github.com

More features still to come. Visit the project page for further details.

Helperful: a large collection of Rails Helpers

Simone Carletti — Thu, 26 Feb 2009 08:28:19 +0000

Helperful aims to be a collection of useful and reusable Rails helpers.

Rails Installation

As a Gem

This is the preferred way to install Helperful and the best way if you want install a stable version.

1	$ gem install weppos-helperful --source http://gems.github.com"

You can specify the GEM dependency in your application environment.rb file:

1
2
3
4
5
6

Rails::Initializer.run do |config|
# other configurations
# ...

config.gem "weppos-helperful", :lib => "helperful", :source => "http://gems.github.com"
end

As a Plugin

This is the preferred way if you want to live on the edge and install a development version.

1	$ script/plugin install git://github.com/weppos/helperful.git

Available Helpers

The list of available helpers actually includes AffiliationsHelper, ContentHelper and the more famous TitleHelper.

Affiliations Helper

Provides a set of helpers for working with online affiliations.

For example, the tradedoubler_verification_tag helper method returns the site verification tag required by Tradedoubler to verify the publisher account ownership.

1
2
3
4
5

# In your template
<%= tradedoubler_verification_tag('00112233') %>

# Will produce the following output.

Content Helper

Provides a set of helpers for capturing and working with your page content in a more effective way.

Fo example, the has_content? helper is a natural fulfillment for the original content_for helper.

1
2
3
4
5
6

<% content_for :foo do %>

This is a foo content.

<% end %>

<% has_content? :foo # => true %>
<% has_content? "foo" # => true %>

Title Helper

Provides an helper for managing page title in Rails views and layouts.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# Include the helper in your controller.
# You might want to include it in ApplicationController to make it available
# always and everywhere in your templates.
class ApplicationController < ActionController::Base
helperful :title
end

# Now you can use set a title in your action
# Example. index.html.rb

<%= title 'This is a title' %>

# And print the title with a :site decorator in your layout.
<%= title :site => 'My Cool Site!' %>

<%= yield %>

Documentation and Repository

Visit the project page or the documentation for further details. The repository is available on GitHub for forking or reference. Feel free to add more helpers and send me a pull request. Please ensure new helpers come with an appropriate test suite.