datashift_journey 0.1.2

data/config/locales/en.yml

@@ -0,0 +1,39 @@
+---
+en:
+  datashift_journey:
+    shared:
+      errors:
+        you_have: You have
+  global:
+    back: Back
+    continue: Continue
+    journey_plan:
+      continue: Continue
+    404_notfound:
+      heading: Page not found
+      message1: Sorry, the page you’re looking for cannot be found.
+      message2: Please check the web address you entered was correct.
+    422_unprocessable_entity:
+      heading: The change you wanted was rejected
+      message1: Maybe you tried to change something you didn't have access to?
+    500_internal_server_error:
+      heading: Something went wrong
+      message1: Sorry, there is a technical problem.
+      message2: Please try again in a few minutes.
+    siteHeader_html: Override global.siteHeader_html in en.yml
+    401_unauthorized:
+      heading: Unauthorised
+      message1: You are not permitted to see this page.
+      message2: This page is restricted to certain users only.
+    403_forbidden:
+      # As per https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4
+      # We do not wish to make this information available to the client, therefore using messaging for 404-not-found instead.
+      heading: Page not found
+      message1: Sorry, the page you’re looking for cannot be found.
+      message2: Please check the web address you entered was correct.
+    503_bad_gateway:
+      heading: Service unavailable
+      message1: Please try again later. If the problem persists, call the Environment Agency helpline 03708 506 506.
+    invalid_authenticity_token:
+      heading: The cookies in your browser have been disabled
+      message_html: "To carry on with your registration please enable session %{link} in your browser."

data/config/routes.rb

@@ -0,0 +1,44 @@
+DatashiftJourney::Engine.routes.draw do
+
+  resources :journey_plans, only: [:create, :new, :edit, :update]
+
+  # TODO - Devise generates routes based on module selection .. like we are trying to do with optional Collector
+  #   https://github.com/plataformatec/devise/blob/88724e10adaf9ffd1d8dbfbaadda2b9d40de756a/lib/devise/rails/routes.rb
+
+  # TO INVESTIGATE - On an error processing a state user is redirected but this goes to
+  #   => http://localhost:3000/journey_plans/(:id)  via a get- which is index or show
+  # This currently fixes the issue so a refresh leaves user on right page
+  get '/journey_plans(.:format)', :to => 'journey_plans#create'
+  get '/journey_plans/:id', :to => 'journey_plans#edit'
+
+  # Note on using get rather than patch  :
+  # We use these to provide nicer links - to jump between states & fwd/backwards,
+  # but if the Visitor has JS disabled, link_to falls back to get even if patch, put etc specified
+  get 'journey_plans/state/back/*id', :to => '/datashift_journey/journey_plans#back_a_state', :as => :back_a_state
+
+  # These forms enables us to copy and paste url and see the state in the browser url
+  get '/journey_plans/:state/:id', :to => 'journey_plans#edit', :as => :journey_plan_state
+
+  # factory is optional - without it will create bare bones journey_class object with state set
+  get '/state_jumper/:state/(:factory)', :to => 'state_jumper#build_and_display', :as => :build_and_display
+
+  resources :journey_ends, only: [:show]
+
+=begin
+
+  patch '/journey_plans/update/:state', :to => 'journey_plans#update', :as => :update_journey_plan
+
+  get '/journey_plans/:id', :to => 'journey_plans#edit'
+
+  get 'reviews/:state/*id', :to => '/datashift_journey/reviews#edit', :as => :review_state
+
+  # We have Abandonment derived from high voltage to manage static content
+  # related to User's abandoning
+  get "/abandonments/*id" => 'abandonments#show', as: :abandonment, format: false
+
+  # includes the high voltage static page to display
+  get "/abandon_journey_plans/:page/:id", to: 'abandon_journey_plans#show', as: :abandon_journey_plan
+=end
+
+  match '(errors)/:status', to: 'errors#show', via: :all, constraints: { status: /\d{3}/ }
+end

data/lib/datashift_journey/collector/field_snippet.rb

