datashift_journey 0.1.2

data/lib/generators/datashift_journey/collector/templates/collector_migration.rb.tt

@@ -0,0 +1,46 @@
+class DatashiftJourneyCreateCollector < ActiveRecord::Migration[<%= @migration_version %>]
+
+  # rubocop:disable Metrics/MethodLength
+
+  def change
+
+    create_table :dsj_form_definitions do |t|
+      t.string :state, index: true, null: false
+      t.string :klass, index: true, null: false
+      t.timestamps null: false
+    end
+
+    create_table :dsj_form_fields do |t|
+      t.references :form_definition, index: true, null: false
+      t.string     :name, index: true,  null: false, limit: 100
+      t.integer    :category, index: true, null: false
+      t.text       :presentation
+      t.timestamps null: false
+    end
+
+    # The plan is an instance of a JourneyPlan class
+    create_table :dsj_data_nodes do |t|
+      t.references  :plan,  null: false, polymorphic: true
+      t.references  :form_field, null: false
+      t.text        :field_value
+      t.timestamps  null: false
+    end
+
+    create_table :dsj_snippets do |t|
+      t.text        :raw_text
+      t.string      :I18n_key, index: true
+      t.timestamps  null: false
+    end
+
+    create_table :dsj_forms_snippets do |t|
+      t.references  :form_model, null: false
+      t.references  :snippet, null: false
+    end
+
+    create_table :dsj_fields_snippets do |t|
+      t.references  :form_field, null: false
+      t.references  :snippet, null: false
+    end
+
+  end
+end

data/lib/generators/datashift_journey/forms_generator.rb

@@ -0,0 +1,45 @@
+require 'datashift_journey/collector/base_collector_form'
+
+module DatashiftJourney
+
+  class FormsGenerator < Rails::Generators::Base
+
+    attr_accessor :state
+
+    source_root File.expand_path('templates', __dir__)
+
+    class_option :base_class, type: :string, banner: "ClassName", desc: "Class to use as the Base class for generated Forms"
+    class_option :"no-collector", type: :boolean, default: false, desc: "Do not generate form to use inbuilt data Collector"
+
+    desc 'This generator creates an initializer and concern to setup and manage the journey Model'
+
+    def create_form_per_state
+
+      method_ptr = if options["no-collector"] == false || DatashiftJourney.journey_plan_class == DatashiftJourney::Collector::Collector
+                     ->() { state_forms_for_collector_definition }
+                   else
+                     ->() { state_form_definition }
+                   end
+
+      DatashiftJourney.journey_plan_class.state_machine(:state).states.map(&:name).each do |state|
+        @state = state
+        method_ptr.call
+      end
+    end
+
+    private
+
+    def state_forms_for_collector_definition
+      @datashift_journey_baseform = "DatashiftJourney::Collector::BaseCollectorForm"
+      template 'base_form.rb', "app/forms/base_form.rb"
+      template 'collector_form.rb', "app/forms/#{state}_form.rb"
+    end
+
+    def state_form_definition
+      @datashift_journey_baseform = "DatashiftJourney::BaseForm"
+      template 'base_form.rb', "app/forms/base_form.rb"
+      template 'journey_plan_form.rb', "app/forms/#{state}_form.rb"
+    end
+
+  end
+end

data/lib/generators/datashift_journey/generate_common.rb

@@ -0,0 +1,33 @@
+module DatashiftJourney
+
+  module GenerateCommon
+
+    # Copied from https://github.com/rails/rails/blob/6-0-stable/activerecord/lib/rails/generators/active_record/migration.rb#L12-L16
+
+    # Implement the required interface for Rails::Generators::Migration.
+    def next_migration_number(dirname)
+      next_migration_number = current_migration_number(dirname) + 1
+      ActiveRecord::Migration.next_migration_number(next_migration_number)
+    end
+
+    def model_path
+      @model_path ||= File.join(destination_root, "app", "models", journey_plan_filename)
+    end
+
+    # Module name  = options[:journey_class]Journey
+
+    def journey_plan_filename
+      "#{DatashiftJourney.journey_plan_class.to_s.underscore}.rb"
+    end
+    #
+    # def concern_file(journey_class)
+    #   "#{journey_class.underscore}_journey.rb"
+    # end
+    #
+    # def decorator_file(journey_class)
+    #   "#{journey_class.underscore}_decorator.rb"
+    # end
+
+  end
+
+end

data/lib/generators/datashift_journey/setup/USAGE

@@ -0,0 +1,12 @@
+Description:
+    This generator will setup a full Datashift Journey Plan.
+
+    Creates a model file to hold the plan.
+
+    Creates an initializer file at config/initializers
+
+Example:
+    bin/rails generate setup Model
+
+    This will create :
+        app/models/datashift_journey/model.rb

