Getting Started
Start building rich interactive user-interfaces, writing minimal custom Javascript now. For a quick start, you can either add Surface to an existing Phoenix LiveView project or install it from scratch.
Installing from scratch
Phoenix v1.5 comes with built-in support for LiveView apps. You can create a new application with
mix phx.new my_app --live
Then add surface
to the list of dependencies in mix.exs
:
def deps do
[
{:surface, "~> 0.1.0"}
]
end
If you're using mix format
, make sure you add surface
to the import_deps
configuration in your .formatter.exs
file:
[
import_deps: [:ecto, :phoenix, :surface],
...
]
That's all!
Note: In case you want to add Surface to an existing Phoenix application that doesn't have LiveView properly installed, please see Phoenix Liveview's installation instructions at hexdocs.pm/phoenix_live_view/installation.html.
Using Surface on plain Phoenix views (optional)
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
Running the examples
Most of the components used in this website as well the examples in the documentation are just thin wrappers around Bulma components. Why Bulma? Because it's a free, open source, responsive CSS framework with no JS dependencies, which makes it a perfect fit to use with Phoenix LiveView. However, you can easily adapt any of the examples to any library of your preference or try them out with your own CSS styles.
For a quick start with bulma, you can add the following line to your layout_view.ex
:
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/bulma/0.8.0/css/bulma.min.css" />
or add it to the list of dependencies in assets/package.json
:
"dependencies": {
"bulma": "0.8.0"
}
Tooling
-
A VS Code extension that adds support for syntax highlighting is available at marketplace.visualstudio.com.
-
Improved integration with ElixirSense to provide auto-completion is comming soon!