diff --git a/README.md b/README.md index 4849b4a..bf08c56 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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``` @@ -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 @@ -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? @@ -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 @@ -100,33 +100,33 @@ 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. @@ -134,13 +134,13 @@ The FormBuilder method gov_uk_date_field takes two parameters: - **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 - + @@ -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. @@ -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 @@ -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:
@@ -199,36 +205,36 @@ will produce the following HTML:

For example, 31 3 1980

-
-
-
diff --git a/lib/gov_uk_date_fields/form_fields.rb b/lib/gov_uk_date_fields/form_fields.rb index 588a12e..a582151 100644 --- a/lib/gov_uk_date_fields/form_fields.rb +++ b/lib/gov_uk_date_fields/form_fields.rb @@ -150,7 +150,7 @@ def generate_day_input_field(day_value) result = %Q|
- +
| end @@ -162,7 +162,7 @@ def generate_month_input_field(month_value) result = %Q|
- +
| end @@ -174,7 +174,7 @@ def generate_year_input_field(year_value) result = %Q|
- +
| end diff --git a/test/dummy/test/models/form_fields_test.rb b/test/dummy/test/models/form_fields_test.rb index bf39340..42b38eb 100644 --- a/test/dummy/test/models/form_fields_test.rb +++ b/test/dummy/test/models/form_fields_test.rb @@ -118,15 +118,15 @@ def expected_fieldset_output_with_error_class_and_message
- +
- +
- +
@@ -145,15 +145,15 @@ def expected_fieldset_output_with_id
- +
- +
- +
@@ -172,15 +172,15 @@ def expected_fieldset_output_with_form_hint
- +
- +
- +
@@ -199,15 +199,15 @@ def expected_fieldset_output_with_legend_class
- +
- +
- +
@@ -227,15 +227,15 @@ def expected_fieldset_output_with_unstyled_today_button Today
- +
- +
- +
@@ -255,15 +255,15 @@ def expected_fieldset_output_with_syled_today_button Today
- +
- +
- +
diff --git a/test/sample.html b/test/sample.html index e4634ac..5bab1ff 100644 --- a/test/sample.html +++ b/test/sample.html @@ -8,17 +8,17 @@
- +
- +
- +