local_time 0.3.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 84f0f9773b1e9bfac34c2e579af56d6c784a8d23
-  data.tar.gz: a1606c79f356e6e09b67f5b2adca382e38366a9f
+  metadata.gz: 0d42dfef630d09374cd897d5a842566191ff07cd
+  data.tar.gz: 671f048d37ba09ade8df1e01dd8c4bb36f5ccfab
 SHA512:
-  metadata.gz: 88db2bd3c1a77268ef0e8a59a18c81bed59c9f3b837bd3f9d2e555862228ded216dc7a2cf8e2d19a1c06fc262ada3ca319e4b2538eeae3ea826c3ecbe65c113f
-  data.tar.gz: 71e7a980c10839bc5e81dda212a9a99f1dd9a5ec68cbd3a082e754126de0dfccad334e3efc28bb01a1c416b71c31bc7bdece4a9c848a2de60e7d771513de9121
+  metadata.gz: 6209af737d470ff029db6233ca5f30e6840e8e74c40db30aca1a8ad9a592dbd705ea2159ff16eb37118946dee8d6f6db1fbfd69d6f129d30b9aab1c3f3a93b18
+  data.tar.gz: 26786c11ec81af062927263f55e5f4103532dbdc871d535e0e272a5c95b8a94f6e8979d165154330c3bc2cc0b93ac202f4202546f04258012e75b82d4c1d8ce1

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright 2014 Javan Makhmali
+Copyright 2014 Javan Makhmali, Basecamp
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,11 +1,16 @@
-Local Time is a Rails engine with helpers and JavaScript for displaying times and dates to users in their local time. The helpers render a `<time>` element in UTC and the JavaScript swoops in to convert and format. Because the `<time>` element is only rendered in one timezone, it is ideal for caching.
+Local Time is a Rails engine with helpers and JavaScript for displaying times and dates to users in their local time. The helpers render a `<time>` element and the JavaScript swoops in to convert and format. The helper output is ideal for caching since it's always in UTC time.
 
 ---
 
 ####Example
 
+```ruby
+> comment.created_at
+"Wed, 27 Nov 2013 18:43:22 EST -0500"
+```
+
 ```erb
-<%= local_time(comment.created_at) # comment.created_at => Wed, 27 Nov 2013 18:43:22 EST -0500 %>
+<%= local_time(comment.created_at) %>
 ```
 
 Renders:
@@ -22,6 +27,7 @@ When the DOM loads, the content is immediately replaced with a local, formatted
 <time data-format="%B %e, %Y %l:%M%P"
       data-local="time"
       datetime="2013-11-27T23:43:22Z"
+      title="November 27, 2013 6:43pm EDT"
       data-localized="true">November 27, 2013 6:43pm</time>
 ```
 
@@ -30,21 +36,36 @@ When the DOM loads, the content is immediately replaced with a local, formatted
 #### Time and date helpers
 
 ```erb
-Pass a time and an optional strftime format (default format shown here)
-<%= local_time(time, format: '%B %e, %Y %l:%M%P') %>
+<%= local_time(time) %>
+```
+
+Format with a strftime string (default format shown here)
+
+```erb
+<%= local_time(time, '%B %e, %Y %l:%M%P') %>
+```
+
+Alias for `local_time` with a month-formatted default
+
+```erb
+<%= local_date(time, '%B %e, %Y') %>
+```
+
+To set attributes on the time tag, pass a hash as the second argument with a `:format` key and your attributes.
 
-Alias for local_time with a month-formatted default
-<%= local_date(time, format: '%B %e, %Y') %>
+```erb
+<%= local_time(time, format: '%B %e, %Y %l:%M%P', class: 'my-time') %>
 ```
 
 To use a strftime format already defined in your app, pass a symbol as the format.
+
 ```erb
-<%= local_time(date, format: :long) %>
+<%= local_time(date, :long) %>
 ```
 
 `I18n.t("time.formats.#{format}")`, `I18n.t("date.formats.#{format}")`, `Time::DATE_FORMATS[format]`, and `Date::DATE_FORMATS[format]` will be scanned (in that order) for your format.
 
-Note: The included strftime JavaScript implementation is not 100% complete. It supports the following directives: `%a %A %b %B %c %d %e %H %I %l %m %M %p %P %S %w %y %Y`
+Note: The included strftime JavaScript implementation is not 100% complete. It supports the following directives: `%a %A %b %B %c %d %e %H %I %l %m %M %p %P %S %w %y %Y %Z`
 
 #### Time ago helper
 
@@ -52,7 +73,9 @@ Note: The included strftime JavaScript implementation is not 100% complete. It s
 <%= local_time_ago(time) %>
 ```
 
