Skip to content
This repository has been archived by the owner on Dec 16, 2022. It is now read-only.

add pattern to date fields #33

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+83 −77
Open

add pattern to date fields #33

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 59 additions & 53 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,20 @@

## Overview

The GOV.UK standard for [date fields](https://govuk-elements.herokuapp.com/form-elements/example-date/) on
web forms is to use three boxes - one each for day, month and year, rather
than the drop_down boxes that comes as standard on rails projects. This is because research has shown that
[some users find it difficult to use dropdown lists](https://paper.dropbox.com/doc/Date-picker-vPs1AAOz3bXLm7P3rCrJm)
The GOV.UK standard for [date fields](https://govuk-elements.herokuapp.com/form-elements/example-date/) on
web forms is to use three boxes - one each for day, month and year, rather
than the drop_down boxes that comes as standard on rails projects. This is because research has shown that
[some users find it difficult to use dropdown lists](https://paper.dropbox.com/doc/Date-picker-vPs1AAOz3bXLm7P3rCrJm)
and scrolling through a long list of years (eg for date of birth) can be slower than entering 4 digits using the keyboard.

This gem provides the methods required to
This gem provides the methods required to
easily display and validate dates entered into forms in this way.


## Getting Started

Follow the four simple steps below. In the example below, we assume there is an Employee model with
attributes, ```name```, ```dob```, ```joined```, the last two attributes being ```gov_uk_dates```. Note
Follow the four simple steps below. In the example below, we assume there is an Employee model with
attributes, ```name```, ```dob```, ```joined```, the last two attributes being ```gov_uk_dates```. Note
that these must be defined on the database as ```date``` fields, not ```datetime```.

### 1. Add the Gem to your Gemfile
Expand All @@ -35,7 +35,7 @@ Then run bundle install. (Note: version 2+ requires Rails 5+, see [gov_uk_date_
Add the following line to the file ```app/assets/stylesheets/application.css.scss```

@import 'govuk_date_fields';

#### 2.2 Javascript

Add the following line to the file ```app/assets/javascripts/application.js```
Expand All @@ -46,7 +46,7 @@ Note: the javascript is optional (required only for the 'Today' button), and req

### 3. Tell your models attributes are gov_uk_dates

To specify date fields on the database that are to be rendered and validated as gov_uk_date_fields,
To specify date fields on the database that are to be rendered and validated as gov_uk_date_fields,
simply add an acts_as_gov_uk_date to your model wth the attribute names of the date fields, e.g.:

class Employee < ActiveRecord::Base
Expand All @@ -70,8 +70,8 @@ This tells the gem that there are two columns of type date on the database recor

#### 3.2 Examples

acts_as_gov_uk_date :date_of_birth, :date_joined,
validate_if: :perform_validation?,
acts_as_gov_uk_date :date_of_birth, :date_joined,
validate_if: :perform_validation?,
error_clash_behaviour: :override_with_gov_uk_date_field_error

def perform_validation?
Expand All @@ -85,7 +85,7 @@ You can also specify a Proc or a Symbol pointing to a method that checks whether

### 4. Permit the date parameters in your controller

Your controller needs to permit three parameters for each gov_uk_date field, so in the example above the
Your controller needs to permit three parameters for each gov_uk_date field, so in the example above the
employee_params method of the EmployeesController would be:

def employee_params
Expand All @@ -100,47 +100,47 @@ date field boxes in the form:

<%= form_for(@employee) do |f| %>
<%= f.gov_uk_date_field :dob, legend_text: 'Date of birth' %>

<%= f.gov_uk_date_field :joined, legend_text: 'Date joined' %>
<% end %>

#### 5.1. Options passed to gov_uk_date_field

The FormBuilder method gov_uk_date_field takes two parameters:

* the method on the model that the FormBuilder is encapsulating

* an option hash desribing how the date fields should be rendered:
- **an empty hash or nil**: means the date fields will be rendered as per version 0.1.0 of this gem,
that is just three input fields with no encapsulating fieldset, divs, or legends. This is
now deprecated and should no longer be used, but is included for backward

- **an empty hash or nil**: means the date fields will be rendered as per version 0.1.0 of this gem,
that is just three input fields with no encapsulating fieldset, divs, or legends. This is
now deprecated and should no longer be used, but is included for backward
compatibility with versions 0.0.1 and 0.0.2.
- **placeholder**: see below for an explanation of how to specify placeholders. This is now deprecated

- **placeholder**: see below for an explanation of how to specify placeholders. This is now deprecated
and should no longer be used, but is included for backward compatibility with versions 0.0.1 and 0.0.2.

- **legend_text**: The text that is to be used as the title of the Date field set.

- **legend_class**: The CSS class that is to be used for the legend
- **form_hint_text**: The text that is to advise the user how to fill in the form. If not specified,

- **form_hint_text**: The text that is to advise the user how to fill in the form. If not specified,
the text "For example, 31 3 1980" will be used.

- **id**: The id to be given to the fieldset. If absent, no id will be assigned to the fieldset. This setting also affects the id of the hint element:
if specified, then the hint element will have the fieldset id appended by '-hint', otherwise it will have the attribute name appended by '-hint'. The hint-id is
referred to by the aria-described-by attribute on the input element.

- **error_messages**: Error messages to be attached to the field, if not the string in the errors collection of the object.
This is useful if the error messages are held in a translation file for example - the client should fetch the translations and
pass in as an array of strings as the value for this option.

- **today_button**: If present, a "Today" button which, when presssed, will populate the form with today's date
will be generated. The value of this option should either be:
* true: a Today button with the default value of "button" will be generated
* {class: "button-class"} a Today button with the specified CSS class(es) will be generated
* false: a Today button will not be generated




Expand All @@ -158,7 +158,7 @@ The FormBuilder method gov_uk_date_field takes two parameters:

You're ready to go.

If the user enters values into the day/month/year boxes that can't be turned into a date, the attribute will be marked as
If the user enters values into the day/month/year boxes that can't be turned into a date, the attribute will be marked as
invalid in the model's errors hash during the validation cycle, and the entered values will be displayed back to
the user on the form.

Expand All @@ -167,6 +167,12 @@ the user on the form.

### Testing

Create the database:

cd tests/dummy
bundle exec rake db:create
cd -

Run tests either with the rake task:

bundle exec rake test
Expand All @@ -184,13 +190,13 @@ Or run test files directly from the command-line:
### What is the HTML that this gem produces?

Given an employee object with the dob attribute set to

Date.new(1965, 7, 13)

the following call to the gov_uk_date_field method:

f.gov_uk_date_field(:dob, legend_text: 'Date of birth', legend_class: 'govuk-legend')

will produce the following HTML:

<fieldset>
Expand All @@ -199,36 +205,36 @@ will produce the following HTML:
<p class="form-hint" id="dob-hint">For example, 31 3 1980</p>
<div class="form-group form-group-day">
<label for="dob-day">Day</label>
<input class="form-control"
id="dob-day"
name="dob-day"
type="number"
pattern="[0-9]*"
<input class="form-control"
id="dob-day"
name="dob-day"
type="number"
pattern="\d*"
min="0"
max="31"
aria-describedby="dob-hint"
max="31"
aria-describedby="dob-hint"
value="13">
</div>
<div class="form-group form-group-month">
<label for="dob-month">Month</label>
<input class="form-control"
id="dob-month"
name="dob-month"
type="number"
pattern="[0-9]*"
min="0"
max="12"
<input class="form-control"
id="dob-month"
name="dob-month"
type="number"
pattern="\d*"
min="0"
max="12"
value="7">
</div>
<div class="form-group form-group-year">
<label for="dob-year">Year</label>
<input class="form-control"
id="dob-year"
name="dob-year"
type="number"
pattern="[0-9]*"
min="0"
max="2016"
<input class="form-control"
id="dob-year"
name="dob-year"
type="number"
pattern="\d*"
min="0"
max="2100"
value="1965">
</div>
</div>
Expand Down
6 changes: 3 additions & 3 deletions lib/gov_uk_date_fields/form_fields.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,7 +150,7 @@ def generate_day_input_field(day_value)
result = %Q|
<div class="form-group form-group-day">
<label for="#{html_id(:day)}">Day</label>
<input class="#{css_class}" id="#{html_id(:day)}" name="#{html_name(:day)}" type="number" min="0" max="31" aria-describedby="#{@hint_id}" value="#{day_value}">
<input class="#{css_class}" id="#{html_id(:day)}" name="#{html_name(:day)}" type="number" pattern="\\d*" min="0" max="31" aria-describedby="#{@hint_id}" value="#{day_value}">
</div>
|
end
Expand All @@ -162,7 +162,7 @@ def generate_month_input_field(month_value)
result = %Q|
<div class="form-group form-group-month">
<label for="#{html_id(:month)}">Month</label>
<input class="#{css_class}" id="#{html_id(:month)}" name="#{html_name(:month)}" type="number" min="0" max="12" value="#{month_value}">
<input class="#{css_class}" id="#{html_id(:month)}" name="#{html_name(:month)}" type="number" pattern="\\d*" min="0" max="12" value="#{month_value}">
</div>
|
end
Expand All @@ -174,7 +174,7 @@ def generate_year_input_field(year_value)
result = %Q|
<div class="form-group form-group-year">
<label for="#{html_id(:year)}">Year</label>
<input class="#{css_class}" id="#{html_id(:year)}" name="#{html_name(:year)}" type="number" min="0" max="2100" value="#{year_value}">
<input class="#{css_class}" id="#{html_id(:year)}" name="#{html_name(:year)}" type="number" pattern="\\d*" min="0" max="2100" value="#{year_value}">
</div>
|
end
Expand Down
Loading