govuk_elements_rails 0.3.0 → 1.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ed73a5758d285ea9ec1e7a0421286d74ea2792f5
-  data.tar.gz: 1e3187d96b39928a349a22b1d7016f5b938e78f4
+  metadata.gz: daa6ca3a658ac82f5376402f7b2340a632d51c8e
+  data.tar.gz: 444a393037f86a9829f34cf65bc832c635ac84a0
 SHA512:
-  metadata.gz: 201e1254abc711464992b54cd023d15bda0d5b3fc9ed58326493b4c18a0eeb0348be80a8744eba1e42cf993d58c948bd9ba9e162f113bd9ced2a925cb7ea021b
-  data.tar.gz: 95ce6ed1575e03f5d78a9ed37a07f51a4e754448d38c0afa7412f657e204df83fd073f303abcf5168bc8e0577f3ff09c4f5266e5bc444382311592ffb72fc740
+  metadata.gz: 89b63c571f1666b85d2ecc654840c04c75b1398410738c254640aee1c792930796ee98a818bbbaa9605f251079dd1ddb53668800bdcd6b9ec728f7702ac7e8bc
+  data.tar.gz: 99471d0e0cf3d42df8d2659fcb223bf9a658543697a1a1650d6d128eb8cb454fc3c7c75a9ee5adffb35a5c8c014915d82ce65afed6124e04657c24e106a88bca

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (C) 2014 Crown Copyright (Government Digital Service)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -3,17 +3,137 @@
 A gem wrapper around [govuk_elements](http://github.com/alphagov/govuk_elements)
 that pulls stylesheet and javascript files into a Rails app.
 
-## Installing
+## Installing for use in a Rails app
 
-Just include `govuk_elements_rails` in your `Gemfile`. It
-automatically attaches itself to your asset path so the static/SCSS
+Just include `govuk_elements_rails` in your Rails application `Gemfile`:
+
+    gem 'govuk_elements_rails'
+
+It automatically attaches itself to your asset path so the static/SCSS
 files will be available to the asset pipeline.
 
-### Development
+### Dependency on govuk_frontend_toolkit
 
-If you are installing from git, ensure you enable submodules like so:
+The gem has a dependency on the
+[govuk_frontend_toolkit gem](https://rubygems.org/gems/govuk_frontend_toolkit).
+So `govuk_frontend_toolkit` will be installed on `bundle install` if it is not
+installed already.
 
-    gem 'govuk_elements_rails', :git => "https://github.com/ministryofjustice/govuk_elements_rails.git", :submodules => true
+### Dependency on govuk_template base HTML styles
+
+The gem assumes you have `govuk_template` base HTML styles in your SASS.
+But the [govuk_template gem](https://rubygems.org/gems/govuk_template) is not a
+dependency. Either require `govuk_template` in your `Gemfile`:
+
+    gem 'govuk_template'
+
+or include the following in a Sass file, see Usage section for details:
+
+    // Base (unclassed HTML elements)
+    // These are predefined by govuk_template
+    // If you're not using govuk_template, uncomment the line below.
+    // HTML elements, set by the GOV.UK template
+    @import 'elements/base'
+
+## Usage
+
+For detailed information on usage see the
+[govuk_elements README](https://github.com/alphagov/govuk_elements#govuk-elements).
+
+### Stylesheets usage
+
+At the top of a Sass file in your Rails project you should use an `@import` rule
+to include the file for the mixins you require.
+
+For example here are possible imports, remember to add semicolons to the end of
+lines if you are using the `scss` format instead of `sass`:
+
+    // From GDS's alphagov/govuk_frontend_toolkit
+    @import 'colours'
+    @import 'font_stack'
+    @import 'measurements'
+    @import 'conditionals'
+    @import 'device-pixels'
+    @import 'grid_layout'
+    @import 'typography'
+    @import 'shims'
+
+    @import 'design-patterns/alpha-beta'
+    @import 'design-patterns/buttons'
+    @import 'design-patterns/breadcrumbs'
+
+    // From GDS's alphagov/govuk_elements
+    @import 'elements/helpers'
+    @import 'elements/reset'
+
+    // Base (unclassed HTML elements)
+    // These are predefined by govuk_template
+    // If you're not using govuk_template, uncomment the line below.
+    // HTML elements, set by the GOV.UK template
+    // @import 'elements/base'
+
+    @import 'elements/layout'
+    @import 'elements/elements-typography'
+    @import 'elements/buttons'
+    // @import 'elements/icons'
+    @import 'elements/lists'
+    // @import 'elements/tables'
+    @import 'elements/details'
+    @import 'elements/panels'
+    @import 'elements/forms'
+    @import 'elements/forms/form-block-labels'
+    @import 'elements/forms/form-date'
+    @import 'elements/forms/form-validation'
+    @import 'elements/breadcrumbs'
+    @import 'elements/phase-banner'
+    @import 'elements/components'
+
+For further detailed information on usage see the
+[govuk_elements README](https://github.com/alphagov/govuk_elements#govuk-elements).
+
+### Javascript usage
+
+In the `app/assets/javascripts/application.js` file in your Rails project use
+`require` rule to include the files for the javascript enhancements you require.
+For example here are all the requires possible at present:
+
+    // from govuk_elements gem
+    //= require details.polyfill
+
+### Javascript from govuk_frontend_toolkit
+
+In the `app/assets/javascripts/application.js` file in your Rails project use
+`require` rule to include javascript from the `govuk_frontend_toolkit` gem. For
+example:
+
+    // from govuk_frontend_toolkit gem
+    //= require vendor/polyfills/bind
+    //= require govuk/selection-buttons
+
+To include all of the govuk javascript, require `govuk_toolkit`, i.e.
+
+    // from govuk_frontend_toolkit gem
+    //= require vendor/polyfills/bind
+    //= require govuk_toolkit
+
+See the
+[govuk_frontend_toolkit documentation](https://github.com/alphagov/govuk_frontend_toolkit#documentation)
+for details of what javascript is available.
+
+## Alternate ways to reuse GOV.UK Elements
+
+There are other alternate ways to include GOV.UK Elements implementations in a Rails
+project, for example via [NPM](https://www.npmjs.com/package/govuk-elements-sass)
+or [Mojular](https://github.com/mojular/govuk-elements).
+
+Feel free to use an alternate approach when it's more appropriate for your team.
+
+## Making updates to the gem itself
+
+You only need to look at this section if you want to update the gem with changes
+from the govuk-elements repo.
+
+If you just want to use the gem in your Rails application, don't follow these steps.
 
 If you are working on the gem itself, clone and download submodules like this:
 
@@ -22,19 +142,47 @@ If you are working on the gem itself, clone and download submodules like this:
     git submodule init
     git submodule update
 
-To add a javascript file to gem, create new symlink to govuk_elements file like this:
+To update govuk_elements to a specific tag:
 
-    cd vendor/assets/javascripts/
-    ln -s ../../../govuk_elements/public/javascripts/application.js
-    ls -l
+    cd govuk_elements
+    git fetch origin
+    git describe --tags # shows current tag
+    git tag -l  # lists available tags
+    git checkout master
+    latest_tag=`git describe --abbrev=0 --tags`
+    git checkout $latest_tag # change to most recent tag
+    cd ..
 
-To update govuk_elements to last master commit:
+Check that the symlinks under `vendor/assets` still point to the govuk_elements files.
+
+To create the gem for local testing:
+
+    rake clean
+    rake gem
+
+If you're happy all's ok, you can commit:
 
     cd govuk_elements
-    git checkout master
-    git pull
+    tag_sha=`git rev-parse HEAD`
+    commit_msg="Upgrade to govuk_elements $latest_tag"
+    commit_msg2="See govuk_elements $latest_tag changelog for details:"
+    commit_msg3="https://github.com/alphagov/govuk_elements/blob/$tag_sha/CHANGELOG.md"
+
+    echo $commit_msg
+    echo $commit_msg2
+    echo $commit_msg3
     cd ..
-    git commit -am "Update govuk_elements to last master commit."
+    git add govuk_elements
+    git commit -m "$commit_msg" -m "$commit_msg2" -m "$commit_msg3"
+
+To add a javascript file to gem, create new symlink to govuk_elements file like in this example:
+
+    cd vendor/assets/javascripts/
+    ls -l
+    ln -s ../../../govuk_elements/public/javascripts/vendor/details.polyfill.js .
+    ls -l
+    cd ../../..
+    git add vendor/javascripts/details.polyfill.js
 
 To update version number, edit version.rb, and repackage:
 
@@ -46,39 +194,10 @@ To tag and publish the gem to rubygems.org:
 
     rake publish
 
-## Usage
-
-At the top of a Sass file in your Rails project you should use an `@import` rule
-to include the file for the mixins you require. For example here are all the
-imports possible:
-
-    @import 'elements/helpers';
-    @import 'elements/reset';
-    @import 'elements/elements-typography';
-    @import 'elements/layout';
-
-    @import 'elements/forms';
-    @import 'elements/tables';
-    @import 'elements/buttons';
-    @import 'elements/details';
-    @import 'elements/lists';
-    @import 'elements/panels';
-    @import "elements/icons";
+If you are installing from git for testing, ensure you enable submodules in your Gemfile
+require like so:
 
-In the `app/assets/javascripts/application.js` file in your Rails project use
-`require` rule to include the files for the javascript enhancements you require.
-For example here are all the requires possible at present:
-
-    // from govuk_elements gem
-    //= require details.polyfill
-    //= require bind
-    //= require selection-buttons
-
-## Alternate ways to reuse GOV.UK Elements
-
-There are other alternate ways to include GOV.UK Elements files in a Rails
-project, for example via `Bower`. Feel free to use an alternate approach if it
-is more appropriate for your team.
+    gem 'govuk_elements_rails', :git => "https://github.com/ministryofjustice/govuk_elements_rails.git", :submodules => true
 
 ## Feedback
 

data/lib/govuk_elements_rails.rb

@@ -1,4 +1,3 @@
 module GovUKElementsRails
   require 'govuk_elements_rails/engine'
-  autoload 'Version', 'govuk_elements_rails/version'
 end

data/lib/govuk_elements_rails/engine.rb

@@ -1,14 +1,4 @@
 module GovUKElementsRails
   class Engine < ::Rails::Engine
-
-    initializer "govuk_elements_rails.default_form_builder" do |app|
-      use_builder = app.config.respond_to?(:use_govuk_elements_form_builder) &&
-          app.config.use_govuk_elements_form_builder
-
-      if use_builder
-        ActionView::Base.default_form_builder = GovukElementsFormBuilder
-      end
-    end
-
   end
 end

data/vendor/assets/javascripts/details.polyfill.js

@@ -7,6 +7,9 @@
 // http://www.sitepoint.com/fixing-the-details-element/
 
 (function () {
+  'use strict';
+
+  var NATIVE_DETAILS = typeof document.createElement('details').open === 'boolean';
 
   // Add event construct for modern browsers or IE
   // which fires the callback with a pre-converted target reference
@@ -26,7 +29,7 @@
   function addClickEvent(node, callback) {
     // Prevent space(32) from scrolling the page
     addEvent(node, 'keypress', function (e, target) {
-      if (target.nodeName === "SUMMARY") {
+      if (target.nodeName === 'SUMMARY') {
         if (e.keyCode === 32) {
           if (e.preventDefault) {
             e.preventDefault();
@@ -78,12 +81,9 @@
 
     // else iterate through them to apply their initial state
     var n = list.length, i = 0;
-    for (n; i < n; i++) {
+    for (i; i < n; i++) {
       var details = list[i];
 
-      // Detect native implementations
-      details.__native = typeof(details.open) == 'boolean';
-
       // Save shortcuts to the inner summary and content elements
       details.__summary = details.getElementsByTagName('summary').item(0);
       details.__content = details.getElementsByTagName('div').item(0);
@@ -103,47 +103,23 @@
       // Add aria-controls
       details.__summary.setAttribute('aria-controls', details.__content.id);
 
-      // Set tabindex so the summary is keyboard accessible
-      // details.__summary.setAttribute('tabindex', 0);
+      // Set tabIndex so the summary is keyboard accessible for non-native elements
       // http://www.saliences.com/browserBugs/tabIndex.html
-      details.__summary.tabIndex = 0;
-
-      // Detect initial open/closed state
+      if (!NATIVE_DETAILS) {
+        details.__summary.tabIndex = 0;
+      }
 
-      // Native support - has 'open' attribute
-      if (details.open === true) {
+      // Detect initial open state
+      var openAttr = details.getAttribute('open') !== null;
+      if (openAttr === true) {
         details.__summary.setAttribute('aria-expanded', 'true');
         details.__content.setAttribute('aria-hidden', 'false');
-        details.__content.style.display = 'block';
-      }
-
-      // Native support - doesn't have 'open' attribute
-      if (details.open === false) {
+      } else {
         details.__summary.setAttribute('aria-expanded', 'false');
         details.__content.setAttribute('aria-hidden', 'true');
-        details.__content.style.display = 'none';
-      }
-
-      // If this is not a native implementation
-      if (!details.__native) {
-
-        // Add an arrow
-        var twisty = document.createElement('i');
-
-        // Check for the 'open' attribute
-        // If open exists, but isn't supported it won't have a value
-        if (details.getAttribute('open') === "") {
-          details.__summary.setAttribute('aria-expanded', 'true');
-          details.__content.setAttribute('aria-hidden', 'false');
-        }
-
-        // If open doesn't exist - it will be null or undefined
-        if (details.getAttribute('open') == null || details.getAttribute('open') == "undefined" ) {
-          details.__summary.setAttribute('aria-expanded', 'false');
-          details.__content.setAttribute('aria-hidden', 'true');
+        if (!NATIVE_DETAILS) {
           details.__content.style.display = 'none';
         }
-
       }
 
       // Create a circular reference from the summary back to its
@@ -152,11 +128,11 @@
 
       // If this is not a native implementation, create an arrow
       // inside the summary
-      if (!details.__native) {
+      if (!NATIVE_DETAILS) {
 
         var twisty = document.createElement('i');
 
-        if (details.getAttribute('open') === "") {
+        if (openAttr === true) {
           twisty.className = 'arrow arrow-open';
           twisty.appendChild(document.createTextNode('\u25bc'));
         } else {
@@ -174,12 +150,22 @@
     // Also update the arrow position
     function statechange(summary) {
 
-      var expanded = summary.__details.__summary.getAttribute('aria-expanded') == 'true';
-      var hidden = summary.__details.__content.getAttribute('aria-hidden') == 'true';
+      var expanded = summary.__details.__summary.getAttribute('aria-expanded') === 'true';
+      var hidden = summary.__details.__content.getAttribute('aria-hidden') === 'true';
 
       summary.__details.__summary.setAttribute('aria-expanded', (expanded ? 'false' : 'true'));
       summary.__details.__content.setAttribute('aria-hidden', (hidden ? 'false' : 'true'));
-      summary.__details.__content.style.display = (expanded ? 'none' : 'block');
+
+      if (!NATIVE_DETAILS) {
+        summary.__details.__content.style.display = (expanded ? 'none' : '');
+
+        var hasOpenAttr = summary.__details.getAttribute('open') !== null;
+        if (!hasOpenAttr) {
+          summary.__details.setAttribute('open', 'open');
+        } else {
+          summary.__details.removeAttribute('open');
+        }
+      }
 
       if (summary.__twisty) {
         summary.__twisty.firstChild.nodeValue = (expanded ? '\u25ba' : '\u25bc');

data/vendor/assets/stylesheets/_govuk-elements.scss

@@ -0,0 +1,54 @@
+// GOV.UK front end toolkit
+// Sass variables, mixins and functions
+// https://github.com/alphagov/govuk_frontend_toolkit/tree/master/stylesheets
+
+// Settings (variables)
+@import "colours";                                // Colour variables
+@import "font_stack";                             // Font family variables
+@import "measurements";                           // Widths and gutter variables
+
+// Mixins
+@import "conditionals";                           // Media query mixin
+@import "device-pixels";                          // Retina image mixin
+@import "grid_layout";                            // Basic grid layout mixin
+@import "typography";                             // Core bold and heading mixins, also external links
+@import "shims";                                  // Inline block mixin, clearfix placeholder
+
+// Mixins to generate components (chunks of UI)
+@import "design-patterns/alpha-beta";
+@import "design-patterns/buttons";
+@import "design-patterns/breadcrumbs";
+
+// Functions
+// @import "url-helpers";                         // Function to output image-url, or prefixed path (Rails and Compass only)
+
+// GOV.UK elements
+
+@import "elements/helpers";                       // Helper functions and classes
+
+// Generic (normalize/reset.css)
+@import "elements/reset";
+
+// Base (unclassed HTML elements)
+// These are predefined by govuk_template
+// If you're not using govuk_template, uncomment the line below.
+// @import "elements/base";                       // HTML elements, set by the GOV.UK template
+
+// Objects (unstyled design patterns)
+@import "elements/layout";                        // Main content container. Grid layout - rows and column widths
+
+// Components (chunks of UI)
+@import "elements/elements-typography";           // Typography
+@import "elements/buttons";                       // Buttons
+@import "elements/icons";                         // Icons - numbered steps, calendar, search
+@import "elements/lists";                         // Lists - numbered, bulleted
+@import "elements/tables";                        // Tables - regular, numeric
+@import "elements/details";                       // Details summary
+@import "elements/panels";                        // Panels with a left grey border
+@import "elements/forms";                         // Form - wrappers, inputs, labels
+@import "elements/forms/form-block-labels";       // Chunky labels for radios and checkboxes
+@import "elements/forms/form-date";               // Date of birth pattern
+@import "elements/forms/form-validation";         // Errors and validation
+@import "elements/breadcrumbs";                   // Breadcrumbs
+@import "elements/phase-banner";                  // Alpha and beta banners and tags
+@import "elements/components";                    // GOV.UK prefixed styles - blue highlighted box