-Displays the relative amount of time passed. With age, the descriptions transition from specific quantities to general dates. The `<time>` elements are updated every 60 seconds. Examples (in quotes):
+Displays the relative amount of time passed. With age, the descriptions transition from {quantity of seconds, minutes, or hours} to {date + time} to {date}. The `<time>` elements are updated every 60 seconds.
+
+Examples (in quotes):
 
 * Recent: "a second ago", "32 seconds ago", "an hour ago", "14 hours ago"
 * Yesterday: "yesterday at 5:22pm"
@@ -60,6 +83,22 @@ Displays the relative amount of time passed. With age, the descriptions transiti
 * This year: "on Nov 17"
 * Last year: "on Jan 31, 2012"
 
+#### Relative time helper
+
+Preset time and date formats that vary with age. The available types are `date`, `time-ago`, `time-or-date`, and `weekday`. Like the `local_time` helper, `:type` can be passed a string or in an options hash.
+
+```erb
+<%= local_relative_time(time, 'weekday') %>
+<%= local_relative_time(time, type: 'time-or-date') %>
+```
+
+**Available `:type` options**
+
+* `date` Inlcudes the year unless it's current. "Apr 11" or "Apr 11, 2013"
+* `time-ago` See above. `local_time_ago` calls `local_relative_time` with this `:type` option.
+* `time-or-date` Displays the time if it's todday. Displays time otherwise. "3:26pm" or "Apr 11"
+* `weekday` Displays "Today", "Yesterday", or the weekday (e.g. Wednesday) if the time is within a week of today.
+
 #### Installation
 
 1. Add `gem 'local_time'` to your Gemfile.
@@ -72,18 +111,29 @@ The included JavaScript does not depend on any frameworks or libraries, and list
 
 #### JavaScript API
 
-`strftime` and `relativeTimeAgo` are available via the global `LocalTime` object.
+`relativeDate`, `relativeTimeAgo`, `relativeTimeOrDate`, `relativeWeekday`, `run`, and `strftime` methods are available on the global `LocalTime` object.
 
 ```js
-> LocalTime.strftime(new Date, "%B %e, %Y %l:%M%P")
-"February 9, 2014 12:55pm"
-
 > LocalTime.relativeTimeAgo(new Date(new Date - 60 * 1000 * 5))
 "5 minutes ago"
+
+// Process <time> tags. Equivalent to dispatching a "time:elapse" Event.
+> LocalTime.run()
+
+> LocalTime.strftime(new Date, "%B %e, %Y %l:%M%P")
+"February 9, 2014 12:55pm"
 ```
 
 #### Version History
 
