LINK²

Generation next link_to-helper for Rails: Spiced with intelligence, and semantic beauty.

A better link helper for Rails designed with the principle of making smart assumptions based on what’s known to avoid repeated and unnecessary code declarations; and at the same time making the code more semantic/readable/beautiful (my subjective opinion). On top of that – for even more maintainable views – scoped I18n translations without lean defaults for fast prototyping. WIN-WIN-WIN.

Helpers:

• link_to enhanced by link
• button_to enhanced by button

This is not a re-implementation of these helpers; rather it wraps these but parses the specified method arguments and extracts as much known information as possible to fill in the missing pieces. The core helpers are not altered at all: You can call them old-school like there was no tomorrow (after using Link2 for a while you’ll spoiled and the core helpers will feel so yesterday, really).

Goals/Features:

• Rapid & flexible – prototyping-friendly link helpers – with no trade-offs, really.
• DRY – based on specified arguments: Use what’s know to make smart assumptions for more readable and maintainable view code.
• I18n deluxe – Lookup scoped translations based on action, model, etc., for more flexible translations – with lean defaults. Enhanced with some nifty interpolation features as well. Code first, translate later.
• DOM Selectors – Why defining DOM classes for RESTful links all the time when same patterns occur? Optionally DONE.
• Stable – Full test-coverage for stability. Unit + Rails integration tests, check: 59 tests: all passed
• Maintainable – Well-documented code.

Drop a Gem on ’em:

  $ sudo gem install link2

Dependencies:

• rails 2.3.x only. Might as well work with Rails 3 already, but I didn’t write that.

For testing: test-unit, mocha, and webrat. Optional: leftright

Generate initializer (optional):

  $ ./script/generate link2
    create    config/initializers/link2.rb

A few examples using the spiced up link_to/button_to helpers, using our trusty fellow Post class:

  link "No operation"
    # => link_to 'No operation', '#'

  link 'http://bash.org'
      # => link_to 'http://bash.org', 'http://bash.org'

  link "Hilarious", 'http://bash.org'
    # => link_to 'Hilarious', 'http://bash.org'

  link :home, '/intro'
    # => link_to I18n.t(:home, ...), '/intro'

  link :home
    # => link_to I18n.t(:home, ...), root_path

  link :back
    # => link_to I18n.t(:home, ...), :back

  link :index
     # => link_to I18n.t(:index, ...), posts_path                     # Note: auto-detected

  link :trash
    # => link_to I18n.t(:trash, ...), trash_post_path(@post)          # Note: auto-detected

  link :new
     # => link_to I18n.t(:new, ...), new_post_path(:id => @post.id)   # Note: auto-detected, id for current resource - if found - passed, makes the implementation more generic

  link @post
    # => link_to I18n.t(:show, ...), post_path(@post)

  link [@post, @comment]
    # => link_to I18n.t(:show, ...), post_comment_path(@post, @comment)

  link :go_back, :back
    # => link_to I18n.t(:go_back, ...), :back

  link :new, :post
    # => link_to I18n.t(:new, ...), new_post_path

  link :new, Post
    # => link_to I18n.t(:new, ...), new_post_path

  link :new, @post
    # => link_to I18n.t(:new, ...), new_post_path(:id => @post.id)    # ...if you think about it; useful for cloning.

  link :edit, @post
    # => link_to I18n.t(:edit, ...), edit_post_path(@post)

  link :edit, [@post, @comment]
    # => link_to I18n.t(:edit, ...), edit_post_comment_path(@post, @comment)

  link :kick, @post
    # => link_to I18n.t(:kick, ...), kick_post_path(@post)

  link "All items", :index
    # => link_to "All items", posts_path                              # Note: auto-detected, see above

  link "New one!", :new, Post
    # => link_to "New one!", new_post_path

  link :new, UserSession { image_tag('sign_in_button.png') }
    # => link_to image_tag('sign_in_button.png'), new_user_session_path

  ...

Same works for button, and you also can optionally use the branded aliases: link2 and button2.

Link2 link helpers accept options in the same way as the core helpers link_to and button_to: first options (a.k.a. url_options) and then html_options. See the Rails core UrlHelpers documentation for details on this. Link2 helpers just pass any non-Link2-related options to the Rails core helpers. In other words no need to learn a new API; just pass the needed options like in the past.

