easy_flow 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c42186355c5aff4867710d2b43d50543a34be2ce290c9748bea1ab11b540e21c
-  data.tar.gz: e0a902db995da05a8fed9e1c8f841b90f252277f31e2867d59a43a7855bcfa03
+  metadata.gz: cf8a8dbfd774f223e6a43af475f4815a3fa9d94c9ce36d58ac546c803e299232
+  data.tar.gz: b773f634332cb61f248bbfb03879a322be6baaaacec6d7cf0220a70eb743b72e
 SHA512:
-  metadata.gz: 907fdb2b8760253cf3eea079d3dbbd92d23050d296b9c1166b8150dd5d6cff1e52b1b5f069a65b2111786808bfbcf9e097125f92b60a7e725dc958cde58b73df
-  data.tar.gz: 7db26de4465197e8983fd84c44f2bb2cc78cd79d4a999606adf11b8fa49a3af68699d19b96fa0686355bd53f5b0eaac93126627d7c37eb9b6aa2cb7c3dacc880
+  metadata.gz: 6b5de21e4e9c7074abe01b61fab6c3305f34d407dc19584e54c649e046bb138a92067cebaa1774cc15d3f55e2aaa67eb1a6fa73ed0dcec219881f7df31807e4b
+  data.tar.gz: e833348051900594e25dc04ffc7a90214544deac6b9f5965e9f3ee79cd1152672253f0679122f3503239552fb8a696285d6c51ff66fefaf955d3e958db91d8c8

data/app/controllers/easy_flow/manage/canvas_controller.rb

@@ -176,7 +176,10 @@ module EasyFlow
         step_type.settings.coerce(configuration).tap do |values|
           objections = step_type.settings.objections(values)
           raise InvalidEdit, objections.join(", ") if objections.any?
-        end
+
+          refused = step_type.settings.keep(values)
+          raise InvalidEdit, refused.join(", ") if refused.any?
+        end.then { |values| step_type.settings.unkept(values) }
       end
     end
   end

data/app/controllers/easy_flow/manage/flows_controller.rb

@@ -6,14 +6,17 @@ module EasyFlow
         @flows = ordered_flows
       end
 
+      def new
+        @flow = hosted_flows.new
+      end
+
       def create
         @flow = hosted_flows.new(create_params)
 
         if @flow.save
           redirect_to manage_flow_path(@flow), notice: "Flow created."
         else
-          @flows = ordered_flows
-          render :index, status: :unprocessable_entity
+          render :new, status: :unprocessable_entity
         end
       end
 

data/app/models/easy_flow/canvas.rb

@@ -18,7 +18,7 @@ module EasyFlow
 
     def drawn_step(node)
       { "id" => node.id, "type" => node.type, "label" => label_for(node),
-        "config" => node.config, "ports" => [], "ends_here" => ends_here?(node), "begins_here" => begins_here?(node),
+        "config" => node.config.merge(kept_values(node)), "ports" => [], "ends_here" => ends_here?(node), "begins_here" => begins_here?(node),
         "loose" => loose?(node), "choices" => choices_for(node), "placeholder" => false, **placed[node.id] }
     end
 
@@ -105,6 +105,10 @@ module EasyFlow
       end
     end
 
+    def kept_values(node)
+      step_type_for(node)&.settings&.kept_values(node.config).to_h
+    end
+
     def label_for(node)
       Name.of(node, @registry)
     end

data/app/models/easy_flow/settings.rb

@@ -3,7 +3,7 @@ module EasyFlow
     attr_reader :fields, :labels, :record_fields, :record_labels, :drawn_from, :outputs_of
 
     def initialize(fields: {}, labels: {}, record_fields: {}, record_labels: {}, choices: {},
-      limits: {}, checks: {}, required: [], drawn_from: {}, outputs_of: {})
+      limits: {}, checks: {}, required: [], drawn_from: {}, outputs_of: {}, kept: {})
       @fields = fields
       @labels = labels
       @record_fields = record_fields