@@ -0,0 +1,12 @@
+module DatashiftJourney
+  module Collector
+    class FieldSnippet < ActiveRecord::Base
+
+      self.table_name = 'dsj_fields_snippets'
+
+      belongs_to :form_field
+      belongs_to :snippet
+
+    end
+  end
+end

data/lib/datashift_journey/collector/page_state_snippet.rb

@@ -0,0 +1,12 @@
+module DatashiftJourney
+  module Collector
+    class PageStateSnippet < ActiveRecord::Base
+
+      self.table_name = 'dsj_page_states_snippets'
+
+      belongs_to :page_state
+      belongs_to :snippet
+
+    end
+  end
+end

data/lib/datashift_journey/collector/snippet.rb

@@ -0,0 +1,14 @@
+module DatashiftJourney
+  module Collector
+
+    class Snippet < ActiveRecord::Base
+
+      self.table_name = 'dsj_snippets'
+
+      def self.to_sentance(snippets)
+        snippets.collect { |s| s.I18n_key.present? ? I18n.t(s.I18n_key) : s.raw_text }.join(' ')
+      end
+
+    end
+  end
+end

data/lib/datashift_journey/configuration.rb

@@ -0,0 +1,103 @@
+module DatashiftJourney
+
+  # Helper struct for displaying available account types in view
+  Struct.new('StateJumperEntry', :state, :display, :factory)
+
+  class Configuration
+
+    # The start page link for journey page Back links
+    #
+    # @param [String<#call>]
+    # @return [String<#call>]
+    #
+    attr_writer :backto_start_url
+
+    # The module(s) under which to find Forms
+    # Form factory will look for a Form class related to a state called
+    #
+    #   "#{mod}::#{journey_plan.state}Form"
+    #
+    # @param [String<#call>] module name under which Forms reside
+    # @return [String<#call>]
+    #
+    attr_accessor :forms_module_name
+
+    # When no Form is required for a specific HTML page, you an specify that a NullForm is to be used
+    # by adding that state to this list
+    #
+    # @param [Array<#call>] List of states that require only a NullForm
+    # @return [Array<#call>]
+    #
+    attr_accessor :null_form_list
+
+    # Always use a NullForm when no designated Form for a page
+    # @param [Boolean<#call>]
+    # @return [Boolean<#call>]
+    #
+    attr_accessor :use_null_form_when_no_form
+
+    # The location of the View partials, for rendering
+    #
+    # default is empty, for views stored directly in app/views
+    #
+    attr_accessor :partial_location
+
+    attr_accessor :layout
+
+    # In development, you can add a state jumper toolbar, for jumping straight to any state
+    #
+    attr_accessor :add_state_jumper_toolbar
+
+    # Add required details of states to jump to (see StateJumperEntry) to this ARRAY
+    #
+    # So that any data required for previous states can be created, it supports passing in a Factory
+    # that creates that data for you by value. Use nil if no data required
+    #
+    # The factory should return an instance of your DatashiftJourney.journey_plan_class
+    #
+    # @param [ StateJumperEntry.new(:state_name, "State Name", :state_factory), .... ]
+    #
+    attr_accessor :state_jumper_states
+
+    def initialize
+      @forms_module_name = ''
+
+      @partial_location  = ''
+
+      @use_null_form_when_no_form = false
+      @null_form_list = []
+
+      @layout = 'application'
+      @add_state_jumper_toolbar = false
+      @state_jumper_states = []
+    end
+
+    def backto_start_url
+      @backto_start_url ||= Rails.application.routes.url_helpers.root_path
+    end
+
+    # @return [DatashiftJourney::Configuration] current configuration
+    def self.call
+      @configuration ||= DatashiftJourney::Configuration.new
+    end
+
+    def self.reset
+      @configuration = DatashiftJourney::Configuration.new
+    end
+
+    # @param config [DatashiftJourney::Configuration]
+    class << self
+      attr_writer :configuration
+    end
+
+    # Modify current DatashiftJourney configuration
+    # ```
+    #   DatashiftJourney::Configuration.configure do |config|
+    #     config.html_only = false
+    #   end
+    # ```
+    def self.configure
+      yield call
+    end
+  end
+end

