Merge pull request #14 from gtt-project/feature/datetime-custom-field

Add a Date and time custom field format

Author: dkastl

app/views/custom_fields/formats/_datetime.html.erb

@@ -0,0 +1,11 @@
+<p>
+  <%= f.text_field :default_value, size: 20,
+                   type: 'datetime-local',
+                   step: RedmineIssueDatetime.time_step_seconds %>
+</p>
+<p>
+  <em class="info">
+    <%= l(:text_datetime_cf_zone_hint, zone: RedmineIssueDatetime.zone_name) %>
+  </em>
+</p>
+<p><%= f.text_field :url_pattern, size: 50, label: :label_link_values_to %></p>

config/locales/en.yml

@@ -2,6 +2,8 @@ en:
   field_start_time: Start time
   field_due_time: Due time
   field_all_day: All day
+  label_datetime: Date and time
+  text_datetime_cf_zone_hint: "Values are entered and shown in %{zone}, the reference time zone configured for this plugin."
   label_issue_datetime_trackers: Enabled for trackers
   label_issue_datetime_step: Time input step
   label_issue_datetime_zone: Reference time zone

config/locales/ja.yml

@@ -2,6 +2,8 @@ ja:
   field_start_time: 開始時刻
   field_due_time: 期日時刻
   field_all_day: 終日
+  label_datetime: 日付と時刻
+  text_datetime_cf_zone_hint: "値はこのプラグインで設定した基準タイムゾーン %{zone} で入力・表示されます。"
   label_issue_datetime_trackers: 有効にするトラッカー
   label_issue_datetime_step: 時刻入力の間隔
   label_issue_datetime_zone: 基準タイムゾーン

lib/redmine_issue_datetime.rb

@@ -1,4 +1,5 @@
 require_relative 'redmine_issue_datetime/drift_check'
+require_relative 'redmine_issue_datetime/datetime_format'
 require_relative 'redmine_issue_datetime/issue_extension'
 require_relative 'redmine_issue_datetime/issue_query_extension'
 require_relative 'redmine_issue_datetime/hooks'

lib/redmine_issue_datetime/datetime_format.rb

