rango 0.0.3

data/lib/rango/helpers/README

@@ -0,0 +1,179 @@
+merb-helpers
+=================
+
+A plugin for the Rango Web framework that provides different view helpers.
+
+To use this plugin in merb in your app
+
+config/dependencies.rb
+
+#...
+
+dependency "merb-helpers"
+
+#...
+
+# TODO: describe date_time_helpers, form_helpers, tag_helpers
+
+
+form_helpers
+------------
+
+* +delete_button+. If you want to delete an object, you should call the delete method on the object's controller.
+You should not use a simple link to your action, instead you should make a DELETE request.
+To help you doing that, you can use the delete_button method as follows:
+
+    <%= delete_button(@comment) %>
+
+The delete_button helper has many options, first thing, you can pass an object or an url:
+
+    <%= delete_button(url(:comment, @comment)) %>
+
+This helper creates a form with a submit button.
+You can pass many arguments to the delete_button helper. The first thing you might want to do is to change the
+default button text.
+
+    <%= delete_button(@comment), "Remove this comment by #{@comment.author.name}" %>
+
+You can also pass the usual helper params to specify a class to use for instance:
+
+    <%= delete_button(@comment, nil, :class => 'custom-class') %>
+
+See usage in specs: spec/fixture/app/views/delete_button_specs
+
+numeric helpers
+---------------
+
+Numeric helpers extend numeric instances, in lay terms: numbers.
+
+* +minutes_to_hours+ converts a +numeric+ value representing minutes into a string representing an hour value
+
+    315.minutes_to_hours # => "05:15"
+
+* +two_digits+ formats a +number+ into a two digit string. Basically it prepends an integer to a 2 digits string.
+
+    3.two_digits # => "03"
+
+* +with_delimiter+, this method formats a number with grouped thousands
+
+    12345678.with_delimiter # => "12,345,678"
+
+
+* +with_precison+, this method formats a number with a level of precision
+
+    111.2345.with_precision # => "111.235"
+
+* +to_currency, this method formats a number into a currency value using a delimited and a set precision
+
+    1234567890.506.to_currency # => "$1,234,567,890.51"
+
+(For usage example look at spec/numeric_exlib.rb)
+
+
+Overwriting the default formating options:
+
+One can overwrite the default settings by passing the name or of the format used and a hash representing the settings to overwrite.
+
+Each method mentioned above has some format settings you can overwrite:
+
+* +with_delimiter+
+  * :delimiter - Overwrites the thousands delimiter.
+  * :separator - Overwrites the separator between the units.
+
+* +with_precision+
+  * :precision - Overwrites the level of precision
+  * :separator - Overwrites the separator between the units
+  * :delimiter - Overwrites the thousands delimiter
+
+* +with_currency+
+  * :precision - Sets the level of precision
+  * :unit - Sets the denomination of the currency
+  * :format - Sets the format of the output string (defaults to "%u%n"). The field types are:
+    * %u The currency unit
+    * %n The number
+
+Usage example:
+
+    1234567890.506.to_currency(:default, :unit => '£') # => "£1,234,567,890.51"
+
+merb_helpers comes with a very limited set of formats you can use, here is an example:
+
+    1234567890.50.to_currency(:uk) # => "&pound;1,234,567,890.50"
+
+Formats are just a hash of settings used by the plugin, here is the default format:
+
+    :us => {
+      :number => {
+        :precision => 3,
+        :delimiter => ',',
+        :separator => '.'
+      },
+      :currency => {
+        :unit => '$',
+        :format => '%u%n',
+        :precision => 2
+      }
+    }
+
+If you wish to add a new format you can easily do that as follows:
+
+    custom_format_to_add = {  :custom_name => {
+                                :number => {
+                                  :precision => 3,
+                                  :delimiter => ',',
+                                  :separator => '.'
+                                },
+                                :currency => {
+                                  :unit => 'Rangoollars',
+                                  :format => '%n %u',
+                                  :precision => 2
+                                }
+                              }
+                          }
+
+    Numeric::Transformer.add_format(custom_format_to_add)
+
+You can then call the format like that:
+
+    1234567890.to_currency(:custom_name) # => "1,234,567,890.00 Rangoollars"
+
+After adding a custom format, you can set it as the default format:
+
+    Numeric::Transformer.change_default_format(:custom_name)
+
+You can set this things up in your before/after app load block in the config/init.rb file.
+
+
+Formating a Date or Time instance
+---------------
+
+Usage examples: spec/merb_helpers_date_time_spec.rb
+
+    Time.now.formatted(:db)   # => "2008-09-21 02:07:31"
+    Time.now.formatted(:long) # => "September 21, 2008 02:08"
+
+You can also add your own format:
+
+    Date.add_format(:matt, "%H:%M:%S %Y-%m-%d")
+
+And use is as a default format:
+
+  Time.now.formatted(:matt)    # => "02:09:18 2008-09-21"
+
+
+
+Representation of time difference
+-------------------
+
+Usage examples: spec/merb_helpers_date_time_spec.rb
+
+* Relative time:
+
+Let's imagine that we are the June 1st 2007 at 11am UTC
+
+
+    relative_date(Time.now.utc)       # => "today"
+    relative_date(1.day.ago.utc)      # => 'yesterday'
+    relative_date(1.day.from_now.utc) # => 'tomorrow'
+    relative_date(Time.utc(2005, 11, 15)) # => 'Nov 15th, 2005' (date with the year since it's not this year)
+    relative_date(Time.utc(2007, 11, 15)) # => 'Nov 15th' (date without the year this the passed date is this year)

