ndr_ui 1.8.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 090dbe1864365cac5df2b73d3ca50b45ac81a254
+  data.tar.gz: ae73d19d763f5de57740b2aa4f5718744d7e3c01
+SHA512:
+  metadata.gz: 9f279abb82c5d964d9f02ccbd1a3e780a0a49f0ad7fabaa20b09f71bb6edb514e577492fe2f0de14c462005e8ce8cc8d7b3cf78ef307aa57bd4389c1a7de2156
+  data.tar.gz: 2061bd700901a6ee9959fe149c25b217a8e0dc32f7e12ce5f09c03e2d33ae9dbea9d0ee23ab6c2e35736296ee518e83ceab254cf9312c8e4e23085838f69bb33

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Public Health England
+
+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

@@ -0,0 +1,127 @@
+# NdrUi [![Build Status](https://travis-ci.org/PublicHealthEngland/ndr_ui.svg)](https://travis-ci.org/PublicHealthEngland/ndr_ui)
+
+This is the Public Health England (PHE) National Disease Registration (NDR) User Interface rubygem,
+providing a set of core features:
+
+1. jQuery
+2. [Bootstrap](http://getbootstrap.com)
+3. a Bootstrap based Rails Form Builder
+4. ~~Bootstrap based pagination links~~
+5. Bootstrap based Rails Helpers
+
+and a set of opt-in plugins:
+
+1. Bootstrap based [datepicker](https://github.com/eternicode/bootstrap-datepicker)
+2. [Timeago](https://github.com/rmm5t/jquery-timeago) jQuery plugin and Rails Helper
+
+Adding third-party plugins to the gem allows us to fix our systems to clearly defined
+versions of the third-party libraries and enables us to add syntactic sugar (in the form of
+preferred setup/defaults and rails helper methods, for example).
+
+To experiment with the code, run `bin/console` for an interactive prompt.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ndr_ui'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install ndr_ui
+
+## Usage
+
+Require NdrUi javascripts at the top of `app/assets/javascripts/application.js`:
+
+```javascript
+//= require ndr_ui
+```
+
+Import NdrUi styles at the top of `app/assets/stylesheets/application.scss`:
+
+```scss
+/*
+*= require ndr_ui
+*/
+```
+
+Require NdrUi::BootstrapHelper near the top of `app/controllers/application_controller.rb`:
+
+```ruby
+class ApplicationController < ActionController::Base
+  ...
+
+  helper NdrUi::BootstrapHelper
+end
+```
+
+### Datepicker
+
+To use the Bootstrap based [datepicker](https://github.com/eternicode/bootstrap-datepicker), require it after ndr_ui. For example:
+
+In `app/assets/javascripts/application.js`:
+
+```javascript
+//= require ndr_ui
+//= require ndr_ui/datepicker
+```
+
+In `app/assets/stylesheets/application.scss`:
+
+```scss
+/*
+*= require ndr_ui
+*= require ndr_ui/datepicker
+*/
+```
+
+Use `<%= form.datepicker_field(method, options) %>` in your Bootstrap forms (see the method documentation for more details).
+
+### Timeago
+
+To use the [Timeago](https://github.com/rmm5t/jquery-timeago) jQuery plugin and helper method:
+
+Require it after ndr_ui at the top of `app/assets/javascripts/application.js`:
+
+```javascript
+//= require ndr_ui
+//= require ndr_ui/timeago
+```
+
+Require NdrUi::TimeagoHelper near the top of `app/controllers/application_controller.rb`:
+
+```ruby
+class ApplicationController < ActionController::Base
+  ...
+
+  helper NdrUi::BootstrapHelper
+  helper NdrUi::TimeagoHelper
+end
+```
+
+Use `<%= timeago_tag(some_time) %>` in your views (see the helper method documentation for more details).
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/PublicHealthEngland/ndr_ui.
+
+This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org/) code of conduct.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,34 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+# require 'rdoc/task'
+#
+# RDoc::Task.new(:rdoc) do |rdoc|
+#   rdoc.rdoc_dir = 'rdoc'
+#   rdoc.title    = 'NdrUi'
+#   rdoc.options << '--line-numbers'
+#   rdoc.rdoc_files.include('README.rdoc')
+#   rdoc.rdoc_files.include('lib/**/*.rb')
+# end
+
+load 'rails/tasks/statistics.rake'
+
+APP_RAKEFILE = File.expand_path('../test/dummy/Rakefile', __FILE__)
+load 'rails/tasks/engine.rake'
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+require 'ndr_dev_support/tasks'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task default: :test

data/app/assets/javascripts/ndr_ui/datepicker.js

@@ -0,0 +1 @@
+//= require bootstrap-datepicker-1.6.0-dist/js/bootstrap-datepicker

data/app/assets/javascripts/ndr_ui/index.js

@@ -0,0 +1,3 @@
+//= require jquery
+//= require jquery_ujs
+//= require bootstrap

data/app/assets/javascripts/ndr_ui/timeago.js

@@ -0,0 +1,5 @@
+//= require jquery-timeago-1.5.3/jquery.timeago.js
+
+jQuery(document).ready(function() {
+  jQuery("time.timeago,abbr.timeago").timeago();
+});

data/app/assets/stylesheets/ndr_ui/datepicker.scss

@@ -0,0 +1,6 @@
+@import "bootstrap-datepicker-1.6.0-dist/css/bootstrap-datepicker3";
+
+// Ensure date picker renders over the static nav
+.datepicker {
+  z-index: (1030 + 1) !important;
+}

data/app/assets/stylesheets/ndr_ui/index.scss

@@ -0,0 +1,11 @@
+// "bootstrap-sprockets" must be imported before "bootstrap" and "bootstrap/variables"
+@import "bootstrap-sprockets";
+@import "bootstrap";
+
+// Fieldsets don't behave properly with Bootstrap in Firefox
+// https://stackoverflow.com/questions/17408815/fieldset-resizes-wrong-appears-to-have-unremovable-min-width-min-content/17863685#17863685
+@-moz-document url-prefix() {
+    fieldset {
+        display: table-cell;
+    }
+}

data/app/builders/ndr_ui/bootstrap/datepicker.rb

@@ -0,0 +1,57 @@
+module NdrUi
+  module Bootstrap
+    # Provides a form builder method for the datepicker plugin
+    module Datepicker
+      # Creates a Boostrap datepicker field.
+      #
+      # ==== Signature
+      #
+      #  datepicker_field(method, options = {})
+      #
+      # ==== Example
+      #
+      #  <%= form.datepicker_field(:last_updated, no_future: true) %>
+      #  # => <div class="input-group date" data-provide="datepicker" data-date-end-date="0d">
+      #         <input class="form-control" type="text"
+      #           name="post[last_updated]" id="post_last_updated" />
+      #         <span aria-hidden="true" class="input-group-addon">
+      #           <span class="glyphicon glyphicon-calendar"></span>
+      #         </span>
+      #       </div>
+      #       <span class="help-block" data-feedback-for="post_last_updated">
+      #         <span class="text-danger"></span><span class="text-warning"></span>
+      #       </span>
+      #
+      def datepicker_field(method, options = {})
+        date_value = object.send(method).try(:to_date).try(:to_s, :ui)
+
+        defaults = {
+          value:          date_value,
+          readonly_value: date_value
+        }
+
+        date_input_group(method, defaults.deep_merge!(options))
+      end
+
+      private
+
+      # This method returns the date input-group and inline errors and warnings.
+      # The errors and warnings are appended after the group to avoid messing up the
+      # input-group-addon calendar icon.
+      def date_input_group(method, options)
+        data = { provide: 'datepicker' }
+        data[:'date-end-date'] = '0d' if options.delete(:no_future)
+
+        html = text_field_without_inline_errors(method, options)
+        return html if readonly?
+
+        @template.content_tag(:div, class: 'input-group date', data: data) do
+          html +
+            @template.content_tag(:span,
+                                  @template.bootstrap_icon_tag(:calendar),
+                                  'aria-hidden': 'true', class: 'input-group-addon')
+        end + inline_errors_and_warnings(method)
+      end
+    end
+  end
+end

data/app/builders/ndr_ui/bootstrap/form_control_class.rb

@@ -0,0 +1,50 @@
+module NdrUi
+  module Bootstrap
+    # The CSS class form-control needs to be added to the following form elements:
+    #
+    # > select
+    # > textarea
+    # > input[type="text"]
+    # > input[type="password"]
+    #   input[type="datetime"]
+    #   input[type="datetime-local"]
+    #   input[type="date"]
+    #   input[type="month"]
+    #   input[type="time"]
+    #   input[type="week"]
+    #   input[type="number"]
+    #   input[type="email"]
+    #   input[type="url"]
+    #   input[type="search"]
+    #   input[type="tel"]
+    #   input[type="color"]
+    #
+    # and this mixin does it for the elements marked ">"
+    module FormControlClass
+      def self.add_form_control_class(method_name)
+        define_method(method_name) do |label, *args, &proc|
+          options = css_class_options_merge(args.extract_options!, %w(form-control))
+          super(label, *(args << options), &proc)
+        end
+      end
+
+      def self.add_select_control_class
+        define_method('select') do |label, choices, *args, &proc|
+          # TODO: Ruby 1.8 doesn't support optional arguments with `define_method`:
+          options, html_options = *args
+          options      ||= {}
+          html_options ||= {}
+
+          html_options = css_class_options_merge(html_options, %w(form-control))
+          super(label, choices, options, html_options, &proc)
+        end
+      end
+
+      %w(password_field text_area text_field).each do |name|
+        add_form_control_class(name)
+      end
+
+      add_select_control_class
+    end
+  end
+end

data/app/builders/ndr_ui/bootstrap/inline_errors_and_warnings.rb

@@ -0,0 +1,64 @@
+module NdrUi
+  module Bootstrap
+    # Allows us to display errors and warnings in a bootstrap-friendly way
+    module InlineErrorsAndWarnings
+      # Tag::Base subclass for generating bootstrap span.help-block.
+      # Allows us to use generate the tag_id properly.
+      class HelpBlock < ActionView::Helpers::Tags::Base
+        def render(&block)
+          feedback_for =
+            if respond_to?(:name_and_id_index, true)
+              tag_id(name_and_id_index(@options))
+            else
+              add_default_name_and_id(@options.fetch('html', {}))
+            end
+
+          options = { class: 'help-block', data:  { feedback_for: feedback_for } }
+          content_tag(:span, @template_object.capture(&block), options)
+        end
+      end
+
+      def self.add_inline_errors_and_warnings_to_field_helper(selector)
+        define_method("#{selector}_with_inline_errors") do |method, *args, &block|
+          html = send("#{selector}_without_inline_errors", method, *args, &block)
+          return html + inline_errors_and_warnings(method)
+        end
+      end
+
+      def self.included(base)
+        excluded = [:label, :fields_for, :hidden_field]
+
+        # Although highly unlikely, through the use of | in all_known_field_helpers),
+        # uniq ensures we avoid a stack overflow
+        (base.all_known_field_helpers - excluded).uniq.each do |selector|
+          class_eval do
+            add_inline_errors_and_warnings_to_field_helper(selector)
+          end
+
+          base.send(:alias_method, "#{selector}_without_inline_errors".to_sym, selector)
+          base.send(:alias_method, selector, "#{selector}_with_inline_errors".to_sym)
+        end
+      end
+
+      private
+
+      def inline_errors_and_warnings(method)
+        HelpBlock.new(object_name, method, @template, options).render do
+          ''.html_safe.tap do |buffer|
+            errors = @template.safe_join(object.errors[method], @template.tag(:br))
+            buffer << @template.content_tag(:span, errors, class: 'text-danger')
+
+            if object_supports_warnings?
+              warnings = @template.safe_join(object.warnings[method], @template.tag(:br))
+              buffer << @template.content_tag(:span, warnings, class: 'text-warning')
+            end
+          end
+        end
+      end
+
+      def object_supports_warnings?
+        object.respond_to?(:warnings) && object.warnings.respond_to?(:[])
+      end
+    end
+  end
+end

data/app/builders/ndr_ui/bootstrap/readonly.rb

@@ -0,0 +1,87 @@
+module NdrUi
+  module Bootstrap
+    # Allows a form to be marked as read-only. Supported field helpers
+    # render as a non-editable display instead, allowing a form to be
+    # reused as a "show" template.
+    #
+    # Most helpers have a similar signature, so can be iterated over and
+    # enhanced. The reminaining minority have to be manually re-defined.
+    module Readonly
+      def self.included(base)
+        # These have different signatures, or aren't affected by `readonly`:
+        needs_custom = [:radio_button, :file_field] + base.field_helpers_from_form_options_helper
+        not_affected = [:label, :fields_for]
+
+        (base.field_helpers - needs_custom - not_affected).each do |selector|
+          class_eval <<-END, __FILE__, __LINE__ + 1
+            def #{selector}(method, options = {}, *rest)
+              return super unless readonly?
+              readonly_value = options.fetch(:readonly_value, object.send(method))
+              @template.content_tag(:p, readonly_value, class: 'form-control-static')
+            end
+          END
+        end
+
+        [:select, :time_zone_select].each do |selector|
+          class_eval <<-END, __FILE__, __LINE__ + 1
+            def #{selector}(method, _something, options = {}, *rest)
+              return super unless readonly?
+              readonly_value = options.fetch(:readonly_value, object.send(method))
+              @template.content_tag(:p, readonly_value, class: 'form-control-static')
+            end
+          END
+        end
+
+        [:collection_select, :collection_check_boxes, :collection_radio_buttons].each do |selector|
+          class_eval <<-END, __FILE__, __LINE__ + 1
+            def #{selector}(method, collection, value_method, text_method, options = {}, *rest)
+              return super unless readonly?
+              readonly_value = options.fetch(:readonly_value, object.send(method))
+              @template.content_tag(:p, readonly_value, class: 'form-control-static')
+            end
+          END
+        end
+
+        class_eval <<-END, __FILE__, __LINE__ + 1
+          # grouped_collection_select takes many other arguments
+          def grouped_collection_select(method, collection, group_method, group_label_method, option_key_method, option_value_method, options = {}, html_options = {})
+            return super unless readonly?
+            readonly_value = options.fetch(:readonly_value, object.send(method))
+            @template.content_tag(:p, readonly_value, class: 'form-control-static')
+          end
+
+          # radio_button takes another intermediate argument:
+          def radio_button(method, tag_value, options = {})
+            return super unless readonly?
+            readonly_value = options.fetch(:readonly_value, object.send(method))
+            @template.content_tag(:p, readonly_value, class: 'form-control-static')
+          end
+
+          # For file_field, the readonly value defaults to nil:
+          def file_field(method, options = {})
+            return super unless readonly?
+            readonly_value = options[:readonly_value]
+            @template.content_tag(:p, readonly_value, class: 'form-control-static')
+          end
+        END
+
+        class_eval <<-END, __FILE__, __LINE__ + 1
+          # Allow fields_for to inherit `readonly`:
+          def fields_for(record_name, record_object = nil, fields_options = {}, &block)
+            fields_options[:readonly] ||= readonly
+            super
+          end
+        END
+      end
+
+      attr_accessor :readonly
+      alias readonly? readonly
+
+      def initialize(*)
+        super
+
+        self.readonly = options[:readonly]
+      end
+    end
+  end
+end

data/app/builders/ndr_ui/bootstrap_builder.rb

@@ -0,0 +1,111 @@
+module NdrUi
+  # Our Bootstrp FormBuilder subclass
+  class BootstrapBuilder < ActionView::Helpers::FormBuilder
+    # FormBuilder defines `field_helpers`, but it is not an exhaustive
+    # list; here, add any others that we may want to be aware of.
+    def self.all_known_field_helpers
+      field_helpers | field_helpers_from_form_options_helper | field_helpers_from_date_helper
+    end
+
+    def self.field_helpers_from_form_options_helper
+      [:select, :collection_select, :grouped_collection_select,
+       :time_zone_select, :collection_check_boxes, :collection_radio_buttons]
+    end
+
+    def self.field_helpers_from_date_helper
+      [:date_select, :time_select, :datetime_select]
+    end
+
+    include CssHelper
+    include ::NdrUi::Bootstrap::FormControlClass
+    include ::NdrUi::Bootstrap::Readonly
+    include ::NdrUi::Bootstrap::InlineErrorsAndWarnings
+    include ::NdrUi::Bootstrap::Datepicker
+
+    attr_accessor :horizontal_mode
+
+    # Creates a bootstrap control group with label tag for the specified method (and has a direct
+    # equivalent in the legacy CautionBuilder). It automatically applies the error or warning class
+    # to the control group if the method has errors.
+    #
+    # ==== Signatures
+    #
+    #   control_group(method, text=nil, options={}, control_options={}, controls)
+    #   control_group(method, text=nil, options={}, control_options={}) do
+    #     # controls
+    #   end
+    #
+    # ==== Options
+    # * <tt>options</tt> - These are standard options that are applied to the overall form-group
+    #   div tag. Options include <tt>:id</tt> and <tt>:class</tt>
+    # * <tt>control_options</tt> - These are standard options that are applied to the controls
+    #   div tag.
+    #
+    # ==== Examples
+    #
+    # TODO: `.form-group` class (margin-left & margin-right : -15px) and `.col-*-*` class (padding-left & padding-right : 15px) should be nested in order to get the correct layout.
+
+    #   <%= form.control_group(:title, 'Demo', {:class => "col-md-6"}, {:id => 'some_id'}, "# Controls go here") %>
+    #   # => <div class="form-group col-md-6">
+    #           <label for="post_title" class="control-label">Demo</label>
+    #           <div id="some_id">
+    #             # Controls go here
+    #           </div>
+    #         </div>
+    #
+    # You can use a block as well if your alert message is hard to fit into the message parameter. ERb example:
+    #
+    #   <%= form.control_group(:title, 'Demo', {:class => "col-md-6"}, {:id => 'some_id'}) do %>
+    #     # Controls go here
+    #   <% end %>
+    #
+    def control_group(methods, text = nil, options = {}, control_options = {}, controls = '', &block)
+      if block_given?
+        return control_group(methods, text, options, control_options, @template.capture(&block))
+      else
+        methods = [methods].compact unless methods.is_a?(Array)
+
+        label_classes = ['control-label']
+        label_classes << "col-md-#{label_columns}" if horizontal_mode
+        label_html = if methods.present?
+                       label(methods.first, text, class: label_classes.join(' '))
+                     else
+                       @template.content_tag(:span, text, class: label_classes.join(' '))
+                     end
+
+        control_options = css_class_options_merge(control_options) do |control_classes|
+          # Only add a col-md-N class if none already specified
+          if horizontal_mode && control_classes.none? { |css_class| css_class.start_with?('col-') }
+            control_classes << "col-md-#{12 - label_columns}"
+          end
+        end
+
+        @template.content_tag(:div,
+                              label_html +
+                                @template.content_tag(:div, controls, control_options),
+                              control_group_options(methods, options))
+      end
+    end
+
+    def control_group_options(methods, options)
+      css_class_options_merge(options, %w(form-group)) do |group_classes|
+        if object && methods.present?
+          if methods.any? { |method| object.errors[method].present? }
+            group_classes << 'has-error'
+          elsif object.respond_to?(:warnings) && methods.any? { |method| object.warnings[method].present? }
+            group_classes << 'has-warning'
+          end
+        end
+      end
+    end
+    private :control_group_options
+
+    # if horizontal_mode is true the label_columns defaults to 3 columns
+    def label_columns
+      horizontal_mode === true ? 3 : horizontal_mode
+    end
+
+    # Lastly we run the bootstrap_builder hooks
+    ActiveSupport.run_load_hooks(:bootstrap_builder, self)
+  end
+end