link2 0.1.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Jonas Grimfelt
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.textile

@@ -0,0 +1,211 @@
+h1. LINK²
+
+_Generation next *link_to*-helper for Rails: Spiced with intelligence, and semantic beauty._
+
+h2. Introduction
+
+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.
+
+This is *not* a re-implementation of @link_to@/@button_to@-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 prototyping-friendly link helpers - with no trade-offs, really.
+* Based on specified arguments: Use what's know to make smart assumptions => DRYer - and more maintainable view code.
+* Use power of I18n: 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.
+* Full test-coverage for stability.
+* Well-documented code.
+
+h2. Dependencies
+
+* "rails 2.3.x":http://github.com/rails/rails only. Might as well work with Rails 3 already, but I didn't write that.
+
+For testing: test-unit, and "left-right":http://github.com/jordi/leftright.
+
+h2. Installation
+
+"Drop a *Gem* on 'em":http://open.spotify.com/track/2pqKuHtn8ZKMMMqbJrA2e7:
+
+<pre>
+  $ sudo gem install link2
+</pre>
+
+h2. Setup
+
+Generate initializer (optional):
+
+<pre>
+  $ ./script/generate link2
+</pre>
+
+h2. Usage
+
+*A few examples* using the spiced up @link_to@/@button_to@ helpers, using our trusty fellow *Post* class:
+
+<pre>
+  link "No operation"
+    # => link_to 'No operation', '#'
+
+  link "Hilarious", 'http://bash.org'
+    # => link_to 'No operation', 'http://bash.org'
+
+  link 'http://bash.org'
+    # => link_to 'http://bash.org', 'http://bash.org'
+
+  link :home
+    # => link_to I18n.t(:home, ...), root_path
+
+  link :back
+    # => link_to I18n.t(:home, ...), :back
+
+  link @post
+    # => link_to I18n.t(:show, ...), post_path(@post)
+
+  link [@post, @comment]
+    # => link_to I18n.t(:show, ...), post_comment_path(@post, @comment)
+
+  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 "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
+
+  ...
+</pre>
+
+...and for the record (not yet implemented, but soon):
+
+<pre>
+  link :edit, [@post, @comment]
+    # => ::Link2::NotImplementedYetError, "case link(:action, [...]) not yet supported. Need to refactor some stuff."
+
+  link :new
+    # => ::Link2::NotImplementedYetError, "Auto-detection of resource is not supported yet."
+</pre>
+
+Same works for @button_to@, and you also can optionally use the branded aliases: @link2@ and @button2@.
+
+h2. Options hashes: URL Options + HTML Options
+
+Link2 link helpers accept options in the same way as the core helpers @link_to@/@button_to@: first @options@ (a.k.a. @url_options@) and then @html_options@. See the "Rails core UrlHelpers documentation":http://railsapi.com/doc/rails-v2.3.5/classes/ActionView/Helpers/UrlHelper.html#M002452 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.
+
+h2. Expected arguments
+
+A summary of the expected argument flavors if the examples for the curious minds:
+
+<pre>
+  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)
+</pre>
+
+Same applies to the @button@ helper, naturally.
+
+h2. I18n
+
+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:
+
+<pre>
+  Link2.setup do |config|
+    config.i18n_scopes = [
+        '{{models}}.links.{{action}}',
+        'links.{{action}}'
+      ]
+  end
+</pre>
+
+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)
+
+<pre>
+  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"
+</pre>
+
+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.
+
+<pre>
+  class CaptainMorgan < ActiveRecord::Base
+    def to_s
+      "Captain ##{self.id}"
+    end
+  end
+</pre>
+
+*4. Go*
+
+Now - with the config and translations setup - let the unicorn free:
+
+<pre>
+  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
+</pre>
+
+h2. TODO
+
+See "TODO":http://github.com/grimen/link2/blob/master/TODO
+
+h2. A note on design decisions
+
+I didn't extend the behavior for the helper @link_to_if@, @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.
+
+h2. License
+
+Released under the MIT license.
+Copyright (c) "Jonas Grimfelt":http://github.com/grimen

data/Rakefile

