easy_flow 0.32.1 → 0.34.0

data/the_local/agents/easy_flow-install.md

@@ -20,6 +20,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
 - `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.file_store` — the object that keeps a file a visitor uploads at a File upload step and names it again later. Defaults to none, and with none set an uploaded file is refused with `EasyFlow::NoFileStore`.
 - `EasyFlow.picture_store` — the object that keeps a picture an admin adds to a question step on the canvas, for the flow it belongs to, and gives the address the picture is loaded from. Defaults to none, and with none set an admin who chooses a picture is told pictures cannot be added yet.
+- `EasyFlow.data_source` — the object that says what Read data and Write data steps can read and write, and carries each one out. Defaults to none, and with none set those steps offer no choices.
 - `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.
 
@@ -46,7 +47,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
      host.visitor_authorization_method = :easy_flow_visitor_permitted?
      host.refusal_method = :refuse_flow
      host.owner_method = :current_account
-     host.offers = %i[question checklist multiple_select fill_in_the_blank file_upload condition switch compare compare_two_values all_or_any count wait flow_step]
+     host.offers = %i[question checklist multiple_select fill_in_the_blank file_upload condition switch compare compare_two_values all_or_any count read_data write_data wait flow_step]
    end
    ```
 
@@ -57,6 +58,10 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
    - `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`, `multiple_select`, `fill_in_the_blank`, `file_upload`, `condition`, `switch`, `compare`, `compare_two_values`, `all_or_any`, `count`, `wait`, `flow_step` and `play_flows`, `file_upload` being the File upload step, which needs the file store from step 10, `compare_two_values` being the Compare two values step, which compares the outputs of two earlier steps, `all_or_any` being the All of or Any of step, which decides whether all or any of several such comparisons hold, `count` being the Count step, which counts how often an earlier step was answered, `wait` being the Wait step, which holds a run until a time counted from an earlier answer or until a date, `flow_step` being the Flow step, which names one of the same host's flows, and `play_flows` being the Play flows step, which lists several of the same host's flows for a visitor to play in the order they choose. A step type the app declares is named by the id it was declared with, 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.
+   - `always_show_insert_buttons` — set to `true` to show each connection's button for inserting a step on this host's canvas without the pointer over the connection. A connection's label then sits to the right of the line so the button does not cover it. With none set, the button shows only with the pointer over the connection.
+   - `hide_step_type_codes` — set to `true` to hide step type code names on this host's canvas. The add menu then lists each step type by its name alone, and a step's box shows its step type's name in place of the code name. With none set, the add menu and step boxes show the code names. The settings panel shows a step's id and code name either way.
+   - `publish_note` — a sentence shown directly under the Publish button in this host's flow panel. It is shown as plain text. With none set, the panel shows no note.
+   - `back_link` — a hash with a `label` and an `address`, such as `{ label: "Games", address: "/admin/games" }`, that shows a button with that label and address in this host's builder header in place of `All flows`. The header then has no `All flows` button. A hash missing either key raises `ArgumentError` when the host is declared, and a blank value is not refused. The address is used as written and is not checked, so it comes from the app's own configuration and never from a request. With none set, the header shows `All flows`.
 
    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.
 8. Mount the engine in `config/routes.rb`, once per host. The host name in `defaults` must match a name declared in step 7. When there is more than one mount, give each an `as:` name:
@@ -100,14 +105,26 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
     - The store answers `url_of(reference)`, called with a reference `keep` returned. It returns the address a page loads the picture from.
     - The store refuses a file it will not keep, such as one that is not an image or is too large, by raising `EasyFlow::PictureRefused` with the message the admin should see. The canvas shows that message and leaves the step's picture as it was.
     - With no store set, an admin who chooses a picture on the canvas is told "Pictures cannot be added yet. Ask the app's developer to set up a picture store." and the step is left unchanged.
