% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/block-eval.R, R/block-server.R
\name{block_eval}
\alias{block_eval}
\alias{eval_env}
\alias{block_eval_trigger}
\alias{block_server}
\alias{block_server.block}
\alias{expr_server}
\alias{block_render_trigger}
\title{Block server}
\usage{
block_eval(x, expr, env, ...)

eval_env(data)

block_eval_trigger(x, session = get_session())

block_server(id, x, data = list(), ...)

\method{block_server}{block}(
  id,
  x,
  data = list(),
  block_id = id,
  edit_block = NULL,
  ctrl_block = NULL,
  board = reactiveValues(),
  update = reactiveVal(),
  inputs_ready = reactive(TRUE),
  ...
)

expr_server(x, data, ...)

block_render_trigger(x, session = get_session())
}
\arguments{
\item{x}{Object for which to generate a \code{\link[shiny:moduleServer]{shiny::moduleServer()}}}

\item{expr}{Quoted expression to evaluate in the context of \code{data}}

\item{env}{Environment in which to evaluate \code{expr}}

\item{...}{Generic consistency}

\item{data}{Input data (list of reactives)}

\item{session}{Shiny session object}

\item{id}{Namespace ID}

\item{block_id}{Block ID}

\item{edit_block, ctrl_block}{Block plugins}

\item{board}{Reactive values object containing board information}

\item{update}{Reactive value object to initiate board updates}

\item{inputs_ready}{Reactive flag signaling whether the block's required
inputs are all connected to ready upstream blocks (supplied by
\code{\link[=board_server]{board_server()}}; defaults to always-ready when a block server is run
standalone)}
}
\value{
Both \code{block_server()} and \code{expr_server()} return shiny server module
(i.e. a call to \code{\link[shiny:moduleServer]{shiny::moduleServer()}}), while \code{block_eval()} evaluates
an interpolated (w.r.t. block "user" inputs) block expression in the context
of block data inputs.
}
\description{
A block is represented by several (nested) shiny modules and the top level
module is created using the \code{block_server()} generic. S3 dispatch is offered
as a way to add flexibility, but in most cases the default method for the
\code{block} class should suffice at top level. Further entry points for
customization are offered by the generics \code{expr_server()} and \code{block_eval()},
which are responsible for initializing the block "expression" module (i.e.
the block server function passed in \code{\link[=new_block]{new_block()}}) and block evaluation
(evaluating the interpolated expression in the context of input data),
respectively.
}
\details{
The module returned from \code{block_server()}, at least in the default
implementation, provides much of the essential but block-type agnostic
functionality, including data input validation (if available), instantiation
of the block expression server (handling the block-specific functionality,
i.e. block user inputs and expression), and instantiation of the
\code{edit_block} module (if passed from the parent scope).

Each block carries an \emph{eval status} -- one of \code{dormant}, \code{waiting}, \code{unset},
\code{failed} or \code{ready} -- which, together with the orthogonal \code{visible} flag,
determines its behaviour. The status separates the two input kinds (data
inputs from links, user inputs from \code{state}) and a genuine failure:
\itemize{
\item \code{dormant} -- not \emph{needed} (neither on screen nor feeding, transitively over
\code{\link[=board_links]{board_links()}}, an on-screen block); inputs stay unfulfilled
(\code{\link[shiny:req]{shiny::req()}} out) and nothing evaluates.
\item \code{waiting} -- needed, but a required \emph{data} input is missing: unconnected,
below the required number of variadic \code{...args} inputs (one by default),
or fed by an upstream block that is not itself \code{ready} (see
\code{allow_empty_state}).
\item \code{unset} -- data inputs are ready, but a required \emph{user} input (\code{state}
value) has not been provided (unless permitted by \code{allow_empty_state}).
\item \code{failed} -- all inputs are present, but the block cannot produce a result:
the data validator (\code{\link[=validate_data_inputs]{validate_data_inputs()}}) or the block expression
raised. The offending condition is surfaced through the block conditions.
\item \code{ready} -- evaluation succeeded and a result (possibly a legitimate \code{NULL})
is available for downstream blocks to consume.
}

A block reaches \code{ready} only once its upstreams have, so an unconnected or
pending block holds its whole downstream chain \code{waiting} without any of them
evaluating against missing data. Output rendering follows the status: the
block output is shown only while \code{ready} and cleared otherwise, so a block
leaving \code{ready} never displays a stale result. While not \code{ready} the block
surfaces a condition explaining why -- a \code{status}-phase note for \code{waiting}
and \code{unset}, or the raised error for \code{failed}. Conditions raised during
validation and evaluation are caught and returned to be surfaced to the app
user.

Block-level user inputs (provided by the expression module) are separated
from output, the behavior of which can be customized via the
\code{\link[=block_output]{block_output()}} generic. The \code{\link[=block_ui]{block_ui()}} generic can then be used to
control rendering of outputs.

When a front-end (such as blockr.dock) drives the \code{visible} write-channel
that \code{\link[=board_server]{board_server()}} hands to the board callback, reporting each block's
visibility status (off screen, on screen, or rendered into its view),
evaluation and rendering are gated on visibility.
Rendering is gated on plain visibility: the render observer is suspended
while a block is off screen and resumed once it is on screen, starting
suspended so nothing renders before the front-end first reports. Evaluation
is gated on the \emph{needed} set, the on-screen blocks together with their
upstream closure over \code{\link[=board_links]{board_links()}} (derived from \code{visible}, recomputed
only when it or the links change). A block's input data reactives stay
unfulfilled (they \code{\link[shiny:req]{shiny::req()}} out) unless the block is needed, so a block
that is neither visible nor feeding a visible block pulls no input and stays
fully quiescent: its result reactive, and any observer its expression server
registers on the incoming data, all short-circuit and do nothing. A needed
but off-screen block (one feeding a visible block) evaluates but does not
render. Block-server \emph{construction} is prioritized the same way: the needed
set is instantiated first so that first paint waits only for the on-screen
blocks and their upstreams, and the remaining block servers are built
progressively in the background. That background pass holds until the
front-end reports every on-screen block as rendered (arranged into its
view), so it never competes with first paint. Until a block is built it is
absent from
the \code{board$blocks} handed to plugins and callbacks, which simply see it
appear once constructed. The background cadence is set by the
\code{background_construction_delay} \code{\link[=blockr_option]{blockr_option()}} (milliseconds between
successive blocks, default 50); a value of 0 disables the staggering and
builds every block up front. With nothing driving
\code{visible} every block is needed and behaviour is unchanged; the
\code{gate_visibility} \code{\link[=blockr_option]{blockr_option()}} (default \code{TRUE}) turns gating off
entirely.
}
