surface-ui / surface_site Goto Github PK
View Code? Open in Web Editor NEWDocumentation website for the Surface project.
Home Page: https://surface-ui.org/
Documentation website for the Surface project.
Home Page: https://surface-ui.org/
Using Surface components in plain Phoenix templates is usually not recommended so I think it's better to move the Using Surface on plain Phoenix views (optional)
section to its own page and add something like this at the top:
Using a Surface component 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:
[Recommened] Replace the live views (or components) that will use the desired component with their Surface's counterparts, i.e. Surface.LiveView
, Surface.LiveComponent
and Surface.Component
. This requires no extra step and you'll be able to enjoy all its features without any limitation.
Follow the steps described in https://surface-ui.org/getting_started#using-surface-on-plain-phoenix-views-(optional) and use ~H
or .sface
instead of ~L
and .leex
. This should work fine but some features may require extra work like implementing mount
to call Surface.init(socket)
.
[Not Recommened] 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.
For example:
https://surface-ui.org/builtincomponents/Field
It should show the atom type instead, especially for a changeset.
We should mention at least SurfaceFormatter
and SurfaceCatalogue
.
SurfaceBootstrap
and SurfaceBulma
will already have their own links on the menu under "UI Components" as soon as their catalogues are set up. The work for SurfaceBootstrap
has already started. See https://github.com/surface-ui/surface_site_bootstrap.
It would be nice if the demo site (http://surface-demo.msaraiva.io/getting_started) was available under https.
Especially as Firefox recently added a https only mode, which shows the following warning on the demo site.
I understand that this doesn't need to have the top priority, but nowadays setting up https is easy and free, using something like let's encrypt.
I apologize for such nitpicking, but I couldn't find in docs how to actually serve components from router (specifically that it should be Surface.LiveView
). I guess it's obvious for those who had already bought in complexity of LiveView, but still it would be not that burdensome to mention it, say, under Components Basic section :)
I mean: wouldn't this assignment require the existence of the 'templates' folder in order for the entire rendering to work?
(being an elixir-illiterate, what am I missing?)
surface_site/lib/surface_site_web.ex
Line 33 in 5a4d0e6
How hard would it be to add searching to the site?
Originally reported in surface-ui/surface_bulma#4 and surface-ui/surface#257.
Steps to reproduce:
_build
and deps
foldersmix deps.get
and mix deps.compile
iex -S mix phx.server
[I] โ iex -S mix phx.server
Erlang/OTP 23 [erts-11.1.1] [source] [64-bit] [smp:12:12] [ds:12:12:10] [async-threads:1] [hipe]
Compiling 79 files (.ex)
== Compilation error in file lib/surface_site_web/live/slots.ex ==
** (SyntaxError) nofile:292: unexpected token: ":" (column 25, code point U+003A)
(surface 0.3.2) expanding macro: Surface.sigil_H/2
lib/surface_site_web/live/slots.ex:10: SurfaceSiteWeb.Slots.render/1
(elixir 1.11.3) lib/kernel/parallel_compiler.ex:314: anonymous fn/4 in Kernel.ParallelCompiler.spawn_workers/7
Remarks: The error does not occur if you checkout on the previous commit: 0db6877 so I suppose we introduced regression when simplyfing the Code
component in the last commit: 6004d9d. It's really strange that the CI didn't catch it. (Edit: Ah, there is not CI ^^)
The Context module defines examples that are not present on the website: https://hexdocs.pm/surface/Surface.Components.Context.html#module-examples-1
If the line_range
prop is not specified the following error occurs:
== Compilation error in file lib/surface_site_web/live/slots.ex ==
** (MatchError) no match of right hand side value: ["defmodule SurfaceSiteWeb.GettingStarted.RenderlessComponent do", " defmodule Column do", " use Surface.Component, slot: \"cols\"", "", " @doc \"The field to be rendered\"", " prop field, :string", " end", "", " defmodule Grid do", " use Surface.Component", "", " @doc \"The list of items to be rendered\"", " prop items, :list, required: true", "", " @doc \"The list of columns defining the Grid\"", " slot cols", "", " def render(assigns) do", " ~H\"\"\"", " <table class=\"table is-bordered is-striped is-hoverable is-fullwidth\">", " <thead>", " <tr>", " <th :for={{ col <- @cols }}>", " {{ Phoenix.Naming.humanize(col.field) }}", " </th>", " </tr>", " </thead>", " <tbody>", " <tr :for={{ item <- @items }} class={{ \"is-selected\": item[:selected] }}>", " <td :for={{ col <- @cols, field = String.to_atom(col.field) }}>", " {{ item[field] }}", " </td>", " </tr>", " </tbody>", " </table>", " \"\"\"", " end", " end", "", " defmodule Example do", " use Surface.LiveComponent", "", " data albums, :list, default: []", "", " def mount(socket) do", " albums = [", " %{name: \"The Dark Side of the Moon\", artist: \"Pink Floyd\", released: \"March 1, 1973\"},", " %{name: \"OK Computer\", artist: \"Radiohead\", released: \"June 16, 1997\"},", " %{", " name: \"Disraeli Gears\",", ...]
(surface_site 0.1.0) lib/surface_site_web/components/code.ex:90: SurfaceSiteWeb.Components.Code.fix_leading_space/1
(surface_site 0.1.0) lib/surface_site_web/components/code.ex:29: SurfaceSiteWeb.Components.Code.expand/3
(surface 0.3.2) lib/surface/compiler.ex:448: Surface.Compiler.convert_node_to_ast/3
(surface 0.3.2) lib/surface/compiler.ex:212: anonymous fn/3 in Surface.Compiler.to_ast/2
(elixir 1.11.3) lib/enum.ex:2193: Enum."-reduce/3-lists^foldl/2-0-"/3
(surface 0.3.2) lib/surface/compiler.ex:211: Surface.Compiler.to_ast/2
(surface 0.3.2) lib/surface/compiler.ex:331: Surface.Compiler.convert_node_to_ast/3
(surface 0.3.2) lib/surface/compiler.ex:212: anonymous fn/3 in Surface.Compiler.to_ast/2
(elixir 1.11.3) lib/enum.ex:2193: Enum."-reduce/3-lists^foldl/2-0-"/3
(surface 0.3.2) lib/surface/compiler.ex:211: Surface.Compiler.to_ast/2
(surface 0.3.2) lib/surface/compiler.ex:331: Surface.Compiler.convert_node_to_ast/3
(surface 0.3.2) lib/surface/compiler.ex:212: anonymous fn/3 in Surface.Compiler.to_ast/2
(elixir 1.11.3) lib/enum.ex:2193: Enum."-reduce/3-lists^foldl/2-0-"/3
(surface 0.3.2) lib/surface/compiler.ex:211: Surface.Compiler.to_ast/2
(surface 0.3.2) lib/surface/compiler.ex:331: Surface.Compiler.convert_node_to_ast/3
(surface 0.3.2) lib/surface/compiler.ex:212: anonymous fn/3 in Surface.Compiler.to_ast/2
(elixir 1.11.3) lib/enum.ex:2193: Enum."-reduce/3-lists^foldl/2-0-"/3
(surface 0.3.2) lib/surface/compiler.ex:211: Surface.Compiler.to_ast/2
(surface 0.3.2) lib/surface/compiler.ex:331: Surface.Compiler.convert_node_to_ast/3
(surface 0.3.2) lib/surface/compiler.ex:212: anonymous fn/3 in Surface.Compiler.to_ast/2
It is because of the split in the following function that does not match with the pattern
surface_site/lib/surface_site_web/components/code.ex
Lines 89 to 96 in 0fb92bb
We should fix this to handle a full file without specify the line_range.
This page https://surface-ui.org/usage_with_phoenix_templates (related to #25) seems to not have been updated for the latest Phoenix and makes no mention of HEEX or <MyComponent.render />
Replace all:
<#Raw>
<div style="color: rgb(212, 212, 212); ...">...</div>
</#Raw>
with either <#Code>
or embedded code in markdown.
Use <#Code>
only for cases where the snippet cannot be embedded directly in markdown. For instance, when reading the code from another file.
Embedded:
surface_site/lib/surface_site_web/live/components_basics.ex
Lines 209 to 215 in d28b763
Using <#Code>
:
surface_site/lib/surface_site_web/live/components_basics.ex
Lines 49 to 55 in d28b763
The site documentation seems to be missing the constructs for <For>
and <If>
(soon to be replaced by new syntax).
Related to surface-ui/surface#192
Hi all, this might just be me but accessing the Getting Started shows Surface version 0.6.0 in the "Installation" section. It seems that the version has been bumped a while ago but is not being properly updated (maybe due to deployment or some other issue). It would be nice if the page can show version 0.7.X since 0.6.X isn't compatible with LiveView 0.17.X.
Update types introduced in surface-ui/surface#297 if necessary.
I am reading the Event section again and again and to be honest I am more an more lost ๐
The purpose of this issue is to list what I find strange in the Event section in order to share my feeling before attacking and validating a possible rewrite. I tried to take the point of view of a beginner and I tried to forget how to use events in Surface.
<Mode Beginner On>
This section is related to the one below, but I was wondering what type should be the "default" option? String? Function?
The use cases of the prop click, :event
are not clear. We use a quick example that shows how to declare a prop event but we do not know if the event is internal to the component or if we should pass a function to that prop.
defmodule MyButton do
use Surface.Component
@doc "Triggers on click"
prop click, :event
def render(assigns) do
...
end
end
This confusion is accentuated the next examples: Handling events in Surface/LiveView. In these examples, a prop event has not been declared but some handle_event
functions have been declared. Moreover, reader also finds this sentence: "always declare event properties as :event" but it is not the case in the example. ๐
Some questions raise in my mind:
:on-{name}
the same as the one used in prop {name}, :event
?I suggest to add examples with other events (at least one): keyup
, keydown
, debounce
, ...
phx-click
is often used with phx-value
:
<div phx-click="inc" phx-value-myvar1="val1" phx-value-myvar2="val2">
will send the following map of params to the server (doc):
def handle_event("inc", %{"myvar1" => "val1", "myvar2" => "val2"}, socket) do
In that case, it's not clear in Surface if I should use phx-value-myvar
or :on-value-my-var
. The last one seems strange to me.
<Mode Beginner Off>
I am wondering if we should rewrite this section to be more explicit and less confusing? For example, we could base the rewriting on the examples in the tests and improve them to show the "flow":
defmodule Button do
use Surface.LiveComponent
prop click, :event, default: "click"
def render(assigns) do
~H"""
<button :on-click={{ @click }}>Click me!</button>
"""
end
def handle_event("click", _, socket) do
{:noreply, socket}
end
end
defmodule Panel do
use Surface.LiveComponent
prop buttonClick, :event, default: "click"
def render(assigns) do
~H"""
<div>
<Button id="button_id" click={{ @buttonClick }}/>
</div>
"""
end
def handle_event("click", _, socket) do
{:noreply, socket}
end
end
# Example without default value
defmodule View do
use Surface.LiveView
def render(assigns) do
~H"""
<div>
<Panel id="panel_id" buttonClick="click"/>
</div>
"""
end
def handle_event("click", _, socket) do
{:noreply, socket}
end
end
# Example with default value
defmodule View do
use Surface.LiveView
def render(assigns) do
~H"""
<div>
<Panel id="panel_id" />
</div>
"""
end
end
I believe we should highlight some points:
handle_event
method you would like to useprop name, :event
Feel free to comment and add your feeling about this section. Even if my English level is not perfect, I would be glad to take time to rewrite this section the best I can.
If you click any button in the official examples fast enough, you can break the expected behavior.
Go to https://surface-ui.org/slots
The value and the style should be on sync
Surface: v0.X.X
LiveView: v0.X.X
Elixir: v1.X.X
surface-ui
orgGigalixir
surface-ui.org
domainsurface
to the surface-ui
orgsurface_site
public@lnr0626, @olivermt, @Malian, @miguel-s and @paulstatezny. Since you implemented some of the components we have, feel free to add examples, review the docs or help me with any of the other items you might like. Also, in case you remember anything else, feel free to add more items to the list.
Cheers.
Hi ๐ I'm a self-taught front end developer that recently started learning about Elixir and Phoenix and while I was progressing people kept suggesting Surface and here I am ๐ It's honestly amazing to see the effort that went into creating the library and how much value it has for the community so I'm excited to see it grow in the upcoming times.
When I stepped into https://surface-ui.org/, the UI, for me, didn't feel very modern and attractive and I was wondering if we could do some tweaks to it to boost its looks and make the starting experience of navigating the docs more exciting!
I have two suggestions for the homepage, one with just a simple intro ( v1 ) and another that is more informative and tries to go towards a similar look to other component libraries' websites.
Let me know if this is something that you could be interested in and I can get to work! ๐
From surface-ui/surface#302 (comment):
Update the docs to inform that slots are always lists and
<slot name="<name>" />
is just a short hand for<slot name="<name>" index="0" />
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.