-11. Leave `EasyFlow.check` out unless the developer asks for it. The engine already turns on `:unrouted_value`, `:unfollowed_path` and `:dead_end` at boot. Any other name raises `EasyFlow::UnknownCheck` when the app boots.
-12. Check that the app loads Active Job (`require "rails/all"` or `require "active_job/railtie"` in `config/application.rb`) and has a queue adapter that runs jobs from the `default` queue. When a run started by a Flow step, or by a step type of the app's own that starts another flow, ends, the engine records its output in the run it was started from and queues a job on `default` that moves that run on. If no adapter runs that queue, the run that holds the step stays at it until its visitor next loads its page. If `config.active_job.queue_adapter` is not set for an environment, ask the developer which adapter to use there.
-13. Check `config.time_zone` in `config/application.rb`. A Wait step's time of day and date, and the "Hour completed" and "Weekday completed" outputs every completed step offers, are read in that zone, and with none set it is UTC. If it is not set, ask the developer which zone the app's admins mean when they write a time.
-14. Start the server and open `<mount path>/manage/flows` for each host.
+11. Ask the developer whether any host will offer the Read data or Write data step, and if so, what a flow may read and write and how the app carries each one out. Set the object that answers in the initializer:
+
+    ```ruby
+    EasyFlow.data_source = FlowData.new
+    ```
+
+    - The object answers `reads`, a list of strings naming what a flow can read.
+    - The object answers `writes`, a list of strings naming what a flow can write.
+    - The object answers `carry_out(name, values)`, called with one of those names and a hash of the step's input values, with string keys as the admin named them. What it returns is the step's answer. What it raises is the step's failure.
+    - A step whose name is no longer on its list records a failure and does not call `carry_out`.
+    - Read data and Write data need a flow that keeps every answer as it is given. In a flow that keeps nothing or keeps the run only once it finishes, the visitor is told "Data can only be read or written in a flow that saves its runs." when the run reaches the step and cannot go on, and the app is not called.
+12. Leave `EasyFlow.check` out unless the developer asks for it. The engine already turns on `:unrouted_value`, `:unfollowed_path` and `:dead_end` at boot. Any other name raises `EasyFlow::UnknownCheck` when the app boots.
+13. Check that the app loads Active Job (`require "rails/all"` or `require "active_job/railtie"` in `config/application.rb`) and has a queue adapter that runs jobs from the `default` queue. When a run started by a Flow step, or by a step type of the app's own that starts another flow, ends, the engine records its output in the run it was started from and queues a job on `default` that moves that run on. If no adapter runs that queue, the run that holds the step stays at it until its visitor next loads its page. If `config.active_job.queue_adapter` is not set for an environment, ask the developer which adapter to use there.
+14. Check `config.time_zone` in `config/application.rb`. A Wait step's time of day and date, and the "Hour completed" and "Weekday completed" outputs every completed step offers, are read in that zone, and with none set it is UTC. If it is not set, ask the developer which zone the app's admins mean when they write a time.
+15. Start the server and open `<mount path>/manage/flows` for each host.
 
 ## Conventions
 
 - After install, check that `<mount path>/manage/flows` shows the flow list and that a new flow opens on the canvas. If the canvas is blank, check that the admin layout calls `yield :head`.
+- After install, add a step to a flow without connecting it and press Publish. Check that the flow panel names the step, that Cancel changes nothing, and that accepting publishes the flow without it and the history shows `Removed unconnected` with its name.
 - After publishing a flow, check that `<mount path>/<slug>` shows it to a visitor who passes the host's visitor authorization method.
 - 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 install, check that an End step selected on the canvas shows an output setting. An admin fills it in on each End step, and it needs no migration and no setting in the initializer.
@@ -145,6 +162,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
 - After filling in a Wait step, check its name on the canvas. With a date set it is named by the date alone, and the run waits until that date. Otherwise, with a time of day set, it is named by that time followed by "after" and the step it counts from, and the run waits until that time of day first comes after the step was answered. Otherwise it is named by the minutes, as "1 minute after" or "<n> minutes after" followed by the step it counts from, and the run waits that many minutes past the answer. With none of the three set it has no name of its own, and a visitor held at it sees "Waiting for Wait."
 - The engine queues no job for a Wait step. After publishing a flow with a Wait step, check that a visitor held at it sees "Waiting for" followed by the step's name, and that a stored run moves on when the visitor's page is loaded after its time has come. Moving a run on with no visitor present belongs to the `easy_flow-develop` local.
 - After publishing a flow with a Wait step whose "What this keeps of a run" detail is "Nothing" or "The whole run once it finishes", check that a visitor held at it sees a "Check again" button, and that pressing it after the time has come carries their answers and completion times forward and moves them past the Wait step.
