Page source: read a page's rows once

The host app serves database pages through MishkaCmsWeb.RuntimeLive. Its handle_params/3 calls MishkaCmsCore.Runtime.PageSource.assign_source/1 for every address, after the page, its language, @query_params and the visitor are known, and before the frame and the head. The call fires the event with the map PageSource.given/2 builds and assigns the answer as @page_source. The CMS then resolves the frame and the head and hands them the same rows.

• Put the rows you read under source. The core never looks inside it, so its shape is yours.
• The CMS keeps only source of the answer. An answer that is not a map, or that has no source key, gives nil.
• Answer only for the pages you own, matched as a frame plugin matches them: by record, by section or by page.path. Return every other page untouched with {:reply, given} before you read anything.
• {:reply, :halt, given} keeps later plugins from answering for a page you own.
• A plugin that raises, or an event whose plugins cannot run, leaves the page with no source. Every reader then reads for itself, as it does without a source.

The template passes the rows with page_source={assigns[:page_source]}:

<.component
  component_name="shop-detail"
  site="acme"
  current_user={assigns[:current_user]}
  page_source={assigns[:page_source]}
/>

Write assigns[:page_source] and not @page_source. The admin's preview assigns no rows, and a template that reads a missing assign with @ raises.

assign_source/1 remembers whom each source was read for. On the next handle_params/3 of the same LiveView, held is the previous @page_source when it was read for the same visitor. In every other case it is nil, such as on the first address of the LiveView or when the last address was read for a different visitor.

• The core checks the visitor and nothing else. Before you reuse held, compare the site, the language and the record it was read for. Mishka Blog compares the site, the visitor, the language, the kind of record and the slug.
• A live patch that stays on the same record, such as the next page of a list or another version, takes from held what the new address did not change and reads only the rest.

The runtime hands page_source only to a component that declares the attribute. It asks the component's own list of declared attributes each time it draws the component, and only when the template names page_source.

• A component that does not declare it, such as one an admin keeps on an older kit, gets no rows. The runtime draws it as if the template had not named the attribute. Without the check, the rows would fall into the component's global attributes, and the component would draw them onto its root element.
• When a kit adds the attribute, the component gets the rows as soon as it is compiled.
• Declare it with the type any and a default of nil:

{"name": "page_source", "type": "any", "opts": {"default": null}}

A block that ships with an extension reads a source by its shape, because its code calls nothing of the extension. It checks that rows_of names the extension, then that site_id is its own site and visitor is its own reader. Anything else it reads for itself.

A shop extension marks its product pages with the record shop:product. This plugin reads the product once per address. MyShop.Catalog.product/3 stands for your own read, made as the visitor.

defmodule MyShop.Plugins.PageSource do
  use MishkaInstaller.Event.Hook, event: "runtime:page:source", initial: %{priority: 50}

  alias MishkaCmsCore.Runtime.PageSource

  @impl true
  def call(%{record: "shop:product", params: %{"slug" => slug}} = given) do
    visitor = PageSource.visitor_id(given.current_user)

    source =
      case given.held do
        %{rows_of: "my_shop", visitor: ^visitor, slug: ^slug} = held ->
          held

        _read_for_another_address ->
          %{
            rows_of: "my_shop",
            site_id: given.site_id,
            visitor: visitor,
            slug: slug,
            product: MyShop.Catalog.product(given.site_id, slug, given.current_user)
          }
      end

    {:reply, :halt, %{given | source: source}}
  end

  def call(given), do: {:reply, given}
end

The page's template passes the rows to a product block, shop-detail, that declares page_source and current_user. The block takes the source with a helper named source_of, which has the argument assigns. It falls back to its own read when the helper returns nil.

site = __MODULE__.__component_information__([:private, :site_id])

visitor =
  case assigns[:current_user] do
    %{id: id} -> id
    _guest -> nil
  end

case assigns[:page_source] do
  %{rows_of: "my_shop", site_id: ^site, visitor: ^visitor} = source -> source
  _not_for_this_block -> nil
end

The results, address by address:

• A visitor with the id u1 opens /shop/mug. held is nil, so the plugin reads the product.
• The same LiveView patches to the same record. held is the first source, and the plugin returns it without a read.
• The LiveView patches to /shop/cup. held was read for another slug, so the plugin reads again.
• The next address is read for another visitor, u2. held is nil, and the new source says visitor: "u2".
• The block, drawn for a guest, takes a source whose visitor is nil. It reads for itself when its reader is a different visitor, when the source is for another site, and when the page passes none.

Each extension answers for its own kinds of record and keeps its rows in a struct. The shape is the extension's own, and its blocks rely on it.

The struct of the document extension also holds the other editions of the document, which its frame plugin reads. The frame plugins of both extensions take their record from this source. See the Mishka Blog plugin events documentation and the Mishka Document plugin events documentation.

• Page frame: languages and the section bar: the plugin that answers for the layout, and takes its record from the source.
• Plugin events: every event the CMS fires, in the order the page events run.
• How a page reaches visitors: where the source is read among the steps of a request.
• Extensions and plugins: how an extension ships its plugins.