data/lib/datashift_journey/engine.rb

@@ -0,0 +1,38 @@
+begin
+  require_relative 'exceptions'
+  require_relative 'configuration'
+  require_relative 'journey/machine_builder'
+
+  require_relative 'reference_generator'
+  require_relative 'helpers/back_link'
+
+rescue => x
+  # TODO: - remove this block once gem stable
+  puts x.inspect
+end
+
+module DatashiftJourney
+
+  class Engine < ::Rails::Engine
+
+    isolate_namespace DatashiftJourney
+
+    # Add a load path for this specific Engine
+    config.autoload_paths += Dir["#{config.root}/lib"]
+
+    # Make Shared examples and Support files available to Apps and other Engines
+    # TODO: - make this optional - i.e installable so Apps/Engines can easily pull this in themselves if they wish
+    # if Rails.env.test? && defined?(RSpec)
+    #   initializer 'datashift_journey.shared_examples' do
+    #     RSpec.configure do
+    #       Dir[File.join(File.expand_path('../../../spec/shared_examples', __FILE__), '**/*.rb')].each { |f| require f }
+    #       Dir[File.join(File.expand_path('../../../spec/support', __FILE__), '**/*.rb')].each { |f| require f }
+    #     end
+    #   end
+    #
+    #   config.autoload_paths << File.expand_path('../../../spec/support', __FILE__)
+    # end
+
+  end
+
+end

data/lib/datashift_journey/exceptions.rb

@@ -0,0 +1,26 @@
+module DatashiftJourney
+
+  class CoreException < StandardError
+
+    def initialize(msg)
+      super
+      Rails.logger.error(msg)
+    end
+
+    def self.generate(name)
+      new_class = Class.new(CoreException) do
+        def initialize(msg)
+          super(msg)
+        end
+      end
+
+      DatashiftJourney.const_set(name, new_class)
+    end
+
+  end
+
+  class FormObjectError < CoreException; end
+  class PlannerApiError < CoreException; end
+  class PlannerBlockError < CoreException; end
+
+end

data/lib/datashift_journey/helpers/back_link.rb

@@ -0,0 +1,58 @@
+#
+# Helper class for constructing back links for navigating backward through the journey
+#
+module DatashiftJourney
+
+  class BackLink
+
+    include ActionView::Helpers::UrlHelper
+
+    attr_reader :css, :current_request, :journey_plan, :engine_routes
+
+    def initialize(request, engine_routes:, journey_plan: nil, css: nil)
+      @current_request = request
+      @engine_routes = engine_routes
+      @journey_plan = journey_plan
+      @css = css
+    end
+
+    def tag(text = nil, html_opts = {})
+      if journey_plan && (journey_plan.can_back?)
+        title, url = link_arguments(text)
+        link_to title, url, html_opts.merge(class: css || 'journey-plan-back-link')
+      end
+    end
+
+    private
+
+    def link_arguments(text = nil)
+      [text || link_text, link_url]
+    end
+
+    def link_text
+      I18n.t(journey_plan ? 'global.back' : 'global.back_to_start_link')
+    end
+
+    def link_url
+      # TODO: Implement automatic reviewable
+      # return  journey_plan_reviewing_path if journey_plan.try! :under_review?
+
+      return start_url unless journey_plan
+
+      journey_plan_back_url
+    end
+
+    def start_url
+      DatashiftJourney::Configuration.call.backto_start_url
+    end
+
+    def journey_plan_back_url
+      engine_routes.back_a_state_url(journey_plan)
+    end
+
+    def journey_plan_reviewing_path
+      engine_routes.journey_plan_state_path('reviewing', journey_plan)
+    end
+
+  end
+end

data/lib/datashift_journey/journey/machine_builder.rb

