13 · Estrutura e shell

Persist

estado da LiveView guardado no navegador · sessionStorage ou localStorage · on_restore

Guarda um valor da LiveView no navegador e o devolve (on_restore) quando ela monta de novo.

sessionStorage: sobrevive ao recarregar a aba

0

storage=session · key=showcase_persist_session

.heex
<%!-- sessionStorage: <.persist id key storage="session" value={%{note: @note, count: @count}} on_restore="restore" target={@myself} />
     Escreva, conte, recarregue a página: o valor volta (a aba é a mesma). --%>
<.live_component module={LedgerShowcaseWeb.Demos.PersistDemo} id="persist-session" storage="session" key="showcase_persist_session" />

localStorage: sobrevive ao fechar a aba

0

storage=local · key=showcase_persist_local

.heex
<%!-- localStorage: sobrevive ao fechar a aba (e vale para todas as abas do site) --%>
<.live_component module={LedgerShowcaseWeb.Demos.PersistDemo} id="persist-local" storage="local" key="showcase_persist_local" />

Uso

<.persist id="draft-persist" key="draft" value={@draft} on_restore="restore" />

Regras

  • O valor fica no navegador, legível por qualquer script da página e pelo usuário: não coloque token, senha nem dado pessoal.
  • O que volta por on_restore é entrada do usuário: valide no handle_event.
  • Dê a cada estado guardado o seu id e o seu key; storage é session (padrão) ou local.

Referência da API

Todos os function components, atributos, valores e slots que este componente cobre.

persist/1: keeps a piece of LiveView state in the browser and gives it back when it mounts.

<.persist
  id="agent-widget"
  key="agent_widget"
  storage="session"
  value={%{open: @open?, conversation_id: @cid}}
  on_restore="aw_restore"
/>

def handle_event("aw_restore", %{"value" => %{"open" => open?, "conversation_id" => cid}}, socket),
  do: {:noreply, assign(socket, open?: open?, cid: cid)}

Renders a hidden element; the hook LedgerUI.Persist (priv/static/ledger_ui/hooks/persist.js) writes value (as JSON) under key in sessionStorage or localStorage (storage) on every mounted and updated, unless it did not change.

On mount, when something is saved under key and it differs from the current value, the hook pushes on_restore with %{"value" => saved} before writing, and does not write the current value over it (the server's reply, updated, writes the restored one). So the saved value survives a push_navigate: the next mount restores it. A value that is not valid JSON is ignored (and overwritten by the next write). Storage that is blocked or full is ignored too.

Not a place for secrets {: .warning}

The value stays in the browser (readable by any script of the page and by the user, and in localStorage it outlives the tab). Do not put tokens, passwords or personal data in it, and do not trust it: it is user input when it comes back through on_restore, so validate it in the handle_event.

target is the phx-target of on_restore (a selector or @myself). Give each persisted state its own id and key.

<.persist>

Attr Type Default Values / notes
id (required) :string Needed by the hook.
key (required) :string The storage key.
value (required) :any Anything that encodes to JSON.
storage :string "session" session, local
on_restore :string nil Event pushed with %{"value" => saved}.
target :any nil phx-target of on_restore.

Any other HTML/phx attribute goes to the root element.