@@ -14,12 +14,35 @@ module EasyFlow
       @required = required
       @drawn_from = drawn_from
       @outputs_of = outputs_of
+      @kept = kept
     end
 
     def choices
       @choices.transform_values { |offered| offered.respond_to?(:call) ? offered.call : offered }
     end
 
+    def kept_values(config)
+      @kept.to_h { |name, kept| [ name.to_s, kept[:finder].call(config.to_h)&.public_send(kept[:attribute]) ] }
+    end
+
+    def unkept(config)
+      config.to_h.except(*@kept.keys.map(&:to_s))
+    end
+
+    def keep(config)
+      refused = []
+      ActiveRecord::Base.transaction(requires_new: true) do
+        refused = @kept.filter_map do |name, kept|
+          record = kept[:finder].call(config.to_h)
+          next if record.nil? || record.update(kept[:attribute] => config.to_h[name.to_s])
+
+          "#{labels[name]} #{record.errors.messages_for(kept[:attribute]).to_sentence}"
+        end
+        raise ActiveRecord::Rollback if refused.any?
+      end
+      refused
+    end
+
     def naming_steps
       fields.select { |_name, type| type == :previous_step }.keys
     end

data/app/models/easy_flow/step_type/declaration.rb

@@ -13,6 +13,7 @@ module EasyFlow
         @checks = {}
         @drawn_from = {}
         @outputs_of = {}
+        @kept = {}
         @declared_outputs = []
         @required = []
         @awaits_input = false
@@ -69,13 +70,14 @@ module EasyFlow
         @naming = naming
       end
 
-      def setting(name, type: nil, from: nil, outputs_of: nil, label: nil, options: nil, limit: nil, check: nil, required: false, &entries)
+      def setting(name, type: nil, from: nil, outputs_of: nil, label: nil, options: nil, limit: nil, check: nil, required: false, kept_on: nil, attribute: nil, &entries)
         type ||= :from_step if from
         type ||= :from_step if outputs_of
         raise UnknownFieldType, "#{type} is not one of #{FIELD_TYPES.join(', ')}" unless FIELD_TYPES.include?(type)
 
         @drawn_from[name] = from if from
         @outputs_of[name] = outputs_of if outputs_of
+        @kept[name] = { finder: kept_on, attribute: attribute || name } if kept_on
         @required += [ name ] if required
 
         declare_entries(name, entries) if type == :list
@@ -117,7 +119,7 @@ module EasyFlow
       def settings
         Settings.new(fields: @fields, labels: @labels, record_fields: @record_fields,
           record_labels: @record_labels, choices: @choices, limits: @limits, checks: @checks,
-          required: @required, drawn_from: @drawn_from, outputs_of: @outputs_of)
+          required: @required, drawn_from: @drawn_from, outputs_of: @outputs_of, kept: @kept)
       end
     end
   end

data/app/views/easy_flow/manage/flows/index.html.erb

@@ -1,5 +1,9 @@
 <%= ui_page(max_width: :xl) do %>