data/lib/rango/helpers/assets.rb

@@ -0,0 +1,29 @@
+# coding: utf-8
+
+class Rango
+  module Helpers
+    # stolen from pupu (but it's OK, it's my code)
+    # @since 0.0.2
+    def javascript(basename)
+      path = Path.new(File.join(Project.settings.media_root, "javascripts", "#{basename}.js"))
+      tag :script, src: path.url, type: "text/javascript"
+    end
+
+    # @since 0.0.2
+    def stylesheet(basename, attrs = Hash.new)
+      path = Path.new(File.join(Project.settings.media_root, basename))
+      default = {href: path.url, media: 'screen', rel: 'stylesheet', type: 'text/css'}
+      single_tag :link, default.merge(attrs)
+    end
+
+    # @since 0.0.2
+    def javascripts(*names)
+      names.map { |name| self.javascript(name) }.join("\n")
+    end
+
+    # @since 0.0.2
+    def stylesheets(*names)
+      names.map { |name| self.stylesheet(name) }.join("\n")
+    end
+  end
+end

data/lib/rango/helpers/general.rb

@@ -0,0 +1,41 @@
+# coding: utf-8
+require "uri"
+
+class Rango
+  module Helpers
+    # @since 0.0.1
+    def copyright(from)
+      now = Time.now.year
+      now.eql?(from) ? now : "#{from} - #{now}"
+    end
+
+    # @since 0.0.2
+    def link_to(name, url, options = Hash.new)
+      default = {href: URI.escape(url), title: name.to_s.gsub(/'/, ''')}
+      tag :a, name, default.merge(options)
+    end
+
+    # @since 0.0.2
+    def link_item(name, url)
+      tag :li, link_to(name, url)
+    end
+
+    # @since 0.0.2
+    # mail_to "joe@example.com"
+    # => "<a href='mailto:joe@example.com'>joe@example.com</a>"
+    # mail_to "joe@example.com", "Title"
+    # => "<a href='mailto:joe@example.com'>Title</a>"
+    def mail_to(mail, text = mail)
+      mail.gsub!("@" "&#x40;")
+      tag :a, text, href: "mailto:#{mail}"
+    end
+
+    # @since 0.0.2
+    def error_messages_for(model_instance)
+      tag :ul do
+        messages = model_instance.errors.full_messages
+        messages.map { |message| tag :li, message }
+      end
+    end
+  end
+end

