PhoenixKitBoards

Collaborative infinite-canvas boards for PhoenixKit.

Admins open Boards in the sidebar, create a board, and open it — an infinite Fresco canvas with the Etcher drawing layer (shapes, text, images). Multiple people on the same board see each other's edits, cursors, and presence in real time. Each board is one row in phoenix_kit_boards.

Installation

# host app mix.exs
{:phoenix_kit_boards, "~> 0.8"}
mix deps.get
mix phoenix_kit.update   # creates the phoenix_kit_boards table

Enable Boards on the admin Modules page. That's it — the sidebar tab, routes, permission, and JS all wire up automatically (PhoenixKit auto-discovers the module).

What you get

Boards in your own pages

A widget for the quick boards of one place — put it in a section of any page, wherever people jot things down:

<PhoenixKitBoards.Web.Components.boards_panel
  id="project-notes"
  scope={{"project", @project.uuid}}
  label="Notes"
  current_user={@current_scope.user}
  return_to={~p"/projects/#{@project}"}
/>

It is a grid of tiles, one per board, and a last tile of the same size that makes a new one. With no boards yet that tile is all there is, centred:

Text and image boards stay on the page and show up as tiles; the empty one opens, since there is nothing in it to see. A tile's menu renames, pins, makes private or shared, archives or deletes. The widget does not manage places or projects: you choose what place it is for (scope is any {type, id} pair of strings — a record, {"project", uuid}, or something that is not one, {"page", "/docs/setup"}) and put one wherever you want one. Every attribute is in the PhoenixKitBoards.Web.BoardsPanel moduledoc; the ones you will reach for:

attribute what it does
folder where the files of these boards go (below)
visibility_options / default_visibility who can see what people create here; one value hides the choice ([:private] = a personal notepad, [:shared] = a team one)
actions which ways to start a board to offer, from [:empty, :text, :image]
limit tiles shown before "Show all"
open :overlay (default: the board opens over the page, in the board page's own viewer), :navigate or :new_tab
show_label false to keep label for the folder name without drawing it

Boards opened from the widget open at /dashboard/boards/:id (so people without boards.manage can open them) and link back to return_to.

The overlay frames that same page (?embed=1) in an <iframe> from your own origin. Phoenix's default put_secure_browser_headers (x-frame-options: SAMEORIGIN) allows that. A Content-Security-Policy with frame-ancestors 'none' or a frame-src that leaves out 'self' does not, and the overlay then shows an empty frame. Relax the policy or pass open={:navigate}.

Every tile's menu also has Export as PDF. The board is drawn off screen with the same viewer as the board page and handed to Fresco's PDF export, so the host needs nothing extra.

The laser measure (Etcher's Bluetooth laser meter tool) is opt-in, with the same switch as PhoenixKit's media viewer: config :phoenix_kit, laser_measure: true. Only while it is on does the overlay's frame get the bluetooth permission.

Permissions

Two keys, in the admin's permissions matrix:

On first start after an upgrade, every role that held boards is given boards.manage, so nobody loses the admin pages; the boards_manage_backfilled setting records that this happened (a host that grants the keys in its own migration can read it). It runs only while the module is enabled, so on a site that turns Boards on later it is the first boot with it enabled that gives boards.manage to every role holding boards at that moment. Hosts that let users with no boards permission see the widget, or open boards, now have to grant the base key — that is the breaking change.

Who may see a place

The module cannot know what "can see project X" means in your app, so it asks:

config :phoenix_kit_boards, :authorize, {MyApp.Boards, :can?}

# MyApp.Boards
def can?(action, user, {"project", id}) when action in [:view, :create],
  do: MyApp.Projects.member?(id, user)

With no hook any signed-in user holding boards may view and create. A hook that raises, exits or answers anything but a boolean denies. The hook can narrow access, never widen it: private is always its creator's (users holding boards.manage may still open any board, as they always could on /admin/boards). The panel renders nothing for a place the user may not view. Boards with no place (scope={nil}) are the admin list's own, so a panel for them shows only to holders of boards.manage.

Where a board's files go

Every upload on a board is filed in that board's own media folder, created on its first upload, so one folder holds exactly one board's files and nobody has to guess which picture belongs to which board. By default that folder is Boards / <place> / <board name>. To put them somewhere of your own — say each order has a folder, however deep, and each board needs a folder inside it:

<%!-- inside that folder (the board gets a folder of its own in it) --%>
<PhoenixKitBoards.Web.Components.boards_panel ... folder={{:under, @order.storage_folder_uuid}} />

<%!-- that chain of folders from the media root, found or created --%>
<PhoenixKitBoards.Web.Components.boards_panel ... folder={{:path, ["Orders", @order.number, "Boards"]}} />

<%!-- the media root itself --%>
<PhoenixKitBoards.Web.Components.boards_panel ... folder={:root} />

<%!-- or work it out when a board is made: fn {type, id}, actor_uuid -> {:ok, folder_uuid} end --%>
<PhoenixKitBoards.Web.Components.boards_panel ... folder={&MyApp.Orders.boards_folder/2} />

or for the whole app, with the same hook convention the other modules use:

config :phoenix_kit_boards,
  attachments_parent_folder: {MyApp.Media, :board_parent},   # fun(:board, actor_uuid, %{scope:, label:})
  attachments_folder_name: {MyApp.Media, :board_name}        # fun(board, actor_uuid)

What to know:

What a place can be

scope is a pair of a type and an id: strings, integers or atoms, so {"order", 1001}, {:project, project.id} and {"page", "/docs/setup"} all work. They are stored as strings, and that is what the :authorize hook receives ({"order", "1001"}). A place with a missing id ({"order", nil}) shows nothing — never the boards that belong nowhere. Nothing in your database refers to a board: deleting an order does not delete its boards or folder (find them by scope with PhoenixKitBoards.Boards.list_for_scope/3).

Staying current

The widget re-reads itself every few seconds (poll, in milliseconds; 0 turns it off), which needs nothing from your page. For instant updates, subscribe your LiveView to the place and forward the message:

# mount/3, when connected?
PhoenixKitBoards.Boards.subscribe_scope({"project", project.uuid})

def handle_info({:boards_scope_changed, _board_uuid}, socket) do
  PhoenixKitBoards.Web.BoardsPanel.refresh("project-notes")
  {:noreply, socket}
end

How it works

Requirements

Optional: the ephemeral socket

Cursors and in-flight drags are high-rate and worthless a moment later, and through a LiveView every position pays for a render and a diff — queued behind that process's real work: saving edits, uploads, link previews. They can go over a channel of their own instead. Sockets are declared on the endpoint, and that belongs to the host, so this is one line in endpoint.ex:

socket "/phoenix_kit/board", PhoenixKitBoards.Web.BoardSocket, websocket: true

Skipping it loses nothing that worked before: cursors fall back to the LiveView relay, which is where they used to go, and live drags simply don't appear. The client also falls back while the channel is joining and if it fails, so a socket that dies mid-session degrades rather than dropping cursors silently.

Joining is governed by a short-lived signed token naming the board and the peer, minted by the LiveView that rendered the page. The channel re-derives both from it, so a client cannot join a board it was never shown, or present as somebody else. Mounted somewhere other than the default path? Say so, and the client is told rather than left to guess:

config :phoenix_kit_boards, board_socket_path: "/somewhere/else"

License

MIT.