@@ -0,0 +1,70 @@
+# encoding: utf-8
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require File.join(File.dirname(__FILE__), 'lib', 'link2', 'version')
+
+# Gem managment tasks.
+#
+# == Generate gemspec, build & install locally:
+#
+#   rake gemspec
+#   rake build
+#   sudo rake install
+#
+# == Git tag & push to origin/master
+#
+#   rake release
+#
+# == Release to Gemcutter.org:
+#
+#   rake gemcutter:release
+#
+begin
+  gem 'jeweler'
+  require 'jeweler'
+
+  Jeweler::Tasks.new do |spec|
+    spec.name         = "link2"
+    spec.version      = ::Link2::VERSION
+    spec.summary      = %{Generation next link_to-helper for Rails: Spiced with intelligence, and semantic beauty.}
+    spec.description  = spec.summary
+    spec.homepage     = "http://github.com/grimen/#{spec.name}"
+    spec.authors      = ["Jonas Grimfelt"]
+    spec.email        = "grimen@gmail.com"
+
+    spec.files = FileList["[A-Z]*", File.join(*%w[{generators,lib,rails} ** *]).to_s]
+
+    spec.add_dependency 'activesupport', '>= 2.3.0'
+    spec.add_dependency 'actionpack', '>= 2.3.0'
+
+    spec.add_development_dependency 'test-unit', '= 1.2.3'
+    spec.add_development_dependency 'activerecord', '>= 2.3.0'
+  end
+
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler - or one of its dependencies - is not available. " <<
+  "Install it with: sudo gem install jeweler -s http://gemcutter.org"
+end
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the plugin.'
+Rake::TestTask.new(:test) do |test|
+  test.libs = ['lib', 'test']
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+desc 'Generate documentation for the plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = ''
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('init.rb')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/TODO

