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:

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 is false.

  • :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 a phx event binding defining the component itself as the default handler (target). This is the prefered way to use phx 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

Link to this function

component(module, assigns, list)

View Source
Link to this macro

sigil_H(arg, _)

View Source (macro)

Translates Surface code into Phoenix templates.