data/lib/generators/datashift_journey/setup/setup_generator.rb

@@ -0,0 +1,44 @@
+module DatashiftJourney
+  class SetupGenerator < Rails::Generators::NamedBase
+
+    source_root File.expand_path('templates', __dir__)
+
+    class_option :migration, type: :boolean, default: true, aliases: '-m'
+
+    # This class automatically runs every method defined in it,
+    def generate_model
+      Rails::Generators.invoke "active_record:model", [name, 'state:string', 'reference:string:index:unique'], migration: options[:migration] unless model_exists? && behavior == :invoke
+
+      plan = File.open(File.join(SetupGenerator.source_root, "model_concern.rb.tt")).read
+
+      inject_into_file model_path, :after => /class.* < ApplicationRecord/ do
+        "\n\tinclude DatashiftJourney::ReferenceGenerator.new(prefix: 'C')\n\tvalidates_presence_of :reference\n\tvalidates_uniqueness_of :reference\n\n#{plan}"
+      end
+    end
+
+    def create_files
+      template 'initializer.rb', 'config/initializers/datashift_journey.rb'
+    end
+
+    def add_engine_to_routes
+      return if File.readlines(File.join(destination_root, "config/routes.rb")).grep(/mount DatashiftJourney::Engine =>/).present?
+
+      route("mount DatashiftJourney::Engine => '/journey'")
+
+      puts '*' * 50
+      puts "We added the following line to your application's config/routes.rb file:\n"
+      puts "  mount DatashiftJourney::Engine => '/journey'"
+    end
+
+    private
+
+    def model_exists?
+      File.exist?(File.join(destination_root, model_path))
+    end
+
+    def model_path
+      @model_path ||= File.join(destination_root, "app", "models", "#{file_path}.rb")
+    end
+
+  end
+end

data/lib/generators/datashift_journey/setup/templates/initializer.rb.tt

@@ -0,0 +1,17 @@
+DatashiftJourney.journey_plan_class = '<%= class_name %>'
+
+DatashiftJourney::Configuration.configure do |config|
+  config.partial_location = '<%= class_name.pluralize.underscore %>'
+
+  config.add_state_jumper_toolbar = false
+
+  config.state_jumper_states = {}
+end
+
+# For Form validation options see - https://github.com/trailblazer/reform#installation
+#
+require "reform/form/dry"
+
+Reform::Form.class_eval do
+  feature Reform::Form::Dry
+end

data/lib/generators/datashift_journey/setup/templates/model_concern.rb.tt

@@ -0,0 +1,37 @@
+
+  DatashiftJourney::Journey::MachineBuilder.create_journey_plan(initial: :TO_DO_SET_INITIAL_STATE) do
+
+=begin
+    The available API is defined in : datashift_journey/lib/datashift_journey/state_machines/planner.rb
+
+    A basic example with 2 simple steps, followed by one set of branches, which reconnect to another common
+    section starting at :review
+
+    DatashiftJourney::Journey::MachineBuilder.create_journey_plan(initial: :ship_address) do
+
+        # Two simple sequential steps
+        sequence [:ship_address, :bill_address]
+
+        # first define the sequences
+        branch_sequence :visa_sequence, [:visa_page1, :visa_page2]
+
+        branch_sequence :mastercard_sequence, [:page_mastercard1, :page_mastercard2, :page_mastercard3]
+
+        branch_sequence :paypal_sequence, []
+
+        # now define the parent state and the routing criteria to each sequence
+        # So after bill address we reach payment - then we split to a single step, depending on the card type entered
+
+        split_on_equality( :payment,
+                            "payment_card",    # Helper method on Checkout that returns card type from Payment
+                            visa_sequence: 'visa',
+                            mastercard_sequence: 'mastercard',
+                            paypal_sequence: 'paypal'
+        )
+
+      # All different card type branches, recombine here at review
+      sequence [:review, :complete ]
+    end
+=end
+
+  end

data/lib/generators/datashift_journey/templates/base_form.rb.tt

@@ -0,0 +1,7 @@
+class BaseForm <%= "< #{@datashift_journey_baseform}" if @datashift_journey_baseform %>
+
+  def initialize(model, journey_plan = nil)
+    super(model, journey_plan)
+  end
+
+end

data/lib/generators/datashift_journey/templates/collector_form.rb.tt

@@ -0,0 +1,18 @@
+class <%= state.to_s.camelize %>Form < ::BaseForm
+
+  def params_key
+    :<%= state %>
+  end
+
+  # Data collection performed by base class but if you need custom processing, the forms
+  # fields are represented as a series of DataNode objects, with the actual data saved in :field_value
+  #
+  # collection :data_nodes do
+  #   property :field_value
+  # end
+
+  # Example basic validation - has field been filled in :
+  # validates :field_value, presence: true
+
+end
+