@@ -0,0 +1,59 @@
+module DatashiftJourney
+  module Journey
+
+    # N.B This gem is based on the AR integration which uses the Machine name for the Column storing the state in
+    # The default name and column is :state
+    #
+    class MachineBuilder
+
+      # The available API is defined in :   ../state_machines/planner.rb
+      #
+      #     DatashiftJourney::Journey::MachineBuilder.create_journey_plan(initial: :deployment) do
+      #         sequence [:deployment,
+      #                   :default_predicator,
+      #                   :version,
+      #                   :launch]
+      #     end
+      #
+      # Args
+      #     :machine_name => :something_different     # Requires Class has a string column also called something_different
+      #     :initial => :first_state
+      #
+      def self.create_journey_plan(args = {}, &block)
+        DatashiftJourney.journey_plan_class.send :include, DatashiftJourney::StateMachines::Extensions
+        DatashiftJourney.journey_plan_class.send :extend,  DatashiftJourney::StateMachines::Extensions
+
+        create_journey_plan_for(DatashiftJourney.journey_plan_class, args, &block)
+      end
+
+      # Args
+      #     :machine_name => :something_different     # Requires Class has a column called something_different
+      #     :initial => :first_state
+      #
+      def self.create_journey_plan_for(klass, args = {}, &block)
+        machine_name = args.key?(:machine_name) ? args.delete(:machine_name) : :state
+
+        puts "Building journey plan State Machine [#{machine_name}] for [#{klass}]"
+
+        machine = if block_given?
+                    klass.class_eval do
+                      state_machine machine_name, args do
+
+                        init_plan
+
+                        instance_eval(&block) # sets the context to be StateMachine class'
+
+                        # Journey has been pre parsed, we have the states, - now build navigation events and transitions
+                        instance_eval('build_journey_plan')
+                      end
+                    end
+                  else
+                    ::StateMachines::Machine.new(klass, machine_name, args)
+                  end
+        machine
+      end
+
+    end
+
+  end
+end

data/lib/datashift_journey/prepare_data_for_review.rb

