Hologram Documentation

Middleware is reusable server-side logic that runs before a page renders (init/3) or before commands execute. It is not Phoenix Plug.

Middleware Types

1. Inline: Define a public function on the page/component and attach it with middleware :name.
2. Leaf: A module using use Hologram.Middleware that implements def call(server, opts).
3. Composite: A module using use Hologram.Middleware that declares a sub-chain using middleware ... lines (omits call/2).

Key Behaviors

• Attachment: Use middleware SomeModule or middleware :some_function on a page or component.
• Flow Control: To stop the chain (e.g., for unauthorized access), set a status using put_status(server, :forbidden), put_status(server, 403), or put_redirect(server, TargetPage). There is no halt; the status is checked after the middleware returns.
• Data Passing: Use put_stash(server, :key, value) to pass data downstream to init/3 or commands.
• Authentication: Use put_user_id(server, user_id) to log in and delete_user_id(server) to log out.

Realtime allows the server to push actions to clients. A broadcast triggers the client's action/3 handler.

In-Handler API (Recommended)

Use these inside init/3 or command/3. These are transactional and roll back if the handler fails.

• put_subscription(server, channel): Subscribes the current component to a channel.
• delete_subscription(server, channel): Removes a subscription.
• put_broadcast(server, channel, action, params): Queues a broadcast.
• put_broadcast_except(server, channel, action, params, {:instance, id}): Broadcasts to everyone except a specific instance.

Outside Handlers (Escape Hatch)

Use Hologram.Realtime functions for background jobs or GenServers. These fire immediately and do not roll back.

• broadcast_action, subscribe, unsubscribe.
• subscribe/unsubscribe require an explicit cid (e.g., "page").

Channel Structure

Channels are structured values, not strings. Examples:

• Bare atom: :notifications
• Tuple: {:room, 42} or {:doc, "abc-123", "v2"}
• Identity channels: {:instance, id}, {:session, id}, {:user, id}.

Hologram is a full-stack isomorphic Elixir web framework that compiles Elixir to JavaScript for the browser. It is fundamentally different from Phoenix LiveView.

Core Building Blocks

• Pages: Route entry points. They are always stateful and initialized on the server.
• Components: Reusable UI elements. They can be stateless or stateful.

Execution Model

• Actions: Run on the client (browser). Use these for state updates, navigation, and triggering commands.
• Commands: Run on the server. Use these for database access, API calls, and session/cookie management.
• State: Lives in the browser, enabling instant UI updates without network round-trips.

Communication

Client-server communication happens automatically over HTTP/2 persistent connections. Hologram automatically determines which code runs on the client vs server and compiles the client portions to JavaScript.

Hologram uses the ~HOLO sigil for templates. Do not use HEEx (~H) syntax.

Syntax Rules

• Interpolation: Use curly braces {expression}. Do not use <%= expression %>.
• Variables: Access props and state with @var syntax: {@name}, {@count}.
• Component Nodes: Use module names: <MyComponent prop="value" />. Do not use <.my_component>.
• Conditionals: Use {%if condition}...{/if} or {%if condition}...{%else}...{/if}.
• Iteration: Use {%for item <- @items}...{/for}.
• Raw Output: Use {%raw}...{/raw} to skip processing.
• Escaping: Use \{literal\} to escape curly braces.
• Spreads: Use ...{@expr} to spread maps or keyword lists as attributes or props (e.g., <div ...{@html_attrs}>).

Attribute Behavior

• If an attribute expression evaluates to nil or false, the attribute is not rendered.
• On HTML elements, spread keys are dasherized (user_id becomes user-id). Nested maps/keyword lists use dash-joined names (data: [user_id: 1] becomes data-user-id="1").
• On components, keys match declared prop names verbatim.
• Event bindings (prefixed with $) cannot be spread; they must be written as literal attributes.