@@ -0,0 +1,49 @@
+TODO
+
+* Implement the problematic one: link(:action, [@parent, @resource])
+
+* Write tests for options hashes as well: url_options vs. html_options
+
+* Generate proper DOM ID selectors, e.g. class="new post"
+
+  DOM Selectors
+
+  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:
+
+  <pre>
+    link :new, Post
+      # => <a class="new post" ...>...<a/>
+
+    link :edit, @post_14
+      # => <a id="edit_post_14_action" class="edit post" ...>...<a/>
+
+    link :back
+      # => <a class="back" ...>...<a/>
+  </pre>
+
+* Fix action mapping procs to handle named scopes. Should work, but do not for some reason. =/
+
+* Fix action mapping procs to receive session, params, etc in a options hash. My mocking/stubbing don't want to work. ='(
+
+* Allow customization of alternatives to Object#to_s for parsing object label, i.e. {{name}} interpolation.
+* Collections detection:
+
+    link(:index)  =>  link(@posts)   =>  link(:index, @posts)   =>  link("Index", @posts)
+
+* Auto-detect current resource instance for member views (non-collection)
+
+    link(:edit)   =>  link(:edit, @post)
+
+  Detect using "self.controller_name.singularize", or use "resource" if InheritedResources is used.
+
+* Add support: #link_to_function + #button_to_function: I18n, more?
+
+    js_link(:hello, "alert('Clicked :hello.');")  =>  link_to_function(I18n.t(:hello, ...), "alert('Clicked :hello.');")
+
+* Add support: #link_to_remote + #button_to_remote: I18n, more? Could probably be cleaned up quite a lot.
+
+    ajax_link(...)
+
+Consider:
+
+* Possible parse TITLE-attribute from the model, say Object#link_title or similar.

data/generators/link2/link2_generator.rb

@@ -0,0 +1,11 @@
+# encoding: utf-8
+
+class Link2Generator < Rails::Generator::Base
+
+  def manifest
+    record do |m|
+      m.template 'initializer.rb', File.join(*%w[config initializers link2.rb])
+    end
+  end
+
+end

data/generators/link2/templates/initializer.rb

@@ -0,0 +1,14 @@
+# encoding: utf-8
+
+if defined?(::Link2)
+  ::Link2.setup do |config|
+    # Configure how - and in what order - link labels should be looked up.
+    # config.i18n_scopes = ['links.{{action}}']
+    #
+    # Configure any custom action mappings.
+    # config.action_mappings = {
+    #   :home => lambda { root_path },
+    #   :back => lambda { |url| url || session[:return_to] || :back }
+    # }
+  end
+end

data/lib/link2.rb

@@ -0,0 +1,115 @@
+# encoding: utf-8
+begin
+  require 'active_support'
+rescue LoadError
+  gem 'activesupport'
+  require 'active_support'
+end
+
+begin
+  require 'action_view'
+rescue LoadError
+  gem 'actionpack'
+  require 'action_view'
+end
+
+module Link2
+
+  autoload :Brain,    'link2/brain'
+  autoload :Helpers,  'link2/helpers'
+  autoload :I18n,     'link2/i18n'
+  autoload :Support,  'link2/support'
+  autoload :VERSION,  'link2/version'
+
+  # include ::ActionController::UrlWriter
+
+  # Default URL value; if none can be assumed. Useful value for prototyping.
+  DEFAULT_LINK = '#'
+
+  # Default lookup scope if none is set.
+  DEFAULT_I18N_SCOPE = [:links]
+
+  # Default I18n lookup scopes if none are set.
+  DEFAULT_I18N_SCOPES = [
+    '{{resource}}.links.{{action}}',
+    'links.{{action}}'
+  ]
+
+  Error = Class.new(::StandardError)
+  NotImplementedYetError = Class.new(::NotImplementedError)
+
+  # TODO: Make aware of named routes.
+  # include ::ActionController::UrlWriter # don't work as expected here (isolated run), but works in Rails app =S
+  #
+  # Don't work even if Rails API docs tells so... 8(
+  # http://api.rubyonrails.org/classes/ActionController/UrlWriter.html
+  # ActionController::UrlWriter.root_path
+
+  # Default action mappings: Link value shortcuts sort of.
+  # FIXME:
+  # DEFAULT_ACTION_MAPPINGS = {
+  #   :home => lambda { '/' }, # TODO: Allow named routes, e.g. root_path
+  #   :back => lambda { |url| url || options[:session][:return_to] || :back }
+  # }
+  DEFAULT_ACTION_MAPPINGS = {
+    :home => lambda { '/' }, # TODO: Allow named routes, e.g. root_path
+    :back => lambda { |url| url || :back }
+  }
+
+  mattr_accessor :i18n_scope
+  @@i18n_scope = DEFAULT_I18N_SCOPE
+
+  # I18n lookup scopes in ascending order of priority.
+  # Used for scoped I18n translations based on model, action, etc.,
+  # for flexability.
+  mattr_accessor :i18n_scopes
+  @@i18n_scopes = DEFAULT_I18N_SCOPES
+
+  # Action mappings - a.k.a. "link value shortcuts" - that should
+  # be recognized.
+  mattr_accessor :action_mappings
+  @@action_mappings = DEFAULT_ACTION_MAPPINGS
+
+  class << self
+
+    # Yield self for configuration block:
+     #
+     #   Link2.setup do |config|
+     #     config.i18n_scope = [:actions]
+     #   end
+     #
+     def setup
+       yield(self)
+     end
+
+     # Finds any existing "action mapping" based on a mapping key (custom action).
+     #
+     # == Example/Usage:
+     #
+     #   Link2.action_mappings[:back] = lambda { |url| url || session[:return_to] || :back }
+     #
+     #   url_for_mapping(:back)
+     #   # => session[:return_to] || :back
+     #
+     #   url_for_mapping(:back, "/unicorns")
+     #   # => "/unicorns"
+     #
+     def url_for_mapping(action, custom_url = nil, options = {})
+       expression = ::Link2.action_mappings[action]
+       if expression.is_a?(Proc)
+         expression.arity == 0 ? expression.call : expression.call(custom_url)
+       else
+         expression
+       end
+     end
+
+   end
+end
+
+# Make I18n aware of our default locale.
+I18n.load_path.unshift File.expand_path(File.join(File.dirname(__FILE__), 'link2', 'locales', 'en.yml'))
+
+# Add extended ActionView behaviour.
+ActionView::Base.class_eval do
+  include ::Link2::Helpers
+end