A rendered program as a pure value: its state store, form fields, query results and mutations, with the interactions of language.md, sections 5 and 6.
Functions that may cause something outside the program to happen return
{runtime, effects}. The host runs the effects and reports back:
{:emit, %OpenUI.Event{}}: an action for the host or the model;{:run_query, query_id, tool, args}: call the tool, thenquery_result/4;{:run_mutation, run_ref, tool, args}: call the tool, thenmutation_result/3;{:schedule_refresh, query_id, seconds}: callrefresh/2later. A new one for the same query replaces the pending one: keep one timer per query.
Which components are fields and which give a form name to their subtree is up to each platform (prompt.md, section 2.6), so the runtime takes it as options:
OpenUI.Runtime.new(MyApp.Library,
fields: %{"Input" => [name: "name", type: "input"]},
forms: %{"Form" => "name"}
)A field option may add rules: "rules", the prop holding its validation
rules ("rules" by default).
Summary
Functions
The rule a field failed at the latest submit, or nil.
The current value of a field element: its bound $variable, or its entry
in the form or page state.
Marks the end of the stream: every query runs.
The name of the nearest form around an element, or nil.
The person changed a field. A bound prop writes its $variable; a field
without a binding writes into its form, or the page when it has none.
Loads a program, from a stream frame or an edit. Declared defaults apply to
state the person has not changed; no key is ever deleted. Nothing runs
until finish/1.
The tool answered a mutation started by {:run_mutation, run_ref, ...}.
On success the rest of its action plan runs; on failure it stops.
Starts a runtime. Options: :fields, :forms and :state, the state a
host persisted earlier, applied over the program's defaults.
The tool answered a query. A result for arguments that are no longer the
query's current ones is discarded. {:error, {:tool_not_found, names}}
reports tool-not-found with the available names; any other error
reports tool-error. Either way the query keeps its last good data.
Fetch state of the queries, for a loading indicator and error display.
Fetches a query again, as its refresh interval asks.
The errors the latest evaluation reported.
Starts over for a new response in the same place: a new stream, the given
persisted state, no queries or mutations. The errors already reported are
kept, so take_errors/2 clears them with [] (language.md, section 8.3).
The state store: $variables with their values, form names with their
fields, page-level fields at the top, each field as %{"value", "componentType"}. This is what a host persists.
The error list to send to the host, only when it changed since the last
call (language.md, section 8.3). While a stream is open nothing is
reported, and a list left from an earlier stream is cleared with [].
renderer_errors are errors the host's renderer adds, such as a component
that raised.
The evaluated tree, with a key on every element.
Runs the action plan in a prop of an element. Inside a form, a plan that
sends something (@ToAssistant, a library action or a mutation) runs only
when every field of the form passes its rules.
Types
Functions
The rule a field failed at the latest submit, or nil.
The current value of a field element: its bound $variable, or its entry
in the form or page state.
Marks the end of the stream: every query runs.
The name of the nearest form around an element, or nil.
The person changed a field. A bound prop writes its $variable; a field
without a binding writes into its form, or the page when it has none.
@spec load(t(), OpenUI.Program.t()) :: {t(), [effect()]}
Loads a program, from a stream frame or an edit. Declared defaults apply to
state the person has not changed; no key is ever deleted. Nothing runs
until finish/1.
The tool answered a mutation started by {:run_mutation, run_ref, ...}.
On success the rest of its action plan runs; on failure it stops.
@spec new(OpenUI.Library.t() | module(), keyword()) :: t()
Starts a runtime. Options: :fields, :forms and :state, the state a
host persisted earlier, applied over the program's defaults.
The tool answered a query. A result for arguments that are no longer the
query's current ones is discarded. {:error, {:tool_not_found, names}}
reports tool-not-found with the available names; any other error
reports tool-error. Either way the query keeps its last good data.
@spec query_status(t()) :: %{ loading?: boolean(), refetching?: boolean(), errors: [OpenUI.Error.t()] }
Fetch state of the queries, for a loading indicator and error display.
Fetches a query again, as its refresh interval asks.
@spec render_errors(t()) :: [OpenUI.Error.t()]
The errors the latest evaluation reported.
Starts over for a new response in the same place: a new stream, the given
persisted state, no queries or mutations. The errors already reported are
kept, so take_errors/2 clears them with [] (language.md, section 8.3).
The state store: $variables with their values, form names with their
fields, page-level fields at the top, each field as %{"value", "componentType"}. This is what a host persists.
@spec take_errors(t(), [OpenUI.Error.t()]) :: {t(), :unchanged | {:changed, [OpenUI.Error.t()]}}
The error list to send to the host, only when it changed since the last
call (language.md, section 8.3). While a stream is open nothing is
reported, and a list left from an earlier stream is cleared with [].
renderer_errors are errors the host's renderer adds, such as a component
that raised.
@spec tree(t()) :: OpenUI.Element.t() | nil
The evaluated tree, with a key on every element.
Runs the action plan in a prop of an element. Inside a form, a plan that
sends something (@ToAssistant, a library action or a mutation) runs only
when every field of the form passes its rules.