PhoenixLiveViewExt.Listilled behaviour (phoenix_live_view_ext v1.2.2) View Source
Listilled behaviour should be implemented by the modules (e.g. LiveView components) assuming the concern of their state-to-assigns transformation where such assigns then need to get compared and diffed (listilled) by the Listiller before getting actually assigned for the LiveComponent list rendering. This is to avoid updating (replacing) the appended (or prepended) container list with elements that haven't really changed which for LiveView is the default behavior when dealing with element lists.
LiveComponent templates rendered by relying on the assigns constructed with this module need to take into account
the :updated
assign and interpret it according to the updated/0
docs. The same is also used in the Javascript
element sorting code.
Link to this section Summary
Types
The state is typically a map of domain/business logic structure assigns. It contains caller-relative normalized structures which require transforming into assigns of the component-children, the functions of which the state is passed to.
:noop
instructs of patching without sorting; intended for actual element updates or:full
insertions (replacements):delete
instructs of rendering the marked-for-deletion variation of the LiveComponent element{ :sort, { dst :: component_id(), state_version()}}
instructs of sorting the element i.e. inserting it before the provided destination element dom id.
Callbacks
Returns the component id string representation for the provided element diff id. The returned string value should not contain the ':' character for it is later used as a separator between the component_id and the state version when sorting.
Returns the component name if different than the module last name without the "Component" suffix. Optional callback.
Constructs component assigns from the provided model state.
Returns the list of all element diff ids along with the provided state with its last moment updates if any.
Checks if any distilling-relevant portion of the provided state has changed. This is an optional callback that, if defined, is invoked before distilling any assigns from the state. It should be defined to provide simple, comparison based checking as an alternative to constructing assigns if there are no changes in the state.
Link to this section Types
Specs
Specs
component_id() :: String.t()
Specs
diff_id() :: term()
Specs
listilled() :: module()
Specs
sort_data() :: {component_id(), state_version()}
Specs
state() :: term() | nil
The state is typically a map of domain/business logic structure assigns. It contains caller-relative normalized structures which require transforming into assigns of the component-children, the functions of which the state is passed to.
Specs
state_version() :: non_neg_integer()
Specs
updated() :: :noop | :delete | {:sort, sort_data()}
:noop
instructs of patching without sorting; intended for actual element updates or:full
insertions (replacements):delete
instructs of rendering the marked-for-deletion variation of the LiveComponent element{ :sort, { dst :: component_id(), state_version()}}
instructs of sorting the element i.e. inserting it before the provided destination element dom id.
Link to this section Functions
Link to this section Callbacks
Specs
component_id(diff_id(), state()) :: component_id()
Returns the component id string representation for the provided element diff id. The returned string value should not contain the ':' character for it is later used as a separator between the component_id and the state version when sorting.
Specs
component_name() :: String.t()
Returns the component name if different than the module last name without the "Component" suffix. Optional callback.
Specs
Constructs component assigns from the provided model state.
Specs
Returns the list of all element diff ids along with the provided state with its last moment updates if any.
Specs
Checks if any distilling-relevant portion of the provided state has changed. This is an optional callback that, if defined, is invoked before distilling any assigns from the state. It should be defined to provide simple, comparison based checking as an alternative to constructing assigns if there are no changes in the state.