Overview

SnapFramework.Scene aims to make creating Scenic scenes easier and comes with a lot of convenient features. See Scenic.Scene docs for more on scenes.

In order to use this module you will first need a template. Templates are just basic EEx files. See an example template below

<%= graph font_size: 20 %>

<%= primitive Scenic.Primitive.Text,
    "selected value #{@dropdown_value}",
    id: :dropdown_value_text,
    translate: {20, 80}
%>

<%= component Scenic.Component.Dropdown, {
        @dropdown_opts,
        @dropdown_value
    },
    id: :dropdown,
    translate: {20, 20}
%>

We always start the template off with <%= graph %>. This tells the compiler to build the Scenic graph. After that we begin inserting our primitives or components. The above is equivilent to writing the following -

Scenic.Graph.build()
|> Scenic.Primitive.Text.add_to_graph("selected value #{scene.assigns.dropdown_value}", id: :dropdown_value_text, translate: {20, 80})
|> Scenic.Component.Dropdown({scene.assigns.dropdown_opts, scene.assigns.dropdown_value}, id: :dropdown, translate: {20, 20})

Now that we have a template we can use the template in a scene.

defmodule Example.Scene.MyScene do
  use SnapFramework.Scene,
    name: :my_scene,
    template: "lib/scenes/my_scene.eex",
    controller: :none,
    assigns: [
      dropdown_opts: [
        {"Dashboard", :dashboard},
        {"Controls", :controls},
        {"Primitives", :primitives}
      ],
      dropdown_value: :dashboard,
    ]
end

Having just the above should be enough to get the scene rendering. But as you can see selecting a new dropdown doesn't update the text component text like the template implies that it should.

To update a graph SnapFramework has the use_effect macro. This macro comes with a Scene or Component. Let's update the above code to catch the event from the dropdown and update the text.

defmodule Example.Scene.MyScene do
  use SnapFramework.Scene,
    name: :my_scene,
    template: "lib/scenes/my_scene.eex",
    controller: Example.Scene.MySceneController,
    assigns: [
      dropdown_opts: [
        {"Dashboard", :dashboard},
        {"Controls", :controls},
        {"Primitives", :primitives}
      ],
      dropdown_value: :dashboard,
    ]

  use_effect [assigns: [dropdown_value: :any]], [
    run: [:on_dropdown_value_change],
  ]

  def process_event({:value_changed, :dropdown, value}, _, scene) do
    {:noreply, assign(scene, dropdown_value: value)}
  end
end

Last but not least the controller module.

defmodule Examples.Scene.MySceneController do
  import Scenic.Primitives, only: [text: 3]
  alias Scenic.Graph

  def on_dropdown_value_change(scene) do
    graph =
      scene.assigns.graph
      |> Graph.modify(:dropdown_value_text, &text(&1, "selected value #{scene.assigns.dropdown_value}", []))

    Scenic.Scene.assign(scene, graph: graph)
  end
end

That is the basics to using SnapFramework.Scene. It essentially consist of three pieces, a template, a controller, and a scene module that glues them together.

Setup and Mounted Callbacks

If you need to do some special setup, like request input, subscribe to a PubSub service, or add some runtime assigns. You can do that in the setup callback. It gives you the scene struct and should return a scene struct.

The setup callback run before the template is compiled. So any added or modified assigns will be included in the template. The graph however is not included on the scene yet.

defmodule Example.Scene.MyScene do
  use SnapFramework.Scene,
    name: :my_scene,
    template: "lib/scenes/my_scene.eex",
    controller: Example.Scene.MySceneController,
    assigns: [
      dropdown_opts: [
        {"Dashboard", :dashboard},
        {"Controls", :controls},
        {"Primitives", :primitives}
      ],
      dropdown_value: :dashboard,
    ]

  use_effect [assigns: [dropdown_value: :any]], [
    run: [:on_dropdown_value_change],
  ]

  def setup(scene) do
    Scenic.PubSub.subscribe(:pubsub_service)

    assign(scene, new_assign: true)
  end

  def process_event({:value_changed, :dropdown, value}, _, scene) do
    {:noreply, assign(scene, dropdown_value: value)}
  end
end

If you need to do something after the graph is compile, you can use the mounted callback. Like the setup callback it gives you the scene, and should return a scene.

defmodule Example.Scene.MyScene do
  use SnapFramework.Scene,
    name: :my_scene,
    template: "lib/scenes/my_scene.eex",
    controller: Example.Scene.MySceneController,
    assigns: [
      dropdown_opts: [
        {"Dashboard", :dashboard},
        {"Controls", :controls},
        {"Primitives", :primitives}
      ],
      dropdown_value: :dashboard,
    ]

  use_effect [assigns: [dropdown_value: :any]], [
    run: [:on_dropdown_value_change],
  ]

  def setup(scene) do
    Scenic.PubSub.subscribe(:pubsub_service)

    assign(scene, new_assign: true)
  end

  def mounted(%{assigns: %{graph: graph}} = scene) do
    # do something with the graph
  end

  def process_event({:value_changed, :dropdown, value}, _, scene) do
    {:noreply, assign(scene, dropdown_value: value)}
  end
end