data/lib/rango/helpers/merb-helpers.rb

@@ -0,0 +1,40 @@
+# coding: utf-8
+
+class Rango
+
+  module Helpers
+
+    @@helpers_dir   = File.dirname(__FILE__) / 'merb-helpers'
+    @@helpers_files = Dir["#{@@helpers_dir}/*_helpers.rb"].collect {|h| h.match(/\/(\w+)\.rb/)[1]}
+
+    def self.load
+      require @@helpers_dir + '/time_dsl'
+      require @@helpers_dir + '/core_ext'
+      require @@helpers_dir + '/core_ext/numeric'
+
+      # if Rango::Plugins.config[:merb_helpers]
+      #   config = Rango::Plugins.config[:merb_helpers]
+      #
+      #   if config[:include] && !config[:include].empty?
+      #     load_helpers(config[:include])
+      #   else
+      #     # This is in case someone defines an entry in the config,
+      #     # but doesn't put in a with or without option
+      #     load_helpers
+      #   end
+      #
+      # else
+        load_helpers
+      # end
+    end
+
+    # Load only specific helpers instead of loading all the helpers
+    def self.load_helpers(helpers = @@helpers_files)
+      helpers.each {|helper| Kernel.load(File.join(@@helpers_dir, "#{helper}.rb") )} # using load here allows specs to work
+    end
+
+  end
+
+end
+
+Rango::Helpers.load

data/lib/rango/helpers/merb-helpers/core_ext.rb