@@ -0,0 +1,219 @@
+module DatashiftJourney
+
+  #   module PrepareDataForReview
+  #
+  #     extend ActiveSupport::Concern
+  #
+  #     def self.included(base)
+  #       base.send :include, InstanceMethods
+  #     end
+  #
+  #     module InstanceMethods
+  #
+  #       # You can build your review page within a YAML config file (locale file)
+  #       # It supports a simple DSL in below format.
+  #       #
+  #       # SYNTAX :
+  #       #     Indentation, usually 2 spaces, or a 2 space TAB, is very important
+  #       #     <> are used to illustrate the elements that accept free text
+  #       #
+  #       # ROW :
+  #       #
+  #       # Each ReviewDataRow has upto 3 elements
+  #       #
+  #       #   :title:      The string for Column 1, the row header
+  #       #
+  #       #   :method: The actual database data for Column2, method to call on the model, or the association object
+  #       #
+  #       #   :link_state: The state the change me links, jumps back to.
+  #       #                Optional, if unspecified,  uses the section block (state)
+  #       #
+  #       # FULL DSL :
+  #       #
+  #       # <key>:
+  #       #   sections:
+  #       #     <section_block - usually a state>:          # The Link target defaults to this, if no explicit state set
+  #       #       section_heading: "Farming data"           # The section title - that spans the 3 columns
+  #       #       direct:                                   # Non association data i.e directly on the parent model
+  #       #         -  :title: "Activity is on a farm"      # Column title. The - indicates a list, each mini block is a row
+  #       #            :method: on_a_farm                   # Method called on association to get real (DB) data to display
+  #       #         -  :title: "Registrant is a farmer"     # Next mini block - Each section can have multiple rows
+  #       #            :method: is_a_farmer
+  #       #     <next section_block - choosing_site_address>:
+  #       #       section_heading: Waste Activity Location
+  #       #       associations:
+  #       #         <association>                     # As well as direct, supports Rails associations, on supplied model
+  #       #           -  :title: "1st Column"
+  #       #              :method: full_name           # Ruby method called on association, returns real (DB) data to display
+  #       #              :link_state: state           # The link target - i.e state to JUMP to, in order to EDIT the data
+  #       #          site_address:                    # Again, section can contain multiple rows, from multiple associations
+  #       #            -  :title: "Address"
+  #       #               :method:                    # No method supplied, data will be WHOLE associated object
+  #       #
+  #       # EXAMPLE:
+  #       #
+  #       # journey_plan_review:
+  #       #   sections:
+  #       #     choosing_farming_data:
+  #       #       section_heading: "Farming data"
+  #       #       direct:
+  #       #         -  :title: "Activity is on a farm"
+  #       #            :method: on_a_farm
+  #       #         -  :title: "Registrant is a farmer"
+  #       #            :method: is_a_farmer
+  #       #     choosing_site_address:
+  #       #       section_heading: Waste Activity Location
+  #       #       associations:
+  #       #          site_address:
+  #       #            -  :title: "Address"
+  #       #               :method:                    # No state cos Partial can render WHOLE Address object
+  #       #            -  :title: "Grid reference"
+  #       #               :method: grid_reference
+  #       #     choosing_exemption:
+  #       #       section_heading: Waste Exemption Codes
+  #       #       associations:
+  #       #         exemption:
+  #       #           -  :title: "Waste Exemptions"
+  #       #              :method: code
+  #       #
+  #       # NOTES
+  #       #
+  #       # Method can be left blank, in this case the data is the association object, so this must be display-able
+  #       #
+  #       # For example, this will cause @journey_plan.site_address to be sent to the review partial, which we know has
+  #       # special use case for Address, which renders a display address partial
+  #       #
+  #       #          site_address:
+  #       #            -  :title: "Address"
+  #       #               :method:
+  #       #
+  #       attr_reader :review_data
+  #
+  #       # rubocop:disable Metrics/MethodLength
+  #
+  #       def prepare_from_locale(model, locale_key = '.journey_plan_review')
+  #         sections = I18n.t("#{locale_key}.sections", default: {})
+  #
+  #         Rails.logger.debug("Review Sections: #{sections.inspect}")
+  #
+  #         unless sections.is_a?(Hash)
+  #           Rails.logger.error("Bad syntax in your review YAML - Expect a 'sections' Hash element")
+  #           raise "Bad syntax in your review YAML - Expect a 'sections' Hash element"
+  #         end
+  #
+  #         @model_object = model
+  #
+  #         # Return a collection of Sections (ReviewData), each section has multiple rows
+  #
+  #         sections.collect do |section, data|
+  #           next unless data[:section_heading]
+  #
+  #           @current_section = section
+  #
+  #           @review_data = ReviewDataSection.new(data[:section_heading])
+  #
+  #           # Possible Enhancement required :
+  #           # As it stands this will NOT preserve the Order as defined exactly in the YAML as it's a HASH
+  #           # with keys - for direct & association sections - which are unordered.
+  #           # So currently had to make arbitrary decision to process direct first, then associations
+  #
+  #           # Direct data on parent Model, where key is - direct:
+  #           key = "#{locale_key}.sections.#{section}.direct"
+  #
+  #           I18n.t(key).each { |column| row_to_review_data(model_object, column) } if I18n.exists?(key)
+  #
+  #           # Associated data - children of parent
+  #           key = "#{locale_key}.sections.#{current_section}.associations"
+  #
+  #           if I18n.exists?(key)
+  #
+  #             association_list = I18n.t("#{locale_key}.sections.#{current_section}.associations", default: [])
+  #
+  #             association_list.each do |association_data|
+  #               unless association_data.size == 2
+  #                 Rails.logger.error('Bad syntax in your review YAML - expect each association to have name and fields')
+  #                 next
+  #               end
+  #
+  #               # Each association should have a row defined as a list i.e Array
+  #               #  -  :title: Business trading name
+  #               #     :name: full_name
+  #               #
+  #               unless association_data[1].respond_to?(:each)
+  #                 Rails.logger.error('Bad syntax in review YAML - each row needs a title, method and optional link')
+  #                 next
+  #               end
+  #
+  #               # The first element is the association name or chain,
+  #               # i.e method(s) to call on the parent model to reach child with the actual data
+  #               association_method = association_data[0].to_s
+  #
+  #               review_object = begin
+  #                 find_association(association_method)
+  #               rescue => e
+  #                 Rails.logger.error(e.message)
+  #                 Rails.logger.error("Bad syntax in review YAML - Could not load associated object #{association_method}")
+  #                 next
+  #               end
+  #
+  #               unless review_object
+  #                 Rails.logger.error("Nil association for #{association_method} on #{model} - no review data available")
+  #                 next
+  #               end
+  #
+  #               # The second element is a list of rows, made up of title, method to call on association and the state link
+  #               association_data[1].each { |column| row_to_review_data(review_object, column) }
+  #             end
+  #           end
+  #
+  #           review_data
+  #         end
+  #       end
+  #
+  #       private
+  #
+  #       attr_accessor :current_section, :current_review_object, :review_data
+  #
+  #       attr_accessor :model_object
+  #
+  #       def row_to_review_data(review_object, row)
+  #         # The section name, can be used as the state, for linking whole section, rather than at field level
+  #         link_state = row[:link_state] || current_section
+  #         link_title = row[:link_title]
+  #
+  #         @current_review_object = review_object
+  #
+  #         # The review partial can support whole objects, or low level data from method call defined in the DSL
+  #         if row[:method].blank?
+  #           review_data.add(row[:title], review_object, link_state.to_s, link_title)
+  #         else
+  #           # rubocop:disable Style/IfInsideElse
+  #           if review_object.respond_to?(:each)
+  #             review_object.each do |o|
+  #               @current_review_object = o
+  #               review_data.add(row[:title], send_chain(row[:method]), link_state.to_s, link_title)
+  #             end
+  #           else
+  #             review_data.add(row[:title], send_chain(row[:method]), link_state.to_s, link_title)
+  #           end
+  #
+  #         end
+  #       end
+  #
+  #       def find_association(method_chain)
+  #         method_chain.to_s.split('.').inject(model_object) { |a, e| a.send(e) }
+  #       end
+  #
+  #       def send_chain(method_chain)
+  #         arr = method_chain.to_s.split('.')
+  #         begin
+  #           arr.inject(current_review_object) { |a, e| a.send(e) }
+  #         rescue => e
+  #           Rails.logger.error("Failed to process method chain #{method_chain} : #{e.message}")
+  #           return I18n.t('.journey_plan_review.missing_data')
+  #         end
+  #       end
+  #
+  #     end
+  #   end
+end