data/lib/generators/datashift_journey/templates/collector_view.rb.tt

@@ -0,0 +1,15 @@
+<!--
+You can access the Reform form object via local : form
+You can access the Reform form model object via  : form.model
+You have access to main DSJ journey object via local : journey_plan
+-->
+
+<header class="text">
+  <h1 class="form-title heading-large" id="groupLabel"><%%= t(".header") %></h1>
+</header>
+
+<fieldset>
+  <legend class="visuallyhidden"><%%= t(".legend") %></legend>
+  <%%= f.label :field_value,  t(".field_value_label"), class: 'form-label' %>
+  <%%= f.text_field :field_value, class: 'form-control form-control-char-50' %>
+</fieldset>

data/lib/generators/datashift_journey/templates/journey_plan_form.rb.tt

@@ -0,0 +1,23 @@
+class <%= state.to_s.camelize %>Form < ::BaseForm
+
+  def self.factory(journey)
+
+    # Auto generated by DatashiftJourney - check the Model this Form is managing
+
+    # state_model = #{state.classify}.new
+    # new(state_model, journey)
+
+    # For example if this page concerned with collecting data for an Organisation model use :
+
+    # organisation = journey.organisation
+    # new(organisation, journey)
+
+    # If you have no separate model just use
+     new(journey)
+  end
+
+  def params_key
+    :<%= state %>
+  end
+end
+

data/lib/generators/datashift_journey/templates/journey_plan_view.rb.tt

@@ -0,0 +1,15 @@
+<!--
+You can access the Reform form object via local      : form
+You can access the Reform form model object via      : form.model
+You have access to main DSJ journey object via local : journey_plan
+-->
+
+<header class="text">
+  <h1 class="form-title heading-large" id="groupLabel"><%%= t(".header") %></h1>
+</header>
+
+<fieldset>
+  <legend class="visuallyhidden"><%%= t(".legend") %></legend>
+  <%%= f.label :field_value,  t(".field_value_label"), class: 'form-label' %>
+  <%%= f.text_field :field_value, class: 'form-control form-control-char-50' %>
+</fieldset>

data/lib/generators/datashift_journey/views_generator.rb

@@ -0,0 +1,35 @@
+module DatashiftJourney
+
+  class ViewsGenerator < Rails::Generators::Base
+
+    source_root File.expand_path('templates', __dir__)
+
+    desc 'This generator creates an initializer and concern to setup and manage the journey Model'
+
+    def create_form_per_state
+      method_ptr = if DatashiftJourney.journey_plan_class == DatashiftJourney::Collector::Collector
+              ->(p) { view_for_collector_definition(p) }
+            else
+              ->(p) { view_for_journey_plan_definition(p) }
+            end
+
+      partial_location = DatashiftJourney::Configuration.call.partial_location
+
+      path = 'app/views'
+      path = File.join(path, partial_location) if partial_location.present?
+
+      DatashiftJourney.state_names.each { |state| method_ptr.call(state.to_s, File.join(path, "_#{state}.html.erb")) }
+    end
+
+    private
+
+    def view_for_collector_definition(path)
+      template 'collector_view.rb', path
+    end
+
+    def view_for_journey_plan_definition(path)
+      template 'journey_plan_view.rb', path
+    end
+
+  end
+end

data/lib/tasks/state_machine.thor

@@ -0,0 +1,48 @@
+require'datashift_journey'
+require 'thor'
+
+class StateMachine < Thor
+
+  desc "report", "Report on the states and transitions availblke for current DSJ Journey Plan"
+
+  def report
+
+    environment
+
+    journey_plan = DatashiftJourney.journey_plan_class.new
+
+    state_machine = DatashiftJourney.journey_plan_class.state_machine
+
+    puts "\nINITIAL STATE", journey_plan.state.inspect
+
+    puts "\nEVENTS",journey_plan.state_events.inspect
+
+    puts "\nSTATE PATHS",journey_plan.state_paths.inspect
+
+    puts "\nSTATES", state_machine.states.map(&:name).inspect
+
+    puts "\nEVENT KEYS", state_machine.events.keys.sort
+
+    puts "\nBACK", state_machine.events[:back].known_states.sort
+  end
+
+  no_commands do
+
+    def environment
+
+      if File.exist?(File.expand_path('config/environment.rb'))
+        begin
+          require File.expand_path('config/environment.rb')
+        rescue => e
+         puts ("Failed to initialise ActiveRecord : #{e.message}")
+            exit -1
+          #raise ConnectionError.new("Failed to initialise ActiveRecord : #{e.message}")
+        end
+
+      else
+        raise PathError.new('No config/environment.rb found - cannot initialise ActiveRecord')
+      end
+    end
+
+  end
+end

data/spec/datashift_journey/complex_journey_spec.rb

