Usage with Phoenix templates
Using Surface components in vanilla Phoenix templates, i.e. using ~L
or in *.leex
files,
is partially supported, however, this approach is limited and mostly not recommended.
Keep in mind that Surface extends Liveview, adding extra features like slots and contexts. Since there's no built-in support for them in Phoenix, Surface needs to prepare the LV/Component to make those features work seamlessly.
If you find a Surface component you want to use in your existing phoenix project. You have the following options:
-
[Recommended] Replace the live views (or components) that will use the desired component with their Surface's counterparts, i.e.
Surface.LiveView
,Surface.LiveComponent
andSurface.Component
. This requires no extra step and you'll be able to enjoy all its features without any limitation. -
[Limited] Follow the steps described in the Setting up Phoenix views for Surface section below and use
~F
or.sface
instead of~L
and.leex
. This should work fine but some features may require extra work like implementingmount
to callSurface.init(socket)
. -
[Not Recommended] Inject the component using phoenix's
live_component/4
directly in your template. This will work for most simple components as long as they don't make use of slots nor contexts. Other features that may be added in the future might not work with this approach either.
Setting up Phoenix views for Surface
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
You will also need to call Surface.init/1
in the mount function:
defmodule PageLive do
use Phoenix.LiveView
def mount(socket) do
socket = Surface.init(socket)
...
{:ok, socket}
end
...
end
defmodule NavComponent do
use Phoenix.LiveComponent
def mount(socket) do
socket = Surface.init(socket)
...
{:ok, socket}
end
...
end