@@ -0,0 +1,58 @@
+# coding: utf-8
+
+require "date"
+require File.dirname(__FILE__) + '/date_time_formatting'
+class Date
+  include DateAndTimeFormatting
+
+  # Converts a Date instance to a Time, where the time is set to the beginning of the day.
+  # The timezone can be either :local or :utc (default :utc).
+  #
+  # ==== Examples:
+  #   date = Date.new(2007, 11, 10)
+  #   date.to_s                      # => 2007-11-10
+  #
+  #   date.to_time                   # => Sat Nov 10 00:00:00 UTC 2007
+  #   date.to_time(:utc)             # => Sat Nov 10 00:00:00 UTC 2007
+  #   date.to_time(:local)           # => Sat Nov 10 00:00:00 -0800 2007
+  #
+  def to_time(form = :utc)
+    ::Time.send("#{form}", year, month, day)
+  end
+
+  def to_date; self; end
+
+  def formatted(format=:default)
+    format = Date.formats[format]
+    if format.nil?
+      self.to_s
+    else
+      self.strftime(format)
+    end
+  end
+
+end
+
+class Time
+  include DateAndTimeFormatting
+
+  # Ruby 1.8-cvs and 1.9 define private Time#to_date
+  %w(to_date to_datetime).each do |method|
+    public method if private_instance_methods.include?(method)
+  end
+
+  def to_time; self; end
+end
+
+# Truncates a string to the given length and appends the given suffix if the string is, in fact, truncated.
+#
+# ==== Examples:
+#  "This is a long string right here".truncate(10, "...")  #=> "This is..."
+
+class String
+  def truncate(length = 30, truncate_string = "...")
+    return self unless self.length > length
+    length = length - truncate_string.split(//).length
+    self[0...length] + truncate_string
+  end
+end

data/lib/rango/helpers/merb-helpers/core_ext/numeric.rb

@@ -0,0 +1,388 @@
+# coding: utf-8
+
+class Numeric
+  module Transformer
+
+    # known formats to use with the app
+    # users can add their own formats by using Numeric::Transformer.add_format(:format_name => {})
+
+    @formats ={
+      :us => {
+        :number => {
+          :precision => 3,
+          :delimiter => ',',
+          :separator => '.'
+        },
+        :currency => {
+          :unit => '$',
+          :format => '%u%n',
+          :precision => 2
+        }
+      },
+      :uk => {
+        :number => {
+        :precision => 3,
+        :delimiter => ',',
+        :separator => '.'
+        },
+        :currency => {
+          :unit => '£',
+          :format => '%u%n',
+          :precision => 2
+        }
+      },
+      :au => {
+        :number => {
+        :precision => 3,
+        :delimiter => ',',
+        :separator => '.'
+        },
+        :currency => {
+          :unit => '$;',
+          :format => '%u%n',
+          :precision => 2
+        }
+      },
+      :fr => {
+        :number => {
+        :precision => 3,
+        :delimiter => ' ',
+        :separator => ','
+        },
+        :currency => {
+          :unit => '€',
+          :format => '%n%u',
+          :precision => 2
+        }
+      },
+      :ru => {
+          :number => {
+             :precision => 2,
+             :delimiter => ' ',
+             :separator => ','
+             },
+             :currency => {
+               :unit => 'р.',
+               :format => '%n %u',
+               :precision => 2
+             }
+           }
+    }
+
+    # accessor for @formats
+    #---
+    # @private
+    def self.formats
+      @formats
+    end
+
+    @default_format = @formats[:us]
+
+
+    # Accessor for the default format in use
+    #
+    #---
+    # @public
+    def self.default_format
+      @default_format
+    end
+
+
+    # Changes the default format to use when transforming a +Numeric+ instance
+    #
+    # ==== Parameters
+    # format_code <Symbol>:: format name to use as the new default format
+    #
+    # ==== Returns
+    # Hash:: a hash representing the default format
+    #
+    #---
+    # @public
+    def self.change_default_format(format_code)
+      @default_format = (formats[format_code] || default_format)
+    end
+
+
+    # Adds a new format to the existing transforming formats
+    #
+    # ==== Parameters
+    # format <Hash>:: format defining how to transform numeric values
+    #
+    # ==== Examples
+    #
+    #
+    #---
+    # @public
+    def self.add_format(format)
+      formats.merge!(format)
+      formats[format]
+    end
+
+
+    # Formats a +number+ with grouped thousands using +delimiter+ (e.g., 12,324). You can
+    # pass another format to format the number differently.
+    #
+    #
+    # ==== Parameters
+    # format_name<Symbol>:: name of the format to use
+    # options<Hash>:: options which will overwrite the used format
+    #
+    # ==== Returns
+    # String:: a string representing the delimited number
+    #
+    # ==== Options
+    # :delimiter - Overwrites the thousands delimiter.
+    # :separator - Overwrites the separator between the units.
+    #
+    # ==== Examples
+    # with_delimiter(12345678) # => 12,345,678
+    # with_delimiter(12345678.05) # => 12,345,678.05
+    # with_delimiter(12345678, :FR) # => 12.345.678
+    # with_delimiter(12345678, :US) # => 12,345,678
+    #
+    #---
+    # @private
+    def self.with_delimiter(number, format_name = nil, options = {})
+
+      format = (formats[format_name] || default_format)[:number].merge(options)
+
+      begin
+        parts = number.to_s.split('.')
+        parts[0].gsub!(/(\d)(?=(\d\d\d)+(?!\d))/, "\\1#{format[:delimiter]}")
+        parts.join(format[:separator])
+      rescue
+        number
+      end
+    end
+
+    # Formats a +number+ with a level of <tt>:precision</tt> (e.g., 112.32 has a precision of 2).
+    # You can pass another format to use and even overwrite the format's options.
+    #
+    #
+    # ==== Parameters
+    # format_name<Symbol>:: name of the format to use
+    # options<Hash>:: options which will overwrite the used format
+    #
+    # ==== Returns
+    # String:: a string representing the delimited number
+    #
+    # ==== Options
+    # :precision - Overwrites the level of precision
+    # :separator - Overwrites the separator between the units
+    # :delimiter - Overwrites the thousands delimiter
+    #
+    # ==== Examples
+    # with_precision(111.2345)                       # => 111.235
+    # with_precision(111.2345, :UK, :precision => 1) # => "111.2"
+    # with_precision(1234.567, :US, :precision => 1, :separator => ',', :delimiter => '-') # => "1-234,6"
+    #
+    #---
+    # @private
+    def self.with_precision(number, format_name = nil, options={})
+
+      format = (formats[format_name] || default_format)[:number].merge(options)
+
+      begin
+        rounded_number = (Float(number) * (10 ** format[:precision])).round.to_f / 10 ** format[:precision]
+        with_delimiter("%01.#{format[:precision]}f" % rounded_number, format_name, :delimiter => format[:delimiter], :separator => format[:separator])
+      rescue
+        number
+      end
+    end
+
+
+    # Formats a +number+ into a currency string (e.g., $13.65). You can specify a format to use
+    # and even overwrite some of the format options.
+    #
+    # ==== Parameters
+    # number<Numeric>:: Numeric value to convert
+    # format_name<Symbol>:: name of the format to use
+    # options<Hash>:: options which will overwrite the used format
+    #
+    # ==== Returns
+    # String:: a string representing the number converted in currency
+    #
+    # ==== Options
+    # :precision - Sets the level of precision
+    # :unit - Sets the denomination of the currency
+    # :format - Sets the format of the output string (defaults to "%u%n"). The field types are:
+    #
+    # %u The currency unit
+    # %n The number
+    #
+    # ==== Examples
+    # to_currency(1234567890.506, :US, :precision => 1)  # => "$1,234,567,890.5"
+    # to_currency(1234567890.516, :FR)                   # =>"1 234 567 890,52€"
+    # to_currency(1234567890.516, :US, :unit => "€")     # =>"€1,234,567,890.52"
+    # to_currency(1234567890.506, :US, :precision => 3, :unit => "€") # => "€1,234,567,890.506"
+    # to_currency(1234567890.506, :AU, :unit => "$AUD", :format => '%n %u') # => "1,234,567,890.51 $AUD"
+    #
+    #---
+    # @private
+    def self.to_currency(number, format_name = nil, options = {})
+
+      format = (formats[format_name] || default_format)[:currency].merge(options)
+
+      begin
+        format[:format].gsub(/%n/, with_precision(number,
+                                      format_name, :precision  => format[:precision]) ).gsub(/%u/, format[:unit])
+      rescue
+        number
+      end
+    end
+
+
+    # Formats a +number+ into a two digit string. Basically it prepends an integer to a 2 digits string.
+    #
+    # ==== Parameters
+    # number<Numeric>:: Numeric value to convert
+    #
+    # ==== Returns
+    # String:: a string representing the number converted into a 2 digits string.
+    #
+    # ==== Examples
+    # two_digits(5-3) # => "02"
+    #
+    #---
+    # @private
+    def self.two_digits(number)
+      (0..9).include?(number) ? "0#{number}" : number.to_s
+    end
+
+    # Converts a +numeric+ value representing minutes into a string representing an hour value
+    #
+    # ==== Parameters
+    # number<Numeric>:: Numeric value representing minutes to convert in hours
+    #
+    # ==== Returns
+    # String:: a string representing the numeric value converted in hours
+    #
+    # ==== Examples
+    # minutes_to_hours(315) => "05:15"
+    #
+    #---
+    # @private
+    def self.minutes_to_hours(minutes)
+      hours = (minutes/60).ceil
+      minutes = (minutes - (hours * 60)).to_i
+      "#{two_digits(hours)}:#{two_digits(minutes)}"
+    end
+
+  end #of Numeric::Transformer
+
+  # Formats with with grouped thousands using +delimiter+ (e.g., 12,324). You can
+  # pass another format to format the number differently.
+  #
+  #
+  # ==== Parameters
+  # format_name<Symbol>:: name of the format to use
+  # options<Hash>:: options which will overwrite the used format
+  #
+  # ==== Returns
+  # String:: a string representing the delimited number
+  #
+  # ==== Options
+  # :delimiter - Overwrites the thousands delimiter.
+  # :separator - Overwrites the separator between the units.
+  #
+  # ==== Examples
+  # 12345678.with_delimiter      # => 12,345,678
+  # 12345678.05.with_delimiter   # => 12,345,678.05
+  # 12345678.with_delimiter(:FR) # => 12.345.678
+  # 12345678.with_delimiter(:US) # => 12,345,678
+  #
+  #---
+  # @public
+  def with_delimiter(format_name = nil, options = {})
+    Transformer.with_delimiter(self, format_name, options)
+  end
+
+  # Formats with a level of <tt>:precision</tt> (e.g., 112.32 has a precision of 2).
+  # You can pass another format to use and even overwrite the format's options.
+  #
+  #
+  # ==== Parameters
+  # format_name<Symbol>:: name of the format to use
+  # options<Hash>:: options which will overwrite the used format
+  #
+  # ==== Returns
+  # String:: a string representing the delimited number
+  #
+  # ==== Options
+  # :precision - Overwrites the level of precision
+  # :separator - Overwrites the separator between the units
+  # :delimiter - Overwrites the thousands delimiter
+  #
+  # ==== Examples
+  # 111.2345.with_precision                       # => 111.235
+  # 111.2345.with_precision(:UK, :precision => 1) # => "111.2"
+  # 1234.567.with_precision(:US, :precision => 1, :separator => ',', :delimiter => '-') # => "1-234,6"
+  #
+  #---
+  # @public
+  def with_precision(format_name = nil, options = {})
+    Transformer.with_precision(self, format_name, options)
+  end
+
+  # Formats into a currency string (e.g., $13.65). You can specify a format to use
+  # and even overwrite some of the format options.
+  #
+  # ==== Parameters
+  # format_name<Symbol>:: name of the format to use
+  # options<Hash>:: options which will overwrite the used format
+  #
+  # ==== Returns
+  # String:: a string representing the number converted in currency
+  #
+  # ==== Options
+  # :precision - Sets the level of precision
+  # :unit - Sets the denomination of the currency
+  # :format - Sets the format of the output string (defaults to "%u%n"). The field types are:
+  #
+  # %u The currency unit
+  # %n The number
+  #
+  # ==== Examples
+  # 1234567890.506.to_currency(:US)                   # => "$1,234,567,890.51"
+  # 1234567890.506.to_currency(:US, :precision => 1)  # => "$1,234,567,890.5"
+  # 1234567890.516.to_currency(:FR)                   # =>"1 234 567 890,52€"
+  # 1234567890.516.to_currency(:US, :unit => "€")     # =>"€1,234,567,890.52"
+  # 1234567890.506.to_currency(:US, :precision => 3, :unit => "€") # => "€1,234,567,890.506"
+  # 1234567890.506.to_currency(:AU, :unit => "$AUD", :format => '%n %u') # => "1,234,567,890.51 $AUD"
+  #---
+  # @public
+  def to_currency(format_name = nil, options = {})
+    Transformer.to_currency(self, format_name, options)
+  end
+
+  # Formats a +number+ into a two digit string. Basically it prepends an integer to a 2 digits string.
+  #
+  # ==== Returns
+  # String:: a string representing the number converted into a 2 digits string.
+  #
+  # ==== Examples
+  # (5-3).two_digits # => "02"
+  #
+  #---
+  # @public
+  def two_digits
+    Transformer.two_digits(self)
+  end
+
+  # Converts a +numeric+ value representing minutes into a string representing an hour value
+  #
+  # ==== Parameters
+  # number<Numeric>:: Numeric value representing minutes to convert in hours
+  #
+  # ==== Returns
+  # String:: a string representing the numeric value converted in hours
+  #
+  # ==== Examples
+  # 315.minutes_to_hours => "05:15"
+  #
+  #---
+  # @public
+  def minutes_to_hours
+    Transformer.minutes_to_hours(self)
+  end
+end