+**1.0.0** (April 12, 2014)
+
+* Added `local_relative_time` helper with several built in types
+* Allow `:format` (and `:type`) option as a bare string or value in hash
+* Added `relativeDate`, `relativeTimeOrDate`, `relativeWeekday` and `run` to the API
+* Dropped ineffective `popstate` event listener
+* Now in use at [Basecamp](https://basecamp.com/)
+
 **0.3.0** (February 9, 2014)
 
 * Allow :format option lookup in I18n or DATE_FORMATS hashes [Paul Dobbins]

data/app/assets/javascripts/local_time.js.coffee

@@ -30,7 +30,7 @@ strftime = (time, formatString) ->
   minute = time.getMinutes()
   second = time.getSeconds()
 
-  formatString.replace /%([%aAbBcdeHIlmMpPSwyY])/g, ([match, modifier]) ->
+  formatString.replace /%([%aAbBcdeHIlmMpPSwyYZ])/g, ([match, modifier]) ->
     switch modifier
       when '%' then '%'
       when 'a' then weekdays[day].slice 0, 3
@@ -51,6 +51,7 @@ strftime = (time, formatString) ->
       when 'w' then day
       when 'y' then pad year % 100
       when 'Y' then year
+      when 'Z' then time.toString().match(/\((\w+)\)$/)?[1] ? ''
 
 
 class CalendarDate
@@ -67,6 +68,16 @@ class CalendarDate
     @year = @date.getUTCFullYear()
     @month = @date.getUTCMonth() + 1
     @day = @date.getUTCDate()
+    @value = @date.getTime()
+
+  equals: (calendarDate) ->
+    calendarDate?.value is @value
+
+  is: (calendarDate) ->
+    @equals calendarDate
+
+  isToday: ->
+    @is @constructor.today()
 
   occursOnSameYearAs: (date) ->
     @year is date?.year
@@ -82,7 +93,7 @@ class CalendarDate
     @constructor.today().daysSince @
 
 
-class RelativeTimeAgo
+class RelativeTime
   constructor: (@date) ->
     @calendarDate = CalendarDate.fromDate @date
 
@@ -100,6 +111,12 @@ class RelativeTimeAgo
     else
       "on #{@formatDate()}"
 
+  toTimeOrDateString: ->
+    if @calendarDate.isToday()
+      @formatTime()
+    else
+      @formatDate()
+
   timeElapsed: ->
     ms  = new Date().getTime() - @date.getTime()
     sec = Math.round ms  / 1000
@@ -143,8 +160,19 @@ class RelativeTimeAgo
   formatTime: ->
     strftime @date, '%l:%M%P'
 
+relativeDate = (date) ->
+  new RelativeTime(date).formatDate()
+
 relativeTimeAgo = (date) ->
-  new RelativeTimeAgo(date).toString()
+  new RelativeTime(date).toString()
+
+relativeTimeOrDate = (date) ->
+  new RelativeTime(date).toTimeOrDateString()
+
+relativeWeekday = (date) ->
+  if day = new RelativeTime(date).relativeWeekday()
+    day.charAt(0).toUpperCase() + day.substring(1)
+
 
 domLoaded = false
 
@@ -156,10 +184,6 @@ update = (callback) ->
   if Turbolinks?.supported
     document.addEventListener "page:update", callback
   else
-    setTimeout ->
-      window.addEventListener "popstate", callback
-    , 1
-
     jQuery?(document).on "ajaxSuccess", (event, xhr) ->
       callback() if jQuery.trim xhr.responseText
 
@@ -180,19 +204,30 @@ document.addEventListener "DOMContentLoaded", ->
     time = new Date Date.parse datetime
     return if isNaN time
 
+    unless element.hasAttribute("title")
+      element.setAttribute "title", strftime(time, "%B %e, %Y at %l:%M%P %Z")
+
     element[textProperty] =
       switch local
+        when "date"
+          element.setAttribute "data-localized", true
+          relativeDate time
         when "time"
           element.setAttribute "data-localized", true
           strftime time, format
         when "time-ago"
           relativeTimeAgo time
+        when "time-or-date"
+          relativeTimeOrDate time
+        when "weekday"
+          relativeWeekday(time) ? ""
+
+run = ->
+  event = document.createEvent "Events"
+  event.initEvent "time:elapse", true, true
+  document.dispatchEvent event
 
-  setInterval ->
-    event = document.createEvent "Events"
-    event.initEvent "time:elapse", true, true
-    document.dispatchEvent event
-  , 60 * 1000
+setInterval run, 60 * 1000
 
 # Public API
-@LocalTime = {strftime, relativeTimeAgo}
+@LocalTime = {relativeDate, relativeTimeAgo, relativeTimeOrDate, relativeWeekday, run, strftime}

data/app/helpers/local_time_helper.rb

@@ -1,9 +1,11 @@
 module LocalTimeHelper
   DEFAULT_FORMAT = '%B %e, %Y %l:%M%P'
 
-  def local_time(time, options = {})
-    time   = utc_time(time)
-    format = time_format(options.delete(:format))
+  def local_time(time, options = nil)
+    time = utc_time(time)
+
+    options, format = extract_options_and_value(options, :format)
+    format = find_time_format(format)
 
     options[:data] ||= {}
     options[:data].merge! local: :time, format: format
@@ -11,20 +13,28 @@ module LocalTimeHelper
     time_tag time, time.strftime(format), options
   end
 
-  def local_date(time, options = {})
-    options.reverse_merge! format: '%B %e, %Y'
+  def local_date(time, options = nil)
+    options, format = extract_options_and_value(options, :format)
+    options[:format] = format || '%B %e, %Y'
     local_time time, options
   end
 
-  def local_time_ago(time, options = {})
+  def local_relative_time(time, options = nil)
     time = utc_time(time)
+    options, type = extract_options_and_value(options, :type)
 
     options[:data] ||= {}
-    options[:data].merge! local: 'time-ago'
+    options[:data].merge! local: type
 
     time_tag time, time.strftime(DEFAULT_FORMAT), options
   end
 
+  def local_time_ago(time, options = nil)
+    options, type = extract_options_and_value(options, :type)
+    options[:type] = 'time-ago'
+    local_relative_time time, options
+  end
+
   def utc_time(time_or_date)
     if time_or_date.respond_to?(:in_time_zone)
       time_or_date.in_time_zone.utc
@@ -34,7 +44,7 @@ module LocalTimeHelper
   end
 
   private
-    def time_format(format)
+    def find_time_format(format)
       if format.is_a?(Symbol)
         if (i18n_format = I18n.t("time.formats.#{format}", default: [:"date.formats.#{format}", ''])).present?
           i18n_format
@@ -47,4 +57,16 @@ module LocalTimeHelper
         format.presence || DEFAULT_FORMAT
       end
     end
+
+    def extract_options_and_value(options, value_key = nil)
+      case options
+      when Hash
+        value = options.delete(value_key)
+        [ options, value ]
+      when NilClass
+        [ {} ]
+      else
+        [ {}, options ]
+      end
+    end
 end

data/test/helpers/local_time_helper_test.rb

@@ -1,11 +1,19 @@
 require_relative '../../app/helpers/local_time_helper'
 require 'active_support/all'
 require 'action_view'
+
 require 'minitest/autorun'
+begin
+  # 2.0.0
+  class TestCase < MiniTest::Test; end
+rescue NameError
+  # 1.9.3
+  class TestCase < MiniTest::Unit::TestCase; end
+end
 
 I18n.enforce_available_locales = false
 
-class LocalTimeHelperTest < MiniTest::Unit::TestCase
+class LocalTimeHelperTest < TestCase
   include ActionView::Helpers::DateHelper, ActionView::Helpers::TagHelper
   include LocalTimeHelper
 
@@ -51,6 +59,11 @@ class LocalTimeHelperTest < MiniTest::Unit::TestCase
     assert_equal expected, local_time(@time, format: '%b %e')
   end
 
+  def test_local_time_with_format_as_string
+    expected = %Q(<time data-format="%b %e" data-local="time" datetime="#{@time_js}">Nov 21</time>)
+    assert_equal expected, local_time(@time, '%b %e')
+  end
+
   def test_local_time_with_i18n_format
     expected = %Q(<time data-format="%b %e" data-local="time" datetime="#{@time_js}">Nov 21</time>)
     assert_equal expected, local_time(@time, format: :simple_time)
@@ -88,6 +101,11 @@ class LocalTimeHelperTest < MiniTest::Unit::TestCase
     assert_equal expected, local_date(@time.to_date, format: '%b %e')
   end
 
+  def test_local_date_with_format_as_string
+    expected = %Q(<time data-format="%b %e" data-local="time" datetime="#{@time_js}">Nov 21</time>)
+    assert_equal expected, local_date(@time.to_date, '%b %e')
+  end
+
   def test_local_date_with_i18n_format
     expected = %Q(<time data-format="%b %e" data-local="time" datetime="#{@time_js}">Nov 21</time>)
     assert_equal expected, local_date(@time.to_date, format: :simple_date)
@@ -112,4 +130,14 @@ class LocalTimeHelperTest < MiniTest::Unit::TestCase
     expected = %Q(<time class="date-time" data-local="time-ago" datetime="#{@time_js}">November 21, 2013  6:00am</time>)
     assert_equal expected, local_time_ago(@time, class: "date-time")
   end
+
+  def test_relative_time
+    expected = %Q(<time data-local="time-or-date" datetime="#{@time_js}">November 21, 2013  6:00am</time>)
+    assert_equal expected, local_relative_time(@time, type: "time-or-date")
+  end
+
+  def test_local_time_ago_with_type_as_string
+    expected = %Q(<time data-local="time-or-date" datetime="#{@time_js}">November 21, 2013  6:00am</time>)
+    assert_equal expected, local_relative_time(@time, "time-or-date")
+  end
 end

data/test/javascripts/{index.js.coffee → local_time/index.js.coffee}

@@ -1,13 +1,18 @@
-#= require qunit
-#= require moment
-#= require sinon-timers
+#= require vendor/qunit
+#= require vendor/moment
+#= require vendor/sinon-timers
 #= require local_time
-#= require_directory ./unit
+
 #= require_self
+#= require_directory .
+
+@addTimeEl = ({format, type, datetime} = {}) ->
+  format ?= "%Y"
+  type ?= "time"
+  datetime ?= "2013-11-12T12:13:00Z"
 
-@addTimeEl = (format = "%Y", datetime = "2013-11-12T12:13:00Z") ->
   el = document.createElement "time"
-  el.setAttribute "data-local", "time"
+  el.setAttribute "data-local", type
   el.setAttribute "data-format", format
   el.setAttribute "datetime", datetime
   document.body.appendChild el

data/test/javascripts/{unit → local_time}/local_time_test.js.coffee

@@ -8,7 +8,7 @@ test "date", ->
   assertLocalized "date", "date"
 
 test "unparseable time", ->
-  el = addTimeEl "%Y", ":("
+  el = addTimeEl format: "%Y", datetime: ":("
   setText el, "2013"
   run()
   equal getText(el), "2013"

data/test/javascripts/{unit → local_time}/page_events_test.js.coffee

@@ -10,11 +10,6 @@ test "document time:elapse", ->
   triggerEvent "time:elapse"
   ok getText el
 
-test "window popstate", ->
-  el = addTimeEl()
-  triggerEvent "popstate", window
-  ok getText el
-
 test "document page:update with Turbolinks on", ->
   el = addTimeEl()
   triggerEvent "page:update"