-  <%= ui_page_header(title: "Flows", subtitle: "Build and edit your flows") %>
+  <%= ui_page_header(title: "Flows", subtitle: "Build and edit your flows") do |header| %>
+    <% header.action do %>
+      <%= ui_button(label: "Create", href: flow_routes.new_manage_flow_path) %>
+    <% end %>
+  <% end %>
 
   <%= ui_data_table(
     items: @flows,
@@ -13,20 +17,4 @@
       <% end %>
     <% end %>
   <% end %>
-
-  <%= ui_section(title: "Create a flow") do %>
-    <% if @flow&.errors&.any? %>
-      <%= ui_alert(message: @flow.errors.full_messages.to_sentence, type: :error) %>
-    <% end %>
-
-    <%= ui_form(action: flow_routes.manage_flows_path, method: :post) do %>
-      <label class="block text-sm font-medium mb-1">Slug</label>
-      <%= ui_input(name: "flow[slug]", placeholder: "e.g. business-scorecard") %>
-
-      <label class="block text-sm font-medium mb-1 mt-4">Kind</label>
-      <%= ui_select(name: "flow[kind]", options: [ [ "Scored", "scored" ], [ "Guide", "guide" ] ]) %>
-
-      <%= ui_button(label: "Create", type: :submit, variant: :secondary) %>
-    <% end %>
-  <% end %>
 <% end %>

data/app/views/easy_flow/manage/flows/new.html.erb

@@ -0,0 +1,17 @@
+<%= ui_page(max_width: :md) do %>
+  <%= ui_page_header(title: "New flow") %>
+
+  <% if @flow.errors.any? %>
+    <%= ui_alert(message: @flow.errors.full_messages.to_sentence, type: :error) %>
+  <% end %>
+
+  <%= ui_form(action: flow_routes.manage_flows_path, method: :post) do %>
+    <label class="block text-sm font-medium mb-1">Slug</label>
+    <%= ui_input(name: "flow[slug]", value: @flow.slug, placeholder: "e.g. business-scorecard") %>
+
+    <label class="block text-sm font-medium mb-1 mt-4">Kind</label>
+    <%= ui_select(name: "flow[kind]", options: [ [ "Scored", "scored" ], [ "Guide", "guide" ] ], selected: @flow.kind) %>
+
+    <%= ui_button(label: "Create", type: :submit) %>
+  <% end %>
+<% end %>

data/config/routes.rb

@@ -1,6 +1,6 @@
 EasyFlow::Engine.routes.draw do
   namespace :manage do
-    resources :flows, only: [ :index, :create, :show, :edit, :update, :destroy ] do
+    resources :flows, only: [ :index, :new, :create, :show, :edit, :update, :destroy ] do
       resource :definition, only: [ :edit, :update ]
       resource :preview, only: :show, controller: "previews" do
         get :step

data/lib/easy_flow/version.rb

@@ -1,3 +1,3 @@
 module EasyFlow
-  VERSION = "0.8.0"
+  VERSION = "0.9.0"
 end

data/the_local/agents/easy_flow-develop.md

@@ -1,6 +1,6 @@
 ---
 name: easy_flow-develop
-description: Use PROACTIVELY for adding a step type to easy_flow flows (a step that asks the visitor something, takes several answers at once, computes a value from earlier answers, picks the next branch, or holds the visitor until something outside the flow has happened), showing a step differently depending on the visitor's stored run, branching on what a visitor ticked on a checklist, moving a paused run on once what it waits for has happened, refusing a blank or invalid answer to a step with a message, offering an admin a step setting whose options are read from the app's own records, serving a host's flows from the app's own controller and routes, acting when a visitor finishes a flow, and reading a run's recorded answers and question labels, including every answer ticked on a checklist and every visit's answer when a flow loops back to a question already asked — MUST BE USED instead of hand-rolling questionnaire steps, checkbox lists, branching logic, number comparisons, hard-coded setting options, answer validation, polling or "come back later" pages, flow controllers or answer lookups.
+description: Use PROACTIVELY for adding a step type to easy_flow flows (a step that asks the visitor something, takes several answers at once, computes a value from earlier answers, picks the next branch, or holds the visitor until something outside the flow has happened), showing a step differently depending on the visitor's stored run, branching on what a visitor ticked on a checklist, moving a paused run on once what it waits for has happened, refusing a blank or invalid answer to a step with a message, offering an admin a step setting whose options are read from the app's own records, letting an admin edit a value stored on one of the app's own records from a step's settings on the canvas, serving a host's flows from the app's own controller and routes, acting when a visitor finishes a flow, and reading a run's recorded answers and question labels, including every answer ticked on a checklist and every visit's answer when a flow loops back to a question already asked — MUST BE USED instead of hand-rolling questionnaire steps, checkbox lists, branching logic, number comparisons, hard-coded setting options, copying a record's value into a flow and back, answer validation, polling or "come back later" pages, flow controllers or answer lookups.
 tools: Read, Write, Edit, Grep
 scope: guided flows — versioned documents of steps and the connections between them, drawn on a canvas by an admin and run by a visitor one step at a time, with step types the host registers
 ---
@@ -76,7 +76,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
 4. Ask the developer which hosts' admins should be able to add the type. A registered type is in a host's palette, the step types an admin can add on that host's canvas, only when the host names no list of offered step types or its list includes the type's id. A type that declares `ends_here` is in every host's palette, and a type that declares `begins_here` is in none. When a host that names a list should offer the new type, add the type's id to that host's list through `easy_flow-install`. Leaving a type off a host's list only keeps admins from adding it there, and a step of that type already in one of the host's flows is still drawn and run.
 5. Use these words to declare the type. Each is called once at class level (or inside the `EasyFlow.step` block):
    - `step_name "<label>"` — the name admins see on the canvas. Defaults to the id.
-   - `setting :name, type:, label:, options:, required:, limit:, check:, from:, outputs_of:` — a field the admin fills in on the canvas. `type` is one of `:string`, `:integer`, `:float`, `:boolean`, `:select`, `:multi_select`, `:previous_step`, `:from_step`, `:list`, or boot raises `EasyFlow::UnknownFieldType`. A `:select` or `:multi_select` must pass `options:`, or boot raises the same error. `options:` is either an array of strings, or a lambda taking no arguments that returns one; the lambda is called each time the canvas is opened and each time an admin saves the step's settings, so the options follow the app's data without a restart (`options: -> { Region.order(:name).pluck(:code) }`). A saved setting whose value is no longer among the options is refused the next time the admin saves that step. When the options come from the app's records, ask the developer which records, which column is stored as the value, and whether the list must differ by account or host, since the lambda is passed nothing and the same list is offered everywhere the type is used. A `:list` must take a block of `setting` calls describing one entry. `:previous_step` lets the admin pick an earlier step, and is always required. `outputs_of: :<setting>` offers the outputs of the step chosen in that setting, and `from: :<setting>` offers the values of the output chosen in that setting; either one makes the type `:from_step`. `limit:` is the most values a `:multi_select` takes. `check:` is a lambda given the value that returns an error message, or `nil` when the value is acceptable. `label:` defaults to the name humanized.
+   - `setting :name, type:, label:, options:, required:, limit:, check:, from:, outputs_of:, kept_on:, attribute:` — a field the admin fills in on the canvas. `type` is one of `:string`, `:integer`, `:float`, `:boolean`, `:select`, `:multi_select`, `:previous_step`, `:from_step`, `:list`, or boot raises `EasyFlow::UnknownFieldType`. A `:select` or `:multi_select` must pass `options:`, or boot raises the same error. `options:` is either an array of strings, or a lambda taking no arguments that returns one; the lambda is called each time the canvas is opened and each time an admin saves the step's settings, so the options follow the app's data without a restart (`options: -> { Region.order(:name).pluck(:code) }`). A saved setting whose value is no longer among the options is refused the next time the admin saves that step. When the options come from the app's records, ask the developer which records, which column is stored as the value, and whether the list must differ by account or host, since the lambda is passed nothing and the same list is offered everywhere the type is used. A `:list` must take a block of `setting` calls describing one entry. `:previous_step` lets the admin pick an earlier step, and is always required. `outputs_of: :<setting>` offers the outputs of the step chosen in that setting, and `from: :<setting>` offers the values of the output chosen in that setting; either one makes the type `:from_step`. `limit:` is the most values a `:multi_select` takes. `check:` is a lambda given the value that returns an error message, or `nil` when the value is acceptable. `label:` defaults to the name humanized. `kept_on:` and `attribute:` keep the setting's value on one of the app's own records instead of in the flow; see "Keep a setting on one of the app's records".
    - `output :name, type:, label:, values:, from:` — a value the step records. `type` is one of `:string`, `:integer`, `:float`, `:boolean`, or boot raises `EasyFlow::UnknownOutputType`. `values:` is an array or a lambda taking the node, listing the values the output can take; the canvas offers these as the connections leaving the step, so a type that routes must declare them. `from: :<setting>` takes the values from the step chosen in that setting.
    - `names_by :setting` or `names_by { |node| ... }` — what the step is called on the canvas, from a setting or computed.
    - `awaits_input` — the visitor is shown this step and submits an answer to it.
@@ -169,6 +169,28 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
      - The app calls `run.advance` where the event is handled, such as a webhook or a job. See "Read a run and its answers". This needs a stored run, so it only applies to a flow the admin set to save each step.
 9. Restart the server, open a flow on the canvas of each host that should offer the type, and check the type is in the palette, its settings show, and a preview walks through it. On a host that names a list of offered step types without the type's id, check the type is not in the palette.
 
+### Keep a setting on one of the app's records
+
+Use this when an admin should edit a value that belongs to one of the app's own records, such as a customer's name, from a step's settings on the canvas, and the flow should not hold a copy of it.
+
+1. Ask the developer which record holds the value, which of its attributes, and which of the step's other settings identifies the record. Do not pick these.
+2. Ask the developer which admins may change which records. The finder below is given only the step's settings, not the admin, the host or the owner, so an admin who can type an id into a setting can reach any record the finder will find. If records must be limited to one account or host, stop and ask how the finder can tell, since it has nothing else to read.
+3. Declare the setting with `kept_on:`, a lambda given the step's settings as a hash with string keys that returns the record or `nil`, and `attribute:`, the record's attribute that holds the value. `attribute:` defaults to the setting's name:
+
+   ```ruby
+   setting :customer, type: :string
+   setting :customer_name, type: :string, kept_on: ->(config) { Customer.find_by(id: config["customer"]) }, attribute: :name
+   ```
+
+4. What then holds:
+   - The canvas shows the value read from the record each time it draws the step, or a blank when the finder returns `nil`.
+   - When the admin saves the step's settings, the value is written to the record with `update` at that moment, before the flow is published, and on every save of that step whether or not the value changed. The setting's `type`, `required:` and `check:` are applied first.
+   - When the finder returns `nil`, nothing is written and the save goes on.
+   - When the record refuses the value, the save is refused with the setting's label followed by the record's own error, such as `Customer name is too long (maximum is 40 characters)`. None of the step's kept settings are written and none of its other settings are saved. This holds when the app already has a transaction open.
+   - The value is never stored in the flow's document or its versions, so publishing, undo and a run's pinned version never hold or change it.
+   - `node.config` in `process`, `route`, `waits_until`, `answer_check`, `names_by` and `displays_by` does not hold a kept setting. A step that needs the value reads it from the record.
+5. Restart the server, open a flow on the canvas, add a step of the type, save a value, and check the record holds it and that a value the record refuses shows its error.
+
 ### Serve a host's flows from the app's own controller
 
 1. Ask the developer which host this controller serves, what path the visitor pages live under, and what should happen when a visitor finishes. Do not choose the finish behaviour for them.
@@ -239,6 +261,8 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
 - Registering a type does not put it in the palette of a host that names a list of offered step types without the type's id. Which step types a host offers is set through `easy_flow-install`, not here.
 - A type that declares `ends_here` is in every host's palette, and a type that declares `begins_here` is in no host's palette.
 - An `options:` lambda is passed nothing, and one list is offered on every host's canvas, so it cannot narrow the options by admin, account or host.
+- A setting declared with `kept_on:` lives only on the app's record, written when the admin saves the step, so a step's code never finds it in `node.config`.
+- A `kept_on:` lambda is given only the step's settings, so it cannot limit which records an admin reaches by admin, account or host.
 - A type that routes declares the values its output takes, or the canvas offers no connections to label.
 - Always read a run against `run.pinned_definition`, never the flow's live version, since a run keeps the version it started on after a new one is published.
 - Always look flows and runs up through a host.

data/the_local/agents/easy_flow-info.md

@@ -1,6 +1,6 @@
 ---
 name: easy_flow-info
-description: Use to learn what easy_flow offers — guided flows an admin draws on a canvas and a visitor runs one step at a time, versioned documents of steps and connections, flows that loop back to ask a step again, hosts and the step types each offers its admins, runs, the built-in step types including questions and checklists that can require an answer and explain each answer behind an info button, and branching on an answer or comparing a number, step types the host app registers, the checks they make on an answer, what a step shows a visitor and how that can depend on the visitor's run, and steps that hold a run until something outside the flow has happened, and the settings an admin fills in, including picks whose options come from the app's data.
+description: Use to learn what easy_flow offers — guided flows an admin draws on a canvas and a visitor runs one step at a time, versioned documents of steps and connections, flows that loop back to ask a step again, hosts and the step types each offers its admins, runs, the built-in step types including questions and checklists that can require an answer and explain each answer behind an info button, and branching on an answer or comparing a number, step types the host app registers, the checks they make on an answer, what a step shows a visitor and how that can depend on the visitor's run, and steps that hold a run until something outside the flow has happened, and the settings an admin fills in, including picks whose options come from the app's data and settings kept on one of the app's own records.
 tools: Read
 scope: guided flows — versioned documents of steps and the connections between them, drawn on a canvas by an admin and run by a visitor one step at a time, with step types the host registers
 ---
@@ -18,12 +18,12 @@ Reach for it when an app needs a questionnaire, an intake form, or any decision
 easy_flow declares no commands of its own for this local. Its surface is split between the other two:
 
 - **easy_flow-install** owns putting the engine into an app: its migrations, mounting it, choosing the controller it inherits from, naming hosts and the step types each one offers, choosing the default step drawing, the flow checks, and the admin pages.
-- **easy_flow-develop** owns building on it: declaring and registering step types, including ones that wait, moving a run on once what it waits for has happened, serving a host's flows from the app's own controllers and routes, and reading a visitor's run and answers.
+- **easy_flow-develop** owns building on it: declaring and registering step types, including ones that wait and ones with settings kept on the app's own records, moving a run on once what it waits for has happened, serving a host's flows from the app's own controllers and routes, and reading a visitor's run and answers.
 
 ## How to use it
 
 - To get easy_flow running in an app, or to change how it is configured, including which step types a host's admins can add, use **easy_flow-install**.
-- To add a step type, give a step type its own rule for refusing an answer, make what a step shows depend on the visitor's run, hold a run until something outside the flow has happened, put a flow on the app's own pages, or act on what a visitor answered, use **easy_flow-develop**.
+- To add a step type, give a step type its own rule for refusing an answer, make what a step shows depend on the visitor's run, hold a run until something outside the flow has happened, keep a step's setting on one of the app's own records, put a flow on the app's own pages, or act on what a visitor answered, use **easy_flow-develop**.
 - To branch a flow on an answer or on a number the visitor gave, no code is needed: an admin places one of the built-in branching steps on the canvas.
 - To make a visitor answer a question or tick something on a checklist before going on, no code is needed: an admin marks that step as required on the canvas.
 - To let a visitor tick several answers on one step, no code is needed: an admin places a checklist step on the canvas.
@@ -43,6 +43,7 @@ easy_flow declares no commands of its own for this local. Its surface is split b
 - **Answer check** — a rule a step type may carry that looks at a visitor's answer and, when the answer is not acceptable, returns the message the visitor sees. A step type with no such rule accepts every answer.
 - **Setting** — one field an admin fills in when configuring a step on the canvas. It is text, a whole number, a decimal, a yes or no, a pick from a list, several picks from a list, an earlier step, an earlier step's output, or a list of entries that each hold their own fields. A setting can be required, limited to a number of picks, or checked by a rule the step type supplies.
 - **Options** — the values a pick-from-a-list setting offers. They are either a fixed list written into the step type, or a lookup the app provides that is read each time the canvas or a save asks for them, so they can come from the app's own data. A saved value that is not among the options is refused.
+- **Kept setting** — a setting whose value lives on one of the app's own records rather than in the flow. The step type says how to find that record from the step's other settings and which of its attributes holds the value. The canvas shows the value read from the record, and saving the step's settings writes it straight to the record, so the flow's document and its versions never hold it and undo or publishing does not change it. When no record is found, nothing is written. When the record refuses a value, the save is refused with the record's own error and none of the step's kept settings are written.
 - **Output** — a value a step records into the run, with a type and a label. Later steps read outputs, and a setting that points at an earlier step offers that step's known values on the canvas.
 - **Start** and **End** — the built-in step types that begin and finish a flow.
 - **Question** — the built-in step type that asks the visitor: a question text, an optional category, a yes-or-no required setting, and a list of answers, each with a value, a label, a weight, a hint and an info. The visitor picks one answer, and that answer's value is recorded.

data/the_local/agents/easy_flow-install.md

@@ -1,6 +1,6 @@
 ---
 name: easy_flow-install
-description: Use to hook easy_flow into a project — copying and running its migrations, mounting the engine for each host, setting the controller it inherits from, declaring hosts with their layouts, access methods and the step types each offers, choosing the default step drawing, turning on optional checks, and reaching the admin pages.
+description: Use to hook easy_flow into a project — copying and running its migrations, mounting the engine for each host, setting the controller it inherits from, declaring hosts with their layouts, access methods, the record that owns their flows and the step types each offers, choosing the default step drawing, turning on optional checks, and reaching the admin pages.
 tools: Bash, Read, Edit
 scope: guided flows — versioned documents of steps and the connections between them, drawn on a canvas by an admin and run by a visitor one step at a time, with step types the host registers
 ---
@@ -16,7 +16,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
 - `bin/rails easy_flow:install:migrations` — copies the engine's migrations into the host's `db/migrate`, creating the flow, version and run tables.
 - `mount EasyFlow::Engine` — the route that serves one host's visitor pages and admin pages under a path, with the host named in `defaults: { easy_flow_host: "<host>" }`.
 - `EasyFlow.base_controller=` — the name, as a string, of the host controller every engine controller inherits from. Defaults to `"ActionController::Base"`.
-- `EasyFlow.host` — declares a named host with its visitor layout, admin layout, admin authentication method, visitor authorization method, refusal method, and the step types its admins can add on the canvas.
+- `EasyFlow.host` — declares a named host with its visitor layout, admin layout, admin authentication method, visitor authorization method, refusal method, owner method, and the step types its admins can add on the canvas.
 - `EasyFlow.draws_with` — the partial that draws a visitor's step when the step's type names none. Defaults to the engine's own `easy_flow/steps/choosing`.
 - `EasyFlow.check` — turns on an optional flow check: `:unrouted_value`, `:unfollowed_path` or `:dead_end`.
 - `/manage/flows` — the admin pages, under each mount path, where flows are listed, created, drawn on the canvas, previewed and published.
@@ -26,7 +26,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
 1. Confirm the app has Keystone UI installed (`keystone_ui` in the Gemfile). easy_flow's controllers use its helpers and it is not pulled in by easy_flow. If it is missing, stop and hand off to the `keystone_ui-install` local before continuing.
 2. Read the `keystone_ui` version in the app's `Gemfile.lock`. easy_flow's visitor pages pass each answer's info text to Keystone UI's radio cards and checkbox rows, and easy_flow is built against `keystone_ui` 0.27.0. If the app's version is older, ask the developer whether to run `bundle update keystone_ui` before continuing.
 3. Add `gem "easy_flow"` to the host's `Gemfile` and run `bundle install`.
-4. Run `bin/rails easy_flow:install:migrations`, then `bin/rails db:migrate`. This writes four migrations into `db/migrate` and updates `db/schema.rb`.
+4. Run `bin/rails easy_flow:install:migrations`, then `bin/rails db:migrate`. This writes five migrations into `db/migrate` and updates `db/schema.rb`.
 5. Ask the developer which hosts the app needs. A host is one part of the app that owns its own set of flows, and one host never sees another's flows. Ask for each host's name and the path it is served under.
 6. Ask the developer which controller the engine should inherit from. Choosing `"ApplicationController"` gives the engine the app's own authentication methods and helpers. Create `config/initializers/easy_flow.rb` and set it on the first line:
 
@@ -43,6 +43,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
      host.admin_authentication_method = :authenticate_admin!
      host.visitor_authorization_method = :easy_flow_visitor_permitted?
      host.refusal_method = :refuse_flow
+     host.owner_method = :current_account
      host.offers = %i[question checklist condition switch compare]
    end
    ```
@@ -52,6 +53,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
    - `admin_authentication_method` — a method on the base controller, called with no arguments before every admin page. With none set, the admin pages are open to anyone.
    - `visitor_authorization_method` — a method on the base controller, called with the flow, returning true when the visitor may run it. With none set, every visitor is refused.
    - `refusal_method` — a method on the base controller, called with the refusal error when a visitor is refused or a flow is unpublished or withdrawn. With none set, the response is `404 Not Found`.
+   - `owner_method` — a method on the base controller, called with no arguments, returning the record whose flows the current request works with, such as the signed-in account. When set, the admin pages list, create and edit only that record's flows, a visitor runs only that record's flows, and two records may each hold a flow with the same slug. With none set, every flow in the host is shared by everyone who reaches it. Ask the developer whether each host's flows belong to one record or are shared.
    - `offers` — the step types this host's admins can add from the canvas palette, as a list of step type names. With none set, every registered step type is offered. The engine's own names are `question`, `checklist`, `condition`, `switch` and `compare`. A step type the app declares is named by the id passed to `EasyFlow.step`, or after its class when it is a step class, so `Steps::Notify` is `notify`. The End step is offered whether it is listed or not, and the Start step is never offered. Ask the developer which step types each host should offer.
 
    Each method named here must exist on the base controller. Ask the developer to point at it or write it. Do not invent its logic.
@@ -84,7 +86,8 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
 - After publishing a flow with a question or a checklist whose answer has info text, check that the visitor's page shows an info button on that answer. If it does not, compare the app's `keystone_ui` version with the one in step 2.
 - After publishing a flow with a checklist, check that a visitor can tick several answers and go on, and that a checklist marked required refuses to go on with nothing ticked.
 - After upgrading easy_flow, run `bin/rails easy_flow:install:migrations` again and then `bin/rails db:migrate`. Only migrations the app does not already have are copied.
+- After setting a host's `owner_method`, check that two different owners each see only their own flows on `<mount path>/manage/flows`.
 - After setting a host's `offers`, check that the canvas palette on that host's `<mount path>/manage/flows` lists only those step types and End.
 - Taking a step type off a host's `offers` removes it from the palette only. Steps of that type already in the host's flows stay in them and keep running.
 - The initializer runs once at boot, so a change to it needs a server restart.
-- Declaring step types, serving a host's flows from the app's own controllers and routes, and reading runs and answers are out of scope here. They belong to the `easy_flow-develop` local.
+- Declaring step types, including settings kept on the app's own records, serving a host's flows from the app's own controllers and routes, and reading runs and answers are out of scope here. They belong to the `easy_flow-develop` local.

data/the_local/interface.yml

@@ -29,6 +29,9 @@ sources:
   - app/controllers/easy_flow/manage/base_controller.rb
   - app/models/easy_flow/step.rb
   - app/models/easy_flow/step_type/declaration.rb
+  - app/models/easy_flow/settings.rb
+  - app/models/easy_flow/canvas.rb
+  - app/controllers/easy_flow/manage/canvas_controller.rb
   - app/models/easy_flow/steps/question.rb
   - app/models/easy_flow/steps/checklist.rb
   - app/models/easy_flow/step_type.rb

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: easy_flow
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - tylercschneider
@@ -127,6 +127,7 @@ files:
 - app/views/easy_flow/manage/definitions/edit.html.erb
 - app/views/easy_flow/manage/flows/edit.html.erb
 - app/views/easy_flow/manage/flows/index.html.erb
+- app/views/easy_flow/manage/flows/new.html.erb
 - app/views/easy_flow/manage/flows/show.html.erb
 - app/views/easy_flow/manage/versions/index.html.erb
 - app/views/easy_flow/steps/_choosing.html.erb