View Source Surface.Components.Context (Surface v0.12.1)

Deprecation warning
Using this module as a component with <Context> has been deprecated. Support for scope-aware context will be removed in v0.13 due to the lack of built-in support for the feature in Liveview itself, which leads to inefficient diff-tracking when using it.
Global context related functions like Context.put/3 and Context.get/3, as well as data/prop's option :from_context, will be kept and recommended as their usage don't affect diff-tracking negatively.

A built-in module and component that allows users to set and retrieve values to/from the context.

Properties

put :context_put, accumulate: true, default: [] - Puts a value into the context.

Usage

<Context put={scope, values}>
  ...
</Context>

Where:

scope - Optional. Is an atom representing the scope where the values will be stored. If no scope is provided, the value is stored at the root of the context map.
values- A keyword list containing the key-value pairs that will be stored in the context.

Examples

With scope:

<Context put={__MODULE__, form: @form}>
  ...
</Context>

Without scope:

<Context put={key1: @value1, key2: "some other value"}>
  ...
</Context>

get :context_get, accumulate: true, default: [] - Retrieves a set of values from the context binding them to local variables.

Usage

<Context get={scope, bindings}>
  ...
</Context>

Where:

scope - Optional. Is an atom representing the scope where the values will be stored. If no scope is provided, the value is stored at the root of the context map.
bindings- A keyword list of bindings that will be retrieved from the context as local variables.

Examples

<Context
  get={Form, form: form}
  get={Field, field: my_field}>
  <MyTextInput form={form} field={my_field} />
</Context>

Slots

default, required: true - The content of the <Context>

Summary

Functions

copy_assign(socket_or_assigns, key, opts \\ [])

Copies a value from the context directly into socket_or_assigns.

get(socket_or_assigns, scope \\ nil, key)

Retrieves a value from the context.

has_vars?(ast)

maybe_copy_assign(socket_or_assigns, key, opts \\ [])

Copies a value from the context directly into socket_or_assigns if the value hasn't already been set or if it's nil.

maybe_copy_assign!(socket_or_assigns, key, opts \\ [])

Copies a value from the context directly into socket_or_assigns.

put(socket_or_assigns, scope \\ nil, values)

Puts a value into the context.

Functions

copy_assign(socket_or_assigns, key, opts \\ [])

Copies a value from the context directly into socket_or_assigns.

Usage

# Simple key
Context.copy_assign(socket_or_assigns, key)

# Simple key with options
Context.copy_assign(socket_or_assigns, key, opts)

# Key with scope
Context.copy_assign(socket_or_assigns, {scope, key})

# Key with scope + options
Context.copy_assign(socket_or_assigns, {scope, key}, opts)

Options

:as - Optional. The key to store the value. Default is the key without the scope.

get(socket_or_assigns, scope \\ nil, key)

Retrieves a value from the context.

Usage

Context.get(socket_or_assigns, scope, key)

Where:

socket_or_assigns - The socket or assigns where the values will be retrieved from.
scope - Optional. Is an atom representing the scope where the values will be stored. If no scope is provided, the value is stored at the root of the context map.
key- the key to look for when retrieving the value.

Examples

form = Context.get(assigns, Form, :form)
field = Context.get(assigns, Field, :field)

...

~F"""
<MyTextInput form={form} field={field} />
"""

Note: Whenever using Context.get/3 inside the update/2 callback, make sure you call it passing the socket, not the assigns.

has_vars?(ast)

maybe_copy_assign(socket_or_assigns, key, opts \\ [])

Copies a value from the context directly into socket_or_assigns if the value hasn't already been set or if it's nil.

The value will be saved using the same key.

Usage

Context.maybe_copy_assign(socket_or_assigns, scope, key)

maybe_copy_assign!(socket_or_assigns, key, opts \\ [])

Copies a value from the context directly into socket_or_assigns.

It raises a runtime error in case the value is still nil after after the operation. This is useful whenever you expect a non-nil value coming either explicitly passed a prop or inplictly through the context.

The value will be saved using the same key.

Usage

Context.maybe_copy_assign!(socket_or_assigns, scope, key)

put(socket_or_assigns, scope \\ nil, values)

Puts a value into the context.

Usage

Context.put(socket_or_assigns, scope, values)

Where:

socket_or_assigns - The socket or assigns where the values will be stored.
scope - Optional. Is an atom representing the scope where the values will be stored. If no scope is provided, the value is stored at the root of the context map.
values- A keyword list containing the key-value pairs that will be stored in the context.

Examples

With scope:

Context.put(__MODULE__, form: @form)

Without scope:

Context.put(key1: @value1, key2: "some other value")

Note: Whenever using Context.put/3 inside the update/2 callback, make sure you call it passing the socket, not the assigns.