@@ -0,0 +1,100 @@
+module RedmineIssueDatetime
+  # A "Date and time" custom field format, offered alongside Redmine's built-in
+  # "Date" rather than replacing it: a field either wants a time or it does not,
+  # and that is per field.
+  #
+  # No sidecar table is involved. The whole mirror machinery elsewhere in this
+  # plugin exists because issues.start_date is a real `date` column that cannot
+  # be changed; a custom value is a string column, so a timestamp fits natively.
+  #
+  # Stored as naive local time in the instance reference zone ("2026-08-03T09:15",
+  # no offset). Three reasons: it matches how the built-in date format stores,
+  # it keeps ISO strings sortable as plain strings so ordering needs no special
+  # casing, and it is consistent with this plugin showing one clock for everyone
+  # rather than converting per viewer.
+  # Named DatetimeFormat in datetime_format.rb on purpose: Redmine adds every
+  # plugin's lib/ as an eager-load path, so Zeitwerk derives the constant from
+  # the filename. A mismatch here passes every test (test and development load
+  # lazily) and then kills a production boot with a NameError.
+  class DatetimeFormat < Redmine::FieldFormat::Unbounded
+    add 'datetime'
+    self.form_partial = 'custom_fields/formats/datetime'
+    self.searchable_supported = false
+
+    # Naive local: date and time, deliberately no zone offset.
+    PATTERN = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}\z/
+    STORAGE_FORMAT = '%Y-%m-%dT%H:%M'.freeze
+
+    def label
+      'label_datetime'
+    end
+
+    def cast_single_value(custom_field, value, _customized = nil)
+      return nil if value.blank?
+
+      # Interpreted in the reference zone, which is the clock the value was
+      # entered on.
+      RedmineIssueDatetime.reference_zone.strptime(value.to_s, STORAGE_FORMAT)
+    rescue ArgumentError
+      nil
+    end
+
+    def validate_single_value(custom_field, value, customized = nil)
+      errors = super
+      return errors if value.blank?
+
+      unless PATTERN.match?(value.to_s) && cast_single_value(custom_field, value)
+        errors << ::I18n.t('activerecord.errors.messages.invalid')
+      end
+      errors
+    end
+
+    # Formatted on the reference zone, deliberately not via the view's
+    # format_time, which converts to the viewer's own zone: this plugin shows one
+    # clock for everyone. Admin date/time settings are honoured when set, and the
+    # fallbacks are explicit rather than a locale default, because those can omit
+    # the year (:short renders "03 Aug 09:15").
+    def formatted_value(_view, custom_field, value, customized = nil, _html = false)
+      time = cast_single_value(custom_field, value, customized)
+      return '' if time.nil?
+
+      date_part = Setting.date_format.presence || '%Y-%m-%d'
+      time_part = Setting.time_format.presence || '%H:%M'
+      time.strftime("#{date_part} #{time_part}")
+    end
+
+    def edit_tag(view, tag_id, tag_name, custom_value, options = {})
+      datetime_field(view, tag_name, custom_value.value,
+                     options.merge(id: tag_id))
+    end
+
+    def bulk_edit_tag(view, tag_id, tag_name, custom_field, objects, value, options = {})
+      datetime_field(view, tag_name, value, options.merge(id: tag_id)) +
+        bulk_clear_tag(view, tag_id, tag_name, custom_field, value)
+    end
+
+    # Filtering and grouping come from the framework once the type is declared.
+    def query_filter_options(_custom_field, _query)
+      {type: :datetime}
+    end
+
+    def group_statement(custom_field)
+      order_statement(custom_field)
+    end
+
+    private
+
+    # The step makes the browser's picker move in the configured interval, the
+    # same grid as the start/due time fields. It is deliberately not enforced
+    # server-side: unlike the scheduling times, an arbitrary datetime field may
+    # legitimately record something off the grid, such as when an incident was
+    # reported.
+    def datetime_field(view, name, value, options = {})
+      value = value.strftime(STORAGE_FORMAT) if value.respond_to?(:strftime)
+      view.text_field_tag(name, value, options.merge(
+                                         type: 'datetime-local',
+                                         step: RedmineIssueDatetime.time_step_seconds
+                                       ))
+    end
+  end
+end

test/unit/datetime_format_test.rb

