journea 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b62952533c42e385316284af3e0e14a3e2ed34dd
+  data.tar.gz: bd27f82ed21bd76b53012e7f46a02f0d43981706
+SHA512:
+  metadata.gz: baa167b6d1f4b4a96b61bbc5d02650be086ecc0e316820df4a751ed3339dc59ec62b522de07aace8582f295a97dc8e411c8f231deebe2148854ee79ebbf63f38
+  data.tar.gz: b305cae30727a93ad44efd909cd145e13768f44e70b616e36e13988a2edd4dbd92cfa432e3852dc14d40b00bab1fe37987f6f3355b9cdea4cb0f7e5453a2b13f

data/LICENSE

@@ -0,0 +1,8 @@
+The Open Government Licence (OGL) Version 3
+
+Copyright (c) 2016 Environment Agency
+
+This source code is licensed under the Open Government Licence v3.0. To view this
+licence, visit www.nationalarchives.gov.uk/doc/open-government-licence/version/3
+or write to the Information Policy Team, The National Archives, Kew, Richmond,
+Surrey, TW9 4DU.

data/README.md

@@ -0,0 +1,131 @@
+# Journea (Alpha)
+
+[![Build Status](https://travis-ci.org/DEFRA/journea.svg?branch=master)](https://travis-ci.org/DEFRA/journea)
+[![Code Climate](https://codeclimate.com/github/DEFRA/journea/badges/gpa.svg)](https://codeclimate.com/github/DEFRA/journea)
+[![Test Coverage](https://codeclimate.com/github/DEFRA/journea/badges/coverage.svg)](https://codeclimate.com/github/DEFRA/journea/coverage)
+[![security](https://hakiri.io/github/DEFRA/journea/master.svg)](https://hakiri.io/github/DEFRA/journea/master)
+[![Dependency Status](https://dependencyci.com/github/DEFRA/journea/badge)](https://dependencyci.com/github/DEFRA/journea)
+[![Gem Version](https://badge.fury.io/rb/journea.svg)](https://badge.fury.io/rb/journea)
+
+**Journea** is a Ruby on Rails engine (tested on Rails 5 only) which you can use to define steps and the transitions between them. Each step (or page) is tracked in a state machine, [Statesman](https://github.com/gocardless/statesman).
+
+**Journea** handles rendering the views you design and the transitions between them are defined in an initializer.
+
+## Installation
+
+Add the gem to your gemfile.
+
+Run the install generator and answer the questions
+
+```
+# Only use in new, fresh Rails projects
+rails generate journea:install
+```
+
+## Getting started
+
+For each step you need to setup a state in the state machine
+
+```ruby
+# config/initializers/journea.rb
+
+Journea.configure_steps do
+  step :import_or_export, initial: true
+  step :company_type
+  step :limited_company_details
+  step :company_address
+  step :finish
+
+  transition from: :import_or_export,         to: :company_type
+  transition from: :company_type,             to: [:limited_company_details, :company_address]
+  transition from: :limited_company_details,  to: :company_address
+  transition from: :company_address,          to: :finish
+
+  guard_transition(to: :limited_company_details) do |journea|
+    journea.data.is_limited_company?
+  end
+
+  after_transition(to: :finish) do |journea|
+    Mailer.application_details(journea.data).deliver
+  end
+end
+```
+
+Each step can optionally have a step object, based on [simple form object](https://github.com/reinteractive-open/simple_form_object):
+
+```ruby
+# app/steps/company_address_step.rb
+
+class CompanyAddress < Journea::Step
+  attribute :address_line1, :string
+  attribute :address_line2, :string
+  attribute :city, :string
+  attribute :postcode, :string
+  attribute :is_business_address, :boolean
+
+  attribute :created_date, :datetime, default: Time.now
+
+  validates :address_line1, :address_line2, presence: true
+end
+```
+
+And each step needs a view
+
+```ruby
+
+# app/views/layouts/application.html.haml
+
+# Optional back link helper can be used anywhere
+
+= render 'back_link'
+
+# app/views/steps/company_address.html.haml
+
+.grid-row
+  .column-two-thirds
+    = simple_form_for @form do |f|
+      = render 'shared/error_messages'
+
+      %h1.heading-large What is your company address?
+
+      = f.input :address_line1
+      = f.input :address_line2, hint: 'Optional'
+      = f.input :city
+      = f.input :postcode
+      = f.input :is_business_address
+
+      = f.button :submit, 'Continue'
+
+```
+
+You can access data stored against the journey object like so
+
+```ruby
+  journey = Journea::Journey.find(1)
+  puts journey.data.certifcate_type
+
+  # or
+  puts @journea.data.certifcate_type
+```
+
+## Contributing to this project
+
+If you have an idea you'd like to contribute please log an issue.
+
+All contributions should be submitted via a pull request.
+
+## License
+
+THIS INFORMATION IS LICENSED UNDER THE CONDITIONS OF THE OPEN GOVERNMENT LICENCE found at:
+
+http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3
+
+The following attribution statement MUST be cited in your products and applications when using this information.
+
+> Contains public sector information licensed under the Open Government license v3
+
+### About the license
+
+The Open Government Licence (OGL) was developed by the Controller of Her Majesty's Stationery Office (HMSO) to enable information providers in the public sector to license the use and re-use of their information under a common open licence.
+
+It is designed to encourage use and re-use of information freely and flexibly, with only a few conditions.

data/Rakefile

@@ -0,0 +1,26 @@
+#!/usr/bin/env rake
+begin
+  require "bundler/setup"
+rescue LoadError
+  puts "You must `gem install bundler` and `bundle install` to run rake tasks"
+end
+
+APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+load "rails/tasks/engine.rake"
+
+Bundler::GemHelper.install_tasks
+
+Dir[File.join(File.dirname(__FILE__), "tasks/**/*.rake")].each {|f| load f }
+
+require "rspec/core"
+require "rspec/core/rake_task"
+
+desc "Run all specs in spec directory (excluding plugin specs)"
+RSpec::Core::RakeTask.new(:spec => "app:db:test:prepare")
+
+task :default => :spec
+
+require 'github_changelog_generator/task'
+
+GitHubChangelogGenerator::RakeTask.new :changelog do |config|
+end

data/app/controllers/journea/engine_controller.rb

@@ -0,0 +1,19 @@
+module Journea
+  class EngineController < ::ApplicationController
+    helper Journea::Engine.helpers
+
+    protect_from_forgery with: :exception
+
+    before_action :set_view_paths
+
+    private
+
+    def model
+      ::Journea::Journey
+    end
+
+    def set_view_paths
+      prepend_view_path Rails.root.join("app", "views", "steps")
+    end
+  end
+end

data/app/controllers/journea/journeys_controller.rb

@@ -0,0 +1,10 @@
+module Journea
+  class JourneysController < EngineController
+
+    def create
+      journey = model.create
+      redirect_to edit_journey_step_path(journey, journey.state_machine.current_state)
+    end
+
+  end
+end

data/app/controllers/journea/steps_controller.rb

@@ -0,0 +1,52 @@
+module Journea
+  class StepsController < EngineController
+
+    before_action :set_journey
+
+    def edit
+      @step = current_step_class.new(@journea.data_for_form(current_step_class.new))
+      @step.journey = @journea
+      render template: @step.step_name
+    end
+
+    def update
+      @step = current_step_class.new(form_params)
+      @step.pre_save(form_params)
+      @step.journey = @journea
+      if @journea.save_data(@step)
+        @journea.transition_to_next_step
+        redirect_to edit_journey_step_path(@journea, @journea.state_machine.current_state)
+      else
+        render template: @step.step_name
+      end
+    end
+
+    private
+
+    def set_journey
+      @journea = model.find(params[:journey_id])
+
+      requested_state = params[:id]
+      return unless requested_state != @journea.current_state
+
+      @journea.transition_to!(requested_state)
+    end
+
+    def current_step_class
+      class_name = "#{@journea.current_state}_step".classify
+      begin
+        class_name.constantize
+      rescue NameError
+        # If no custom class is available then use the default
+        klass = Step
+        klass.custom_name = @journea.current_state
+        klass
+      end
+    end
+
+    def form_params
+      params.fetch(current_step_class.step_name.to_sym, {}).permit(current_step_class.permitted_params)
+    end
+
+  end
+end

data/app/helpers/journea/form_helper.rb

@@ -0,0 +1,25 @@
+module Journea
+  module FormHelper
+
+    # So that we don't have to put url: on every simple form, override the url
+    # generator
+    def polymorphic_path(*args)
+      if args.present?
+        record = args.first
+        return journey_step_path(@journea, @step.step_name) if record.is_a? Step
+      end
+      super(*args)
+    end
+
+    def link_to_input_with_error(element, messages)
+      capture do
+        messages.map do |message|
+          concat(content_tag(:li) do
+            link_to message, "##{@step.step_name}_#{element}"
+          end)
+        end
+      end
+    end
+
+  end
+end

data/app/models/journea/journey.rb

@@ -0,0 +1,54 @@
+module Journea
+  class Journey < ActiveRecord::Base
+
+    include Statesman::Adapters::ActiveRecordQueries
+
+    has_many :journea_journey_transitions, class_name: "Journea::JourneyTransition", autosave: false
+    has_many :journea_keyvalues, class_name: "Journea::Keyvalue"
+
+    # State Machine related
+
+    def state_machine
+      @state_machine ||= StateMachine.new(self, transition_class: JourneyTransition)
+    end
+
+    delegate :can_transition_to?,
+             :transition_to!,
+             :transition_to,
+             :current_state,
+             :transition_to_next_step,
+             :previous_step,
+             :in_initial_state?,
+             to: :state_machine
+
+    def self.transition_class
+      Journea::JourneyTransition
+    end
+    private_class_method :transition_class
+
+    # Instance methods
+
+    def save_data(step_object)
+      return false unless step_object.valid?
+      step_object.attributes.each do |k, v|
+        key_value_pair = Keyvalue.find_or_initialize_by(key: k.to_s, journey: self)
+        key_value_pair.value = v
+        key_value_pair.save
+      end
+
+      true
+    end
+
+    def data_for_form(step_object)
+      data = Keyvalue.where(key: step_object.attributes.keys, journey: self).map do |kv|
+        [kv.key.to_sym, kv.value]
+      end
+      data.to_h
+    end
+
+    def data
+      Data.new(Keyvalue.where(journey: self))
+    end
+
+  end
+end

data/app/models/journea/journey_transition.rb

@@ -0,0 +1,17 @@
+module Journea
+  class JourneyTransition < ActiveRecord::Base
+    include Statesman::Adapters::ActiveRecordTransition
+
+    belongs_to :journey, inverse_of: :journea_journey_transitions
+
+    after_destroy :update_most_recent, if: :most_recent?
+
+    private
+
+    def update_most_recent
+      last_transition = journey.journey_transitions.order(:sort_key).last
+      return unless last_transition.present?
+      last_transition.update_column(:most_recent, true)
+    end
+  end
+end

data/app/models/journea/keyvalue.rb

@@ -0,0 +1,5 @@
+module Journea
+  class Keyvalue < ActiveRecord::Base
+    belongs_to :journey
+  end
+end

data/app/views/application/_back_link.html.haml

@@ -0,0 +1,5 @@
+- if @journea.present?
+  - if @journea.previous_step.present?
+    = link_to 'Back', edit_journey_step_path(@journea, @journea.previous_step), class: 'link-back back-link'
+  - elsif @journea.in_initial_state?
+    = link_to 'Back', main_app.root_path, class: 'link-back back-link'

data/config/initializers/simple_form.rb

@@ -0,0 +1,179 @@
+# Use this setup block to configure all options available in SimpleForm.
+# rubocop:disable Metrics/BlockLength
+SimpleForm.setup do |config|
+  # Wrappers are used by the form builder to generate a
+  # complete input. You can remove any component from the
+  # wrapper, change the order or even add your own to the
+  # stack. The options given below are used to wrap the
+  # whole input.
+  config.wrappers :default, class: ["form-group", :input],
+                            hint_class: :field_with_hint, error_class: :error do |b|
+    ## Extensions enabled by default
+    # Any of these extensions can be disabled for a
+    # given input by passing: `f.input EXTENSION_NAME => false`.
+    # You can make any of these extensions optional by
+    # renaming `b.use` to `b.optional`.
+
+    # Determines whether to use HTML5 (:email, :url, ...)
+    # and required attributes
+    b.use :html5
+
+    # Calculates placeholders automatically from I18n
+    # You can also pass a string as f.input placeholder: "Placeholder"
+    b.use :placeholder
+
+    ## Optional extensions
+    # They are disabled unless you pass `f.input EXTENSION_NAME => true`
+    # to the input. If so, they will retrieve the values from the model
+    # if any exists. If you want to enable any of those
+    # extensions by default, you can change `b.optional` to `b.use`.
+
+    # Calculates maxlength from length validations for string inputs
+    b.optional :maxlength
+
+    # Calculates pattern from format validations for string inputs
+    b.optional :pattern
+
+    # Calculates min and max from length validations for numeric inputs
+    b.optional :min_max
+
+    # Calculates readonly automatically from readonly attributes
+    b.optional :readonly
+
+    ## Inputs
+    b.use :label, class: "form-label"
+    b.use :hint,  wrap_with: { tag: :span, class: "form-hint" }
+    b.use :input, class: "form-control"
+    b.use :error, wrap_with: { tag: :span, class: "error-message" }
+
+    ## full_messages_for
+    # If you want to display the full error message for the attribute, you can
+    # use the component :full_error, like:
+    #
+    # b.use :full_error, wrap_with: { tag: :span, class: :error }
+  end
+
+  # The default wrapper to be used by the FormBuilder.
+  config.default_wrapper = :default
+
+  # Define the way to render check boxes / radio buttons with labels.
+  # Defaults to :nested for bootstrap config.
+  #   inline: input + label
+  #   nested: label > input
+  config.boolean_style = :nested
+
+  # Default class for buttons
+  config.button_class = "button"
+
+  # Method used to tidy up errors. Specify any Rails Array method.
+  # :first lists the first message for each field.
+  # Use :to_sentence to list all errors for each field.
+  # config.error_method = :first
+
+  # Default tag used for error notification helper.
+  config.error_notification_tag = :div
+
+  # CSS class to add for error notification helper.
+  config.error_notification_class = "error_notification"
+
+  # ID to add for error notification helper.
+  # config.error_notification_id = nil
+
+  # Series of attempts to detect a default label method for collection.
+  # config.collection_label_methods = [ :to_label, :name, :title, :to_s ]
+
+  # Series of attempts to detect a default value method for collection.
+  # config.collection_value_methods = [ :id, :to_s ]
+
+  # You can wrap a collection of radio/check boxes in a pre-defined tag, defaulting to none.
+  # config.collection_wrapper_tag = :fieldset
+
+  config.wrappers :vertical_radio_and_checkboxes, tag: "div", class: "form-group", error_class: "error" do |b|
+    b.use :error, wrap_with: { tag: "span", class: "error-message" }
+    b.use :input
+  end
+
+  # You can define the class to use on all collection wrappers. Defaulting to none.
+  # config.collection_wrapper_class = nil
+
+  # You can wrap each item in a collection of radio/check boxes with a tag,
+  # defaulting to :span.
+  # config.item_wrapper_tag = :span
+
+  # You can define a class to use in all item wrappers. Defaulting to none.
+  # config.item_wrapper_class = nil
+
+  # How the label text should be generated altogether with the required text.
+  config.label_text = ->(label, _required, _explicit_label) { label }
+
+  # You can define the class to use on all labels. Default is nil.
+  # config.label_class = nil
+
+  # You can define the default class to be used on forms. Can be overriden
+  # with `html: { :class }`. Defaulting to none.
+  # config.default_form_class = nil
+
+  # You can define which elements should obtain additional classes
+  # config.generate_additional_classes_for = [:wrapper, :label, :input]
+
+  # Whether attributes are required by default (or not). Default is true.
+  # config.required_by_default = true
+
+  # Tell browsers whether to use the native HTML5 validations (novalidate form option).
+  # These validations are enabled in SimpleForm's internal config but disabled by default
+  # in this configuration, which is recommended due to some quirks from different browsers.
+  # To stop SimpleForm from generating the novalidate option, enabling the HTML5 validations,
+  # change this configuration to true.
+  config.browser_validations = false
+
+  # Collection of methods to detect if a file type was given.
+  # config.file_methods = [ :mounted_as, :file?, :public_filename ]
+
+  # Custom mappings for input types. This should be a hash containing a regexp
+  # to match as key, and the input type that will be used when the field name
+  # matches the regexp as value.
+  # config.input_mappings = { /count/ => :integer }
+
+  # Custom wrappers for input types. This should be a hash containing an input
+  # type as key and the wrapper that will be used for all inputs with specified type.
+  # config.wrapper_mappings = { string: :prepend }
+
+  # Namespaces where SimpleForm should look for custom input classes that
+  # override default inputs.
+  # config.custom_inputs_namespaces << "CustomInputs"
+
+  # Default priority for time_zone inputs.
+  # config.time_zone_priority = nil
+
+  # Default priority for country inputs.
+  # config.country_priority = nil
+
+  # When false, do not use translations for labels.
+  # config.translate_labels = true
+
+  # Automatically discover new inputs in Rails' autoload path.
+  # config.inputs_discovery = true
+
+  # Cache SimpleForm inputs discovery
+  # config.cache_discovery = !Rails.env.development?
+
+  # Default class for inputs
+  # config.input_class = nil
+
+  # Define the default class of the input wrapper of the boolean input.
+  config.boolean_label_class = "checkbox"
+
+  # Defines if the default input wrapper class should be included in radio
+  # collection wrappers.
+  # config.include_default_input_wrapper_class = true
+
+  # Defines which i18n scope will be used in Simple Form.
+  # config.i18n_scope = 'simple_form'
+
+  config.wrapper_mappings = {
+    radio_buttons: :vertical_radio_and_checkboxes,
+    check_boxes: :vertical_radio_and_checkboxes,
+    boolean: :radio
+  }
+end
+# rubocop:enable Metrics/BlockLength