king_views 1.0.0

data/king_list/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 [name of plugin creator]
+
+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/king_list/README.rdoc

@@ -0,0 +1,21 @@
+= KingList
+
+King List provides helpers to be used in table listings and detail views.
+It has function for action icons, buttons, actions links and icons with hidden
+forms used to simulate PUT or DELETE requests
+
+== Example
+Please read the files in lib/  for further documentation and examples
+
+A tabled view
+  - table_for(@object) do
+    = t.column :firstname
+    = t.column :lastname, :sorting=>false
+
+A definition list view
+  - dl_for current_object do |f|
+    = f.show :creator
+    = f.show :created_at
+    = f.show :updated_at
+
+Copyright (c) 2009 Georg Leciejewski, released under the MIT license

data/king_list/Rakefile

@@ -0,0 +1,23 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the king_list plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the king_list plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'KingList'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/king_list/init.rb

@@ -0,0 +1 @@
+require "#{File.dirname(__FILE__)}/lib/king_list"

data/king_list/lib/king_list.rb

@@ -0,0 +1,18 @@
+# KingList
+# You need:
+# KingFormat Plugin for the table helper
+# - haml
+# - I18n 
+$LOAD_PATH << File.expand_path(File.dirname(__FILE__))
+require "king_list/overrides"
+require "king_list/list_helper"
+require "king_list/app_helper"
+require "king_list/builder/table"
+require "king_list/builder/show"
+
+
+# extend AC with our helper module
+ActionController::Base.helper KingList::ListHelper
+
+# Helper Functions used in application controller, which should be extracted a little more 
+ActionController::Base.helper KingList::AppHelper

data/king_list/lib/king_list/app_helper.rb

@@ -0,0 +1,30 @@
+module KingList
+  # Functions in here are only used by the table helper. Those should be moved
+  # to a more general place or an own king view helper
+  module AppHelper
+    # Returns the "real" (in URL visible) parameters of the current URL. That means all but the keys "action" and "controller"
+    def visible_params
+      @visible_params ||= params.dup.delete_if{|key,value| [:action, :controller].include?(key.to_sym)}
+    end
+
+    # Change some params of the current URL (and preserve all others)
+    # Example:
+    # If the current URL is
+    #    /clients?filter[letter]=T&filter[tags]=abc&mode=cards
+    # and you call:
+    #    change_params(:mode => 'list')
+    # The result is:
+    #    => /clients?filter[letter]=T&filter[tags]=abc&mode=list
+    #
+    # Attention, this method uses deep_merge, so it works recursive.
+    # See this example: If you call
+    #    change_params(:filter => { :letter => 'S' })
+    # you get
+    #    => /clients?filter[letter]=S&filter[tags]=abc&mode=list
+    # Beware that filter[tags] is NOT removed!
+    def change_params(options={})
+      visible_params.deep_merge(options)
+    end
+
+  end
+end

data/king_list/lib/king_list/builder/show.rb

@@ -0,0 +1,71 @@
+module KingList
+  module Builder
+    class Show
+
+      def initialize(object_name, object, template)
+        @object_name = object_name
+        @object = object
+        @template = template
+      end
+
+      #
+      # ==== Parameter
+      #   field_name<Symbol>:: The name of the field for the current object
+      #   options<Hash{:Symbol=>String}>:: A bunch of options to customize the output
+      #
+      # ==== Options hash:
+      #   :object => record. If not set the current_current is used
+      #   :value => cell content (if not set, it will be determined by object.field_name)
+      #   :link => if set, the value is placed in a link_to
+      #   :caption => text for dt-tag. If not set, the title is created automaticaly
+      #
+      # === Example haml
+      #  = f.show :created_at
+      #  = f.show :caption => 'Calculated', :value => 39.80
+      #
+      # valid html options will be applied to both dt and dd
+      #   options[:class] =>will be applied to dt and dd
+      #
+      # TODO:
+      # rename :caption to :title .. if it does not conflict
+      def show(field_name, options={})
+        if field_name.is_a?(Hash) && options.empty? # Short call without field_name
+          options = field_name
+          field_name = nil
+
+          # Value and caption are needed
+          raise ArgumentError unless options.has_key?(:caption)
+          raise ArgumentError unless options.has_key?(:value)
+        end
+
+        # Use given object or current_record as default
+        if options.has_key?(:object)
+          object = options.delete(:object)
+        else
+          object = @object
+        end
+
+        # Use given caption or translate column title
+        caption = options.delete(:caption) || object.class.human_attribute_name(field_name.to_s)
+
+        # Use given value or take formatted value as default
+        value = options.delete(:value) || @template.formatted_value(object, field_name)  || '&nbsp;'
+
+        # if link option is set, then link to this object
+        if link = options.delete(:link)
+          value = @template.link_to(value, link)
+        end
+
+        # Against HTML validity warnings
+        caption = '&nbsp;' if caption.blank?
+        value = '&nbsp;' if value.blank?
+
+        @template.capture_haml do
+          @template.haml_tag :dt, caption, options
+          @template.haml_tag :dd, value, options
+        end
+      end
+    
+    end #class
+  end # module
+end # module