data/lib/datashift_journey/reference_generator.rb

@@ -0,0 +1,51 @@
+module DatashiftJourney
+
+  class ReferenceGenerator < Module
+    BASE           = 10
+    DEFAULT_LENGTH = 9
+    NUMBERS        = (0..9).to_a.freeze
+    LETTERS        = ('A'..'Z').to_a.freeze
+
+    attr_accessor :prefix, :length
+
+    def initialize(options)
+      @random     = Random.new
+      @prefix     = options.fetch(:prefix)
+      @length     = options.fetch(:length, DEFAULT_LENGTH)
+      @candidates = NUMBERS + (options[:letters] ? LETTERS : [])
+    end
+
+    def included(host)
+      generator_method   = method(:generate_permalink)
+      generator_instance = self
+
+      host.class_eval do
+        validates(:reference, presence: true, uniqueness: { allow_blank: true })
+
+        before_validation do |instance|
+          instance.reference ||= generator_method.call(host)
+        end
+
+        define_singleton_method(:reference_generator) { generator_instance }
+      end
+    end
+
+    private
+
+    def generate_permalink(host)
+      length = @length
+
+      loop do
+        candidate = new_candidate(length)
+        return candidate unless host.exists?(reference: candidate)
+
+        # If over half of all possible options are taken add another digit.
+        length += 1 if host.count > Rational(BASE**length, 2)
+      end
+    end
+
+    def new_candidate(length)
+      @prefix + Array.new(length) { @candidates.sample(random: @random) }.join
+    end
+  end
+end