@@ -0,0 +1,127 @@
+require File.expand_path('../test_helper', __dir__)
+
+class DatetimeFormatTest < ActiveSupport::TestCase
+  include IssueDatetimeTestHelper
+
+  fixtures :projects, :users, :email_addresses, :trackers, :projects_trackers,
+           :issue_statuses, :issues, :enumerations, :enabled_modules,
+           :members, :member_roles, :roles, :custom_fields, :custom_values
+
+  def setup
+    enable_issue_datetime(Issue.find(1).tracker_id, zone: 'Tokyo')
+    @field = IssueCustomField.create!(name: 'Inspection at', field_format: 'datetime',
+                                      is_for_all: true, tracker_ids: Tracker.pluck(:id))
+    @issue = Issue.find(1)
+  end
+
+  test 'the format is registered and offered alongside date' do
+    names = Redmine::FieldFormat.available_formats
+
+    assert_includes names, 'datetime'
+    assert_includes names, 'date', 'the built-in date format must remain available'
+  end
+
+  test 'the format is labelled for the picker' do
+    assert_equal 'label_datetime', Redmine::FieldFormat.find('datetime').label
+  end
+
+  test 'a naive local value round-trips through the custom field' do
+    @issue.custom_field_values = {@field.id.to_s => '2026-08-03T09:15'}
+
+    assert @issue.save
+    assert_equal '2026-08-03T09:15', @issue.reload.custom_field_value(@field)
+  end
+
+  # Stored naive, interpreted in the reference zone: the cast must land on the
+  # same wall clock the user typed, not shift it.
+  test 'casting interprets the stored value in the reference zone' do
+    cast = @field.format.cast_single_value(@field, '2026-08-03T09:15')
+
+    assert_equal 'Asia/Tokyo', cast.time_zone.tzinfo.name
+    assert_equal '09:15', cast.strftime('%H:%M')
+    assert_equal Time.utc(2026, 8, 3, 0, 15), cast.utc
+  end
+
+  test 'a value without a time is rejected' do
+    @issue.custom_field_values = {@field.id.to_s => '2026-08-03'}
+
+    assert_not @issue.save
+  end
+
+  test 'a value with a zone offset is rejected, since storage is naive' do
+    @issue.custom_field_values = {@field.id.to_s => '2026-08-03T09:15+09:00'}
+
+    assert_not @issue.save
+  end
+
+  test 'an impossible time is rejected' do
+    @issue.custom_field_values = {@field.id.to_s => '2026-08-03T25:99'}
+
+    assert_not @issue.save
+  end
+
+  test 'a blank value is allowed when the field is not required' do
+    @issue.custom_field_values = {@field.id.to_s => ''}
+
+    assert @issue.save
+  end
+
+  # The year must always be present: a locale default such as :short renders
+  # "03 Aug 09:15", which is ambiguous for anything not in the current year.
+  test 'formatting shows the full date and the time' do
+    formatted = @field.format.formatted_value(nil, @field, '2026-08-03T09:15')
+
+    assert_includes formatted, '09:15'
+    assert_includes formatted, '2026'
+  end
+
+  test 'formatting honours the admin date and time settings' do
+    with_settings date_format: '%d/%m/%Y', time_format: '%H:%M' do
+      assert_equal '03/08/2026 09:15',
+                   @field.format.formatted_value(nil, @field, '2026-08-03T09:15')
+    end
+  end
+
+  # Values are shown on one clock for everyone, so formatting must not follow the
+  # viewer's own time zone the way Redmine's format_time helper would.
+  test 'formatting does not follow the viewer time zone' do
+    # Captured before anything that can raise, so the ensure block always
+    # restores rather than assuming what the surrounding state was.
+    previous_user = User.current
+    user = User.find(2)
+    original_zone = user.pref.time_zone
+    User.current = user
+    user.pref.update(time_zone: 'UTC')
+
+    assert_includes @field.format.formatted_value(nil, @field, '2026-08-03T09:15'), '09:15'
+  ensure
+    user&.pref&.update(time_zone: original_zone)
+    User.current = previous_user
+  end
+
+  test 'formatting a blank value yields an empty string, not an error' do
+    assert_equal '', @field.format.formatted_value(nil, @field, '')
+  end
+
+  # ISO 8601 sorts correctly as a plain string, which is why storage uses it:
+  # ordering needs no special casing.
+  test 'stored values sort chronologically as strings' do
+    values = ['2026-08-03T09:15', '2026-08-03T08:00', '2026-01-15T23:59', '2026-08-03T10:00']
+
+    assert_equal ['2026-01-15T23:59', '2026-08-03T08:00', '2026-08-03T09:15', '2026-08-03T10:00'],
+                 values.sort
+  end
+
+  test 'the filter is declared as a datetime so the framework can filter on it' do
+    assert_equal({type: :datetime}, @field.format.query_filter_options(@field, nil))
+  end
+
+  # Unlike the start/due times, an arbitrary datetime field is not forced onto
+  # the interval grid: it may legitimately record an off-grid moment.
+  test 'an off-grid minute is accepted' do
+    @issue.custom_field_values = {@field.id.to_s => '2026-08-03T09:07'}
+
+    assert @issue.save
+    assert_equal '2026-08-03T09:07', @issue.reload.custom_field_value(@field)
+  end
+end