data/king_list/lib/king_list/builder/table.rb

@@ -0,0 +1,166 @@
+module KingList
+  module Builder
+    class Table
+
+      attr_accessor :mode, :current_record, :current_column_number, :number_of_columns, :sorting
+
+      def initialize(template, collection, &block)
+        @template = template
+        @collection = collection
+      end
+
+      def start_row(data)
+        self.current_column_number = 0
+        self.current_record = data
+      end
+
+      # Build a column for a table
+      #
+      # ==== Parameter
+      # field_name<Symbol>:: Name of the object attribute (db column) to show in this column
+      # options<Hash{Hash, Symbol=>String}>:: A bunch of options to customize the th, td or content of the column
+      #
+      # ==== Options hash:
+      #   :object   => The record to use. If not set the current_object is used
+      #   :value    => cell content (if not set, it will be determined by calling field_name on object/current_record) => @client.name
+      #   :link     => if set, the value is wrapped in a link_to with the given link (if TRUE, the current object is used)
+      #   :row_link => if set, the value is wrapped in a link_to with the given link (if TRUE, the current object is used)
+      #   :title    => text for column title. If not set, the title is created automaticaly
+      #   :sort_fields => optional fields for order_by (if the column field does not exist in the database)
+      #   :sorting  => false to prevent sorting on this column
+      #   :th_options{Symbol=>String}:: options for the <th>
+      #       :class:: the class to set on the th
+      #   :td_options{Symbol=>String}:: options for the <td>
+      #     :class:: the class to set on the th
+      #   :align    => classes used for alignment. Values are :left or :right
+      def column(field_name, options = {})
+        options = options.deep_clone # for not changing outer variable
+        th_options = options[:th_options] || {}
+        td_options = options[:td_options] || {}
+
+        # Use given object from options (or current_record as default)
+        object = options.has_key?(:object) ? options.delete(:object) : current_record
+
+        # Cell alignment
+        align = options.delete(:align)
+        (th_options[:class] ||= '') << " #{align}" if align == :right
+        (td_options[:class] ||= '') << " #{align}" if align == :right
+
+        self.current_column_number += 1
+
+        case mode
+          when :counter
+            self.number_of_columns ||= 0
+            self.number_of_columns += 1
+            nil
+
+          when :header
+            # Take option or translate column title
+            title_text = options[:title] || object.class.human_attribute_name(field_name.to_s)
+
+            # whole table has sorting enabled and current column has NOT :sorting=>false
+            # => put sorting link into header
+            if sorting && (options.delete(:sorting) != false)
+              # Use given sort_fields or try to detect them automatic
+              sort_fields = options.delete(:sort_fields) || object.class.table_name + '.' + field_name.to_s
+              # Convert to comma separated string if it is an array
+              sort_fields = sort_fields.join(',') if sort_fields.is_a?(Array)
+              # Swap ASC/DESC on every click of the same column title
+              sort = (@template.params[:sort] == "ASC") ? 'DESC' : 'ASC'
+              # Now build the title
+              title = @template.link_to(title_text, @template.change_params(:sort_by => sort_fields, :sort => sort))
+              # if current sorting use class for css up/down image
+              if @template.params[:sort_by] == sort_fields
+                (th_options[:class] ||= '') << ( sort=='DESC' ? ' sortup' : ' sortdown')
+              end
+            else
+              # otherwise just plain text (no sorting link)
+              title = title_text
+            end
+            #mark the first and last columns with css classes
+            if self.current_column_number == 1
+              (th_options[:class] ||= '') << ' first'
+            elsif self.current_column_number == self.number_of_columns
+              (th_options[:class] ||= '') <<  ' last'
+            end
+           @template.capture_haml do
+            @template.haml_tag(:th, title.to_s, th_options)
+          end
+            
+
+          when :content
+            # Use given value (or formatted value as default)
+            value = options.delete(:value) || @template.formatted_value(object, field_name, value)
+
+            # If link option is set, then link to this
+            #
+            # ===Example
+            #
+            # :link => true : uses current object show link
+            #
+            # :link => nil or blank no linking
+            #
+            if link = options.delete(:link)
+              #link to current_oject if true given
+              link = object if link == true
+              if (!value.blank?) && (!link.blank?) #link and linked text is present
+                value = @template.link_to(value, link)
+              else #leave col text empty
+                value = ''
+              end
+            end
+
+            # If row_link option is set, then link to the current object
+            if row_link = options.delete(:row_link)
+              row_link = object if row_link == true
+              value = @template.link_to(value, row_link) unless value.blank?
+
+              # Set a css class for the <td>, so it can be found via JavaScript
+              # and an onclick-event can be installed (TODO)
+              td_options.merge!(:class => 'row_link')
+            end
+          @template.capture_haml do
+            @template.haml_tag(:td, value.to_s, td_options)
+          end
+#          @template.haml_concat
+        end # case mode
+      end
+
+      #build a table column which holds action links (edit/del/show/..) for each record
+      #is used for table listings ex. on index pages
+      #get a block containing multiple #action_
+      # ===Example haml
+      # - t.action_column do
+      #   = action_icon :edit, edit_path(person)
+      #   = action_icon :delete, destroy_path(person)
+      def action_column(options={}, &block)
+        self.current_column_number += 1
+
+        case mode
+          when :counter
+            self.number_of_columns ||= 0
+            self.number_of_columns += 1
+            nil
+          when :header
+            options = { :align => :left }
+            if self.current_column_number == 1
+              options[:class] = 'first'
+            elsif self.current_column_number == self.number_of_columns
+              options[:class] = 'last'
+            end
+
+            @template.haml_tag :th, options do
+              @template.haml_concat I18n.t(:'link.actions')
+            end
+          when :content
+            @template.haml_tag :td, :class => 'actions' do
+              @template.haml_tag :ul, :class => 'actions' do
+                @template.haml_concat @template.capture_haml(&block)
+              end
+            end
+        end
+      end
+
+    end #TableBuilder
+  end # module
+end # module