A summary of the expected argument flavors if the examples for the curious minds:

  link(label, options = {}, html_options = {})
  link(url, options = {}, html_options = {}, &content_block)
  link(resource, options = {}, html_options = {}, &content_block)

  link(label, url, options = {}, html_options = {})
  link(action, resource, options = {}, html_options = {}, &content_block)

  link(label, action, resource)

Same applies to the button helper, naturally.

Link2 was designed with the power of I18n in mind; following certain lookup patterns to make it easier to manage link-translations even as your Rails-app grows. This is how in short:

1. Lookup scopes (Optional)

This is the default lookup order, in priority order:

  Link2.setup do |config|
    config.i18n_scopes = [
        '{{models}}.links.{{action}}',
        'links.{{action}}'
      ]
  end

Valid lookup scope interpolations:

• model – link model name, e.g. CaptainMorgan / @captain_morgan => “captain_morgan”
• models – pluralized link model name, e.g. CaptainMorgan / @captain_morgan => “captain_morgans”
• controller – current controller name
• action – the link action name

2. Translations (Optional)

  en:
    links:
      order: "Bartender!!"
      drink: "Drink your {{resource}} now"
    captain_morgans:
      links:
        order: "New barrel of rum with lime, ohoy!"
        drink: "Slurp {{name}} like a pirate"

Valid value interpolations:

• resource – resource humanized name (parsed with I18n if possible), e.g. CaptainMorgan / @captain_morgan => “captain morgan”
• resources – pluralized resource humanized name (parsed with I18n if possible), e.g. CaptainMorgan / @captain_morgan => “captain morgans”
• name – current resource name to_s-value, e.g. @captain_morgan.to_s => “Captain Morgan with Cola and lime #4”

3. Label parsing (Optional)

Customize to_s for your model(s) to return a more humane string.

  class CaptainMorgan < ActiveRecord::Base
    def to_s
      "Captain ##{self.id}"
    end
  end

4. Go

Now – with the config and translations setup – let the unicorn free:

  link :order, Caipirinha
    # => link_to "Bartender!!", new_caipirinha_path

  link :drink, @sour_caipirinha
    # => link_to "Drink your caipirinha now", drink_caipirinha_path(@sour_caipirinha)

  link :order, CaptainMorgan
    # => link_to "New barrel of rum with lime, ohoy!", new_captain_morgan_path

  link :drink, @captain_morgan_no_8
    # => link_to "Slurp Captain #8 like a pirate", drink_captain_morgan_path(@captain_morgan_no_8)  # See: CaptainMorgan#to_s

To make a web-designer’s life easier Link2 generates some semantic selector classes based on specified/known link properties for easier DOM-manipulation with CSS and javascript.

Examples:

  link :new, Post
    # => <a class="new post" ...>...<a/>

  link :edit, @post_14
    # => <a class="edit post id_14" ...>...<a/>

  link :back
    # => <a class="back" ...>...<a/>

  ...

Configuration:

This behavior is enabled by default but can be disabled just in case; preferably in the initializer:

  Link2.setup do |config|
    config.dom_selectors = false
  end

link_to_function

To get the Link2 features for link_to_function – which is deprecated in Rails 3 because of it’s obtrusive nature (note: obtrusive should be avoided) – you can get such behaviour with Link2 (if you must) by specifying :onclick HTML attribute like so:

  link :hello, :onclick => "alert('Hello world!')"

link_to_remote

No Link2-wrapper for this one. Also, it’s deprecated in Rails 3 as well for same reasons as above. In Rails 3 it should be possible to call it like so:

  link :hello, say_hello_path(@world), :remote => true

…but as Link2 is not tested with Rails 3 yet; use the old-school link_to for now.

link_to_if + link_to_unless

I didn’t extend the behavior for the helpers link_to_if and link_to_unless because I simply think they should not be used in Rails apps; my strong opinion is that they introduce unnecessary complexity in code and make it less readable. I also skipped link_to_if_current because it’s not very thorough implementation – even an extra URI slash make it confused, which is funny. Hate it, or LOVE IT.

I really like the declarative_authorization view helper DSL for checking permissions on models, and brought the pattern to the link helpers – they are like ying & yang:

  link(:edit, @account) if permitted_to?(:edit, @account)

…but I usually mix it with an alias:

  link(:edit, @account) if can?(:edit, @account)

Nice, huh? =)

See TODO

Released under the MIT license.
Copyright © Jonas Grimfelt