+- After setting `EasyFlow.data_source`, check that a Read data step on the canvas offers the object's `reads` and a Write data step offers its `writes`. Publish a flow set to save each step, connect each step's `passed` and `failed` connections, and check a run follows `passed` when `carry_out` answers and `failed` when it raises.
 - After setting `EasyFlow.file_store`, publish a flow with a File upload step whose "What this keeps of a run" detail is "Every answer as it is given", upload a file as a visitor, and check that the completion page shows the name the store gives it.
 - A File upload step takes a file only in a flow that keeps every answer as it is given. In a flow that keeps nothing or keeps the run only once it finishes, the visitor is told "A file can only be uploaded in a flow that saves its runs." and cannot go on with a file chosen.
 - A File upload step's "Accepted file types" setting is a comma-separated list of extensions, such as `.pdf, .png`. A file of another kind is refused with a message naming the accepted kinds and is never passed to the file store.

data/the_local/interface.yml

@@ -8,6 +8,7 @@ install:
   - EasyFlow.draws_with
   - EasyFlow.file_store
   - EasyFlow.picture_store
+  - EasyFlow.data_source
   - EasyFlow.check
   - /manage/flows
 
@@ -16,6 +17,7 @@ develop:
   - EasyFlow.step
   - labels_answer_by
   - outputs_named_by
+  - EasyFlow::Inputs
   - host.allowed_answers=
   - EasyFlow::FlowsController
   - hosted_by
@@ -48,6 +50,10 @@ sources:
   - app/models/easy_flow/count.rb
   - app/models/easy_flow/compare_two_values.rb
   - app/models/easy_flow/all_or_any.rb
+  - app/models/easy_flow/read_data.rb
+  - app/models/easy_flow/write_data.rb
+  - app/models/easy_flow/data_step.rb
+  - app/models/easy_flow/inputs.rb
   - app/models/easy_flow/wait.rb
   - app/models/easy_flow/completed_at.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.32.1
+  version: 0.34.0
 platform: ruby
 authors:
 - tylercschneider
@@ -112,6 +112,7 @@ files:
 - app/models/easy_flow/completed_at.rb
 - app/models/easy_flow/condition.rb
 - app/models/easy_flow/count.rb
+- app/models/easy_flow/data_step.rb
 - app/models/easy_flow/definition.rb
 - app/models/easy_flow/digest.rb
 - app/models/easy_flow/document.rb
@@ -119,6 +120,7 @@ files:
 - app/models/easy_flow/edge.rb
 - app/models/easy_flow/edit_history.rb
 - app/models/easy_flow/flow_step.rb
+- app/models/easy_flow/inputs.rb
 - app/models/easy_flow/layout.rb
 - app/models/easy_flow/name.rb
 - app/models/easy_flow/node.rb
@@ -128,6 +130,7 @@ files:
 - app/models/easy_flow/progress/kept.rb
 - app/models/easy_flow/progress/loose.rb
 - app/models/easy_flow/question_runner.rb
+- app/models/easy_flow/read_data.rb
 - app/models/easy_flow/registry.rb
 - app/models/easy_flow/run.rb
 - app/models/easy_flow/runner.rb
@@ -143,11 +146,14 @@ files:
 - app/models/easy_flow/steps/question.rb
 - app/models/easy_flow/switch.rb
 - app/models/easy_flow/terminal.rb
+- app/models/easy_flow/unconnected_steps.rb
 - app/models/easy_flow/validator.rb
 - app/models/easy_flow/version.rb
 - app/models/easy_flow/violation.rb
 - app/models/easy_flow/wait.rb
+- app/models/easy_flow/write_data.rb
 - app/views/easy_flow/flows/complete.html.erb
+- app/views/easy_flow/flows/refused.html.erb
 - app/views/easy_flow/flows/show.html.erb
 - app/views/easy_flow/flows/step.html.erb
 - app/views/easy_flow/manage/definitions/edit.html.erb