data/king_list/lib/king_list/list_helper.rb

@@ -0,0 +1,329 @@
+module KingList
+  # The List Helper aides in lists anddetail views by providing helpers for:
+  # tables, action icons, action buttons and action links, definition list helper
+  module ListHelper
+
+    # Build a definition list(dl/dt/dd) for a collection
+    # Usage examples:
+    #   - dl_for(client)
+    #   - dl_for(:client, my_client_object)
+    # === Example haml
+    #  - dl_for(current_object) do |f|
+    #    - f.show :first_name
+    #    - f.show :last_name
+    #
+    # =>    <dl>
+    #         <dt>Firstname</dt>
+    #         <dd>Otto</dd>
+    #         <dt>Lastname</dt>
+    #         <dd>Bismark</dd>
+    #       </dl>
+    #
+    # Parameters are like "form_for"
+    def dl_for(record_or_name, *args)
+      raise ArgumentError, "Missing block" unless block_given?
+
+      options = args.extract_options!
+      case record_or_name
+        when String, Symbol
+          object_name = record_or_name
+          object = args.first
+        else
+          object = record_or_name
+          object_name = ActionController::RecordIdentifier.singular_class_name(object)
+      end
+
+      haml_tag :dl, options do
+        yield KingList::Builder::Show.new(object_name, object, @template)
+      end
+    end
+
+    # Create a section
+    # A section is a group of related object information and
+    # generates a fieldset with optional legend
+    #
+    # === Example haml
+    #  - section :caption => _('legend.user.details'), :class => 'my_css_class' do
+    #    %p= "This is the content"
+    #
+    # => # <fieldset>
+    #        <legend>User Details</legend>
+    #        <p>This is the content</p>
+    #      </fieldset>
+    #
+    def section(options = {}, &block)
+      # Short form of usage
+      if options.is_a?(String)
+        caption = options
+        options = {}
+      end
+
+      caption ||= options.delete(:caption)
+
+      @template.haml_tag :fieldset, options do
+        @template.haml_tag :legend, caption unless caption.blank?
+        @template.haml_concat @template.capture_haml(&block)
+      end
+    end
+
+    # Create a div for form actions
+    def actions(options = {}, &block)
+      @template.haml_tag :div, options.merge(:class => 'form_actions') do
+        @template.haml_concat @template.capture_haml(&block)
+      end
+    end
+
+    # Build a table-tag for a collection
+    #
+    # Available option keys:
+    #     :sorting    => Enable/Disable sorting for ALL columns (default is true)
+    #
+    # === Usage example:
+    #
+    # Header linking for all, default
+    #   - table_for(@users) do |t, user|
+    #     - t.column :name  # with sorting
+    #     - t.column :email # with sorting
+    #
+    # Header linking for all, but exclude individual columns from sorting:
+    #  - table_for(@users)do |t, user|
+    #    - t.column :name, :sorting => false  # without sorting
+    #    - t.column :last_name                # with sorting
+    #
+    # NO header linking for all columns:
+    #  - table_for(@users, :sorting => false) do |t, user|
+    #    - t.column :name  # without sorting
+    #    - t.column :email # without sorting
+    #
+    # No header linking for all, but allow sorting for individual columns:
+    #  - table_for(@users, :sorting => false) do |t, user|
+    #    - t.column :name, :sorting => true # with sorting
+    #    - t.column :last_name              # without sorting
+    #
+    def table_for(collection, options={}, html_options={}, &block)
+      return if collection.nil? || collection.empty?
+
+      builder = KingList::Builder::Table.new(@template, collection)
+      # extract options
+      builder.sorting = options.delete(:sorting) != false # default => true
+
+      # First step: Yield the block just for counting the columns
+      builder.mode = :counter
+      builder.start_row(collection.first)
+      yield(builder, builder.current_record)
+
+      haml_tag :table, { :summary => '' }.merge(html_options) do
+        # Build header row
+        haml_tag :thead do
+          haml_tag :tr do
+            builder.mode = :header
+            builder.start_row(collection.first)
+            yield(builder, builder.current_record)
+          end
+        end
+
+        # TODO: Build footer here
+        # haml_tag :tfoot do
+        # end
+
+        haml_tag :tbody do
+          builder.mode = :content
+          # Build content row for each collection item
+          collection.each do |c|
+            tr_options = {}
+            # zebra styling
+            tr_options[:class] = @template.cycle('odd','even')
+
+            haml_tag :tr, tr_options do
+              builder.start_row(c)
+              yield(builder, builder.current_record)
+            end
+          end
+        end
+
+      end
+    end
+
+    # Show a list of options as ul / li list.
+    # Each actions li gets a special class so image replacement can be done via css
+    # ==== Example
+    #  - action_group do
+    #    = action_icon :edit, edit_object_path(client)
+    #    = action_icon :invoice_add, new_client_invoice_path(client), :title => 'New Invoice'
+    #     = action_text t(:'web_templates.new'), new_object_path,{},{ :class=>'btn_add'}
+    # # <ul class="actions">
+    #    <li class="button delete">
+    #     <a href="delete/id">delete</a>
+    def action_group(caption=nil, options={}, &block)
+      if caption && !caption.empty?
+        haml_tag :span, caption, { :class => 'caption' }
+      end
+
+      options[:class] ||= 'actions'
+      haml_tag :ul, options do
+        haml_concat capture_haml(&block)
+      end
+    end
+
+    # Renders a <li> with a link shown as icon
+    # The link text is hidden via css image replacement and only an icon is shown
+    #
+    # ==== Example
+    #   action_icon :show, show_user(user), :title => "Show User details"
+    # => <li class="show"><a href="/users/show" title="Show User details"><span>show</span></a></li>
+    # ==== Parameter
+    # name<String>:: The name of the action which is taken in the translated title,
+    # and li class (if no custom class is present in li_options )
+    # li_options<Hash{Symbol=>String}>:: Options for the li-element
+    # link_options<Hash>:: Options passed on to rails link_to method  #
+    # html_options<Hash>:: Options passed on to rails link_to method
+    # ==== Options li_options
+    # :title - the html title tag for the li
+    # :class - the html class tag for the li
+    def action_icon(name, link_options={}, li_options={}, html_options={})
+      li_options[:title] ||= case name
+        # Some known names with their titles
+        when :edit        then t(:'link.edit')
+        when :pdf         then t(:'link.pdf')
+        when :show        then t(:'link.show')
+        when :delete      then t(:'link.delete')
+        when :copy        then t(:'link.copy')
+        when :comment     then t(:'link.comment')
+        when :send_email  then t(:'link.send_email')
+      end
+      (li_options[:class] ||= '') << " icon #{name}"
+
+      action :icon, name, link_options, li_options, html_options
+    end
+
+    # Renders a <li> with a link shown as text
+    # You can set html options for both the li and the a tag
+    #
+    #===Example haml
+    #   action_text _('link.user.edit'), edit_object_path
+    #   action_text _('link.user.edit'), edit_object_path, {li html options}, {a html options :class=>'supercssclass'}
+    #
+    #   =>   <li>
+    #         <a href="/users/edit/12">
+    #           link.user.edit
+    #         </a>
+    #        </li>
+    #
+    def action_text(title, link_options, li_options={}, html_options={})
+      # Prepare the css-class for the <li>
+      li_options[:class] ||= ''
+      li_options[:class] << ' active' if li_options.delete(:active)
+
+      #kill class attribute if still empty
+      li_options.delete(:class) if li_options[:class].empty?
+      action :text, title, link_options, li_options, html_options
+    end
+
+    # Renders a <li> with a button that will submit a form to a given url.
+    # This allows to make POST/PUT/DELETE request instead of using a link which triggers a GET.
+    #
+    # The button tags name attribute will be set to the <tt>name</tt> paramter followed by
+    # either the <tt>:id</tt> url_for_options value or a <tt>:number</tt> option either is
+    # available.
+    #
+    # ==== Parameters
+    # fieldname<String>:: the name attribute of the hidden form field f.ex. 'status' or 'invoice[status]'
+    # options<Hash>:: a couple of options explained further on
+    #
+    # ==== Options
+    #  :method<Symbol>::form request method: :post / :put / :delete
+    #  :url<String>:: The url the form is submitted to
+    #  :title<String>::Button title and text
+    #  :value<String>::the hidden field value
+    #  :class<String>::button class
+    #
+    # ==== Example
+    #   = action_button 'order_status', {:value=>'open', :title=> "Change Status to open", :method => :put}
+    #
+    #
+    # ==== Returns
+    #   <form>
+    #     <div>
+    #       <input type="hidden" value="put" name="_method"/>
+    #       <input type="hidden" value="939f3c1dc225bcaa2e5c2bd88910537901dc19d6" name="authenticity_token"/>
+    #       <input type="hidden" value="open" name="order_status"/>
+    #        <button type='submit' class="some_class" title="Change Status to open">Change Status to open</button>
+    #     </div>
+    #   </form>
+    #
+    def action_button(fieldname, options)
+      @template.capture_haml do
+        haml_tag :li, :class=>'form_btn' do
+          haml_concat mini_action_form(fieldname, options)
+        end
+      end
+    end
+    def action_link(fieldname, options)
+      haml_concat mini_action_form(fieldname, options)
+    end
+
+    def mini_action_form(fieldname, options)
+      method_tag = ''
+      if (method = options.delete(:method)) && %w{put delete}.include?(method.to_s)
+        method_tag = tag('input', :type => 'hidden', :name => '_method', :value => method.to_s)
+      end
+
+      form_method = method.to_s == 'get' ? 'get' : 'post'
+
+      request_token_tag = ''
+      if form_method == 'post' && protect_against_forgery?
+        request_token_tag = tag(:input, :type => "hidden", :name => request_forgery_protection_token.to_s, :value => form_authenticity_token)
+      end
+
+      hidden_tag = ''
+      hidden_tag = tag(:input, :type => "hidden", :name =>fieldname, :value => options[:value]) unless options[:value].blank?
+
+      "<form method=\"#{form_method}\" action=\"#{escape_once options[:url]}\"><div>" +
+            method_tag +
+            request_token_tag +
+            hidden_tag +
+            "<button type='submit' name='submit' title='#{options[:title]}' class='#{options[:class]}'><span>#{options[:title]}</span></button>" +
+         "</div></form>"
+    end
+
+    # Renders a <ol> for a given collection and yields the block for every item
+    # Options:
+    #   :descending: if true, numbering is reversed (defaults to false)
+    def ordered_list_for(collection, options={}, &block)
+      if collection.nil? || collection.empty?
+        haml_tag :p, _('list.empty')
+        return
+      end
+
+      descending = options.delete(:descending)
+
+      haml_tag :ol, options do
+        collection.each_with_index do |c,i|
+          li_options = {}
+          li_options[:class] = @template.cycle('odd','even')
+          li_options[:value] = collection.length - i if descending
+          haml_tag :li, li_options do
+            yield(c)
+          end
+        end
+      end
+    end
+
+  private
+
+    # Internal method used by action_text, action_button and action_icon
+    # Directly returns a haml string into the template
+    def action(kind, name_or_title, link_options, li_options={}, html_options={})
+      @template.capture_haml do
+        haml_tag :li, li_options do
+          case kind
+            when :icon   then haml_concat link_to('', link_options, html_options)
+            when :text   then haml_concat link_to(name_or_title, link_options, html_options)
+            when :button then haml_concat button_to(name_or_title, link_options)
+          end
+        end
+      end
+    end
+
+  end #ListHelper
+end#module