@@ -0,0 +1,132 @@
+require 'rails_helper'
+
+module DatashiftJourney
+
+  module Journey
+
+    RSpec.describe 'Complex Machine Builder Examples' do
+      before(:each) do
+        DatashiftJourney.use_default_journey_plan_class
+        # puts DatashiftJourney.journey_plan_class.state_machine.methods.sort
+        # puts DatashiftJourney.journey_plan_class.state_machine
+
+        # N.B This is bit of a hack cos DatashiftJourney.journey_plan_class.state_machines
+        # only available after at least one Machine defined
+
+        DatashiftJourney.journey_plan_class.state_machines.clear if DatashiftJourney.journey_plan_class.respond_to?(:state_machines)
+      end
+
+      context 'Multiple Sequences' do
+        it 'reports that branches are missing when not defined' do
+          pending('create a test with a splitter but where some branch_sequences are not defined')
+
+          DatashiftJourney::Journey::MachineBuilder.create_journey_plan(initial: :splitter) do
+            branch_sequence :renew_sequence, [:business_type]
+
+            split_on_equality(:splitter,
+                              'new_or_renew_value', # Helper method on Collector
+                              new_sequence: 'new',
+                              renew_sequence: 'renew')
+          end
+
+          journey = DatashiftJourney.journey_plan_class.new
+
+          expect_state_matches(journey, :new_or_renew)
+          expect(journey.can_back?).to eq false # this is the initial state
+
+          journey.next!
+        end
+
+        it 'enables the first state to be a branch splitter' do
+          DatashiftJourney::Journey::MachineBuilder.create_journey_plan(initial: :new_or_renew) do
+            branch_sequence :new_sequence, [:business_type]
+
+            branch_sequence :renew_sequence, [:enter_reg_number]
+
+            # now define the parent state and the routing criteria to each sequence
+
+            split_on_equality(:new_or_renew,
+                              'new_or_renew_value', # Helper method on Collector
+                              new_sequence: 'new',
+                              renew_sequence: 'renew')
+
+            # Define the sequences for Business Type split
+            # Partnership Limited Company Public Body Charity Authority Other
+
+            split_on_equality(:business_type,
+                              'business_type_value', # Helper method on Collector,
+                              authority:  'authority',
+                              other_sequence: 'other',
+                              sole_trader_sequence: 'sole_trader',
+                              partnership_sequence: 'partnership',
+                              limited_company: 'limited_company',
+                              public_body:  'public_body',
+                              charity: 'charity')
+
+            # SOLE TRADER
+            branch_sequence :sole_trader_sequence, [:other_businesses, :service_provided]
+
+            split_on_equality(:service_provided,
+                              'service_provided_value', # Helper method on Collector
+                              service_provided_no_sequence: 'no',
+                              service_provided_yes_sequence: 'yes')
+
+            branch_sequence :service_provided_no_sequence, [] # => construction_demolition
+
+            # OTHER
+
+            branch_sequence :other_sequence, [:other_business]
+
+            # Construction Demolition
+
+            split_on_equality(:construction_demolition,
+                              :construction_demolition_value,
+                              registration_type_sequence: 'yes') # => registration_type
+
+            # This branch may actually simplify down to just
+            # sequence [ :registration_type, :business_details]
+
+            split_on_equality(:registration_type,
+                              :registration_type_value,
+                              carrier_dealer_sequence: 'carrier_dealer',
+                              broker_dealer_sequence: 'broker_dealer',
+                              carrier_broker_dealer_sequence: 'carrier_broker_dealer')
+
+            branch_sequence :carrier_dealer_sequence, [:business_details]
+            branch_sequence :broker_dealer_sequence, [:business_details]
+            branch_sequence :carrier_broker_dealer_sequence, [:business_details]
+
+            # RESTART COMMON JOURNEY AFTER BUSINESS TYPES
+
+            sequence [
+              :contact_details,
+              :postal_address
+            ]
+          end
+
+          journey = DatashiftJourney.journey_plan_class.new(reference: 'UNIQUE_1234')
+
+          expect_state_matches(journey, :new_or_renew)
+          expect(journey.can_back?).to eq false # this is the initial state
+          expect(journey.can_next?).to eq true
+          journey.next!
+
+          expect_state_canback_cannext_and_next!(journey, :business_type)
+
+          # First state of a branch - We should be able to go back to the Split - based on same conditions
+          expect_state_matches(journey, :other_businesses)
+          expect(journey.can_back?).to eq true
+          journey.back!
+
+          expect_state_canback_cannext_and_next!(journey, :business_type)
+
+          # Now in Sole Trader branhc
+          expect_state_canback_cannext_and_next!(journey, :other_businesses)
+          expect_state_canback_cannext_and_next!(journey, :service_provided)
+
+          expect_state_matches(journey, :construction_demolition)
+        end
+      end
+    end
+  end
+end