surface v0.1.0-alpha.0 Surface View Source
Surface is component based library for Phoenix LiveView.
Built on top of the new Phoenix.LiveComponent
API, Surface provides
a more declarative way to express and use components in Phoenix.
A work-in-progress live demo with more details can be found at surface-demo.msaraiva.io
This module defines the ~H
sigil that should be used to translate Surface
code into Phoenix templates.
In order to have ~H
available for any Phoenix view, add the following import to your web
file in lib/my_app_web.ex
:
# lib/my_app_web.ex
...
def view do
quote do
...
import Surface
end
end
Defining components
To create a component you need to define a module and use
one of the available component types:
Surface.Component
- A stateless component.Surface.LiveComponent
- A live stateful component.Surface.LiveView
- A wrapper component aroundPhoenix.LiveView
.Surface.DataComponent
- A component that serves as a customizable data holder for the parent component.Surface.MacroComponent
- A low-level component which is responsible for translating its own content at compile time.
Example
# A functional stateless component
defmodule Button do
use Surface.Component
property click, :event
property kind, :string, default: "is-info"
def render(assigns) do
~H"""
<button class="button {{ @kind }}" phx-click={{ @click }}>
{{ @inner_content.() }}
</button>
"""
end
end
You can visit the documentation of each type of component for further explanation and examples.
Directives
Directives are built-in attributes that can modify the translated code of a component at compile time. Currently, the following directives are supported:
:for
- Iterates over a list (generator) and renders the content of the tag (or component) for each item in the list.:if
- Conditionally render a tag (or component). The code will be rendered if the expression is evaluated to a truthy value.:show
- Conditionally shows/hides an HTML tag, keeping the rendered alement in the DOM even when the value isfalse
.:bindings
- Defines the name of the variables (bindings) in the current scope that represent the values passed internally by the component when calling the@content
function.:on-[event]
- Sets aphx
event binding defining the component itself as the default handler (target). This is the prefered way to usephx
events in Surface as it can properly handle properties of type:event
. Available directives are::on-phx-click
,:on-phx-blur
,:on-phx-focus
,:on-phx-change
,:on-phx-submit
,:on-phx-keydown
and:on-phx-keyup
.
Example
<div>
<div class="header" :if={{ @showHeader }}>
The Header
</div>
<ul>
<li :for={{ item <- @items }}>
{{ item }}
</li>
</ul>
</div>
Link to this section Summary
Functions
Translates Surface code into Phoenix templates.
Link to this section Functions
Translates Surface code into Phoenix templates.