From d08d0df7934e2299172aac434346ec6e2649cd6b Mon Sep 17 00:00:00 2001 From: Hayleigh Thompson Date: Fri, 14 Jun 2024 00:03:33 +0100 Subject: :memo: Formatting tweaks. --- pages/reference/for-elm-devs.md | 84 +++++++++++++++++++++++------------- pages/reference/for-liveview-devs.md | 47 ++++++++++++++------ 2 files changed, 88 insertions(+), 43 deletions(-) diff --git a/pages/reference/for-elm-devs.md b/pages/reference/for-elm-devs.md index 8d8028b..e545ac7 100644 --- a/pages/reference/for-elm-devs.md +++ b/pages/reference/for-elm-devs.md @@ -1,16 +1,20 @@ # Lustre for Elm developers -Lustre has been directly inspired by Elm and shares some of the primary architectural features of "The Elm Architecture", otherwise known as Model-View-Update. This guide is for Elm developers who are new to Lustreand want to get up to speed quickly. +Lustre has been directly inspired by Elm and shares some of the primary architectural +features of "The Elm Architecture", otherwise known as Model-View-Update. This +guide is for Elm developers who are new to Lustreand want to get up to speed quickly. ## How do I...? ### Setup a new project -**In Elm**, all you really need to get started is to install the `elm` binary. Running `elm make` against an Elm file will transpile your code to either Javascript, or HTML with the Javascript output inlined. Most people will build out their own toolchain to support build-on-save and hot-reload, with tools like Vite or Webpack with the appropriate plugins. A simple hello world might look like this: +**In Elm**, all you really need to get started is to install the `elm` binary. +Running `elm make` against an Elm file will transpile your code to either Javascript, +or HTML with the Javascript output inlined. Most people will build out their own +toolchain to support build-on-save and hot-reload, with tools like Vite or Webpack +with the appropriate plugins. A simple hello world might look like this: ```elm -// src/Main.elm - module Main exposing (main) import Html @@ -25,7 +29,6 @@ Most Lustre projects will add the dev tools too with `gleam add --dev lustre_dev A simple hello world might look like this: ```gleam -// main.gleam import lustre import lustre/element/html @@ -37,18 +40,31 @@ pub fn main() { ### Render some HTML -**In Elm**, you can call functions in the `elm/html` package to render HTML elements. The `Html` module in `elm/html` contains functions for most standard HTML tags; these functions take as parameters a list of attributes from `Html.Attributes`, or events from `Html.Events` - as well as a list of child elements. Here's an example: +**In Elm**, you can call functions in the `elm/html` package to render HTML +elements. The `Html` module in `elm/html` contains functions for most standard +HTML tags; these functions take as parameters a list of attributes from +`Html.Attributes`, or events from `Html.Events` - as well as a list of child +elements: ```elm -Html.button [ Html.Attributes.class "primary" ] [ Html.text "Click me" ] +Html.button + [ Html.Attributes.class "primary" + , Html.Events.onClick ButtonClicked + ] + [ Html.text "Click me" ] ``` --- -**In Lustre**, HTML is rendered by calling functions, many of whom share the same signature - functions in `lustre/element/html` represent HTML tags, and most functions accept a list of `lustre/attribute` or `lustre/event` values, as well as a list of child elements. +**In Lustre**, HTML is rendered by calling functions, many of whom share the same +signature - functions in `lustre/element/html` represent HTML tags, and most +functions accept a list of `lustre/attribute` or `lustre/event` values, as well +as a list of child elements. ```lustre -button([class("primary")], [text("Click me"]) +html.button([attribute.class("primary"), event.on_click(ButtonClicked)], [ + html.text("Click me") +]) ``` ### Render some text @@ -56,24 +72,24 @@ button([class("primary")], [text("Click me"]) **In Elm**, text is rendered by passing a `String` to the `Html.text` function: ```elm -Html.text <| "Hello, " ++ name +Html.span [] [ Html.text <| "Hello, " ++ name ] ``` --- -**In Lustre** because of Gleam's type system, all elements must be Lustre's `Element` -type. To render text you need to use the `text` function: +**In Lustre**, text is rendered by passing a `String` to the `html.text` or +`element.text` functions: ```gleam -span([], [ - text("Hello"), - text("Hello" <> name), +html.span([], [ + html.text("Hello, " <> name), ]) ``` ### Manage state -**In Elm** all state is stored in a single `Model` type and updates happen through a central `update` function. +**In Elm** all state is stored in a single `Model` type and updates happen through +a central `update` function: ```elm type alias Model = Int @@ -82,22 +98,23 @@ init : Model init = 0 type Msg - = Incr - | Decr + = Incr + | Decr update : Msg -> Model -> Model update msg model = - case msg of - Incr -> - model + 1 + case msg of + Incr -> + model + 1 - Decr -> - model - 1 + Decr -> + model - 1 ``` --- -**In Lustre** all state is stored in a single `Model` type and updates happen through a central `update` function, much like in Elm. +**In Lustre** all state is stored in a single `Model` type and updates happen +through a central `update` function, just like in Elm: ```gleam fn init(_) { @@ -109,7 +126,7 @@ type Msg { Decr } -fn update(model, msg) { +fn update(model: Model, msg: Msg) -> Msg { case msg { Incr -> model + 1 Decr -> model - 1 @@ -117,11 +134,10 @@ fn update(model, msg) { } ``` -You can read more about this approach in the [state management guide](https://hexdocs.pm/lustre/guide/02-state-management.html). - ### Handle events -**In Elm** event handlers are decoders for event objects. When the decoder succeeds, that value is passed to your `update` function. Elm's event handlers are part of the `elm/html` package; event handlers return a value of type `Html.Attribute msg`, so they are applied to HTML elements as attributes. +**In Elm** event handlers are decoders for event objects. When the decoder succeeds, +that value is dispatched as a message to your `update` function. ```elm Html.input [ Html.Events.onInput UserUpdatedNameField ] [] @@ -140,7 +156,8 @@ update msg model = --- -**In Lustre** event handlers work in the same way. Lustre provides functions to handle most common events, in [`lustre/effect`](https://hexdocs.pm/lustre/lustre/effect.html): +**In Lustre** event handlers work in the same way. Lustre provides functions to +handle most common events, in [`lustre/effect`](https://hexdocs.pm/lustre/lustre/effect.html): ```gleam button([on_click(Decr)], [text("-")]) @@ -158,7 +175,11 @@ div([on("mousemove", fn(event) { ### Fetch data -**In Elm** you can fetch data by making a HTTP request. HTTP request functions both return a value of type `Cmd msg`, and are handled by the application's `update` function; the payload from the response is available within the `update` function and can be used to update the `Model`, or call other functions that return a value of type `Cmd msg`. +**In Elm** you can fetch data by making a HTTP request. HTTP request functions +both return a value of type `Cmd msg`, and are handled by the application's `update` +function; the payload from the response is available within the `update` function +and can be used to update the `Model`, or call other functions that return a value +of type `Cmd msg`. ```elm type Msg @@ -182,7 +203,8 @@ update msg model = --- -**In Lustre**, the approach is similar, using types and functions from the [`lustre_http` package](https://hexdocs.pm/lustre_http/lustre_http.html): +**In Lustre**, the approach is similar, using types and functions from the +[`lustre_http` package](https://hexdocs.pm/lustre_http/lustre_http.html): ```gleam pub type Msg { diff --git a/pages/reference/for-liveview-devs.md b/pages/reference/for-liveview-devs.md index 3aafd44..4903b8f 100644 --- a/pages/reference/for-liveview-devs.md +++ b/pages/reference/for-liveview-devs.md @@ -1,12 +1,15 @@ # Lustre for LiveView developers -Coming from LiveView, many things about Lustre will feel very familiar. But in many other ways it will be quite different. This guide is for LiveView developers who are new to Lustre and want to get up to speed quickly. +Coming from LiveView, many things about Lustre will feel very familiar. But in many +other ways it will be quite different. This guide is for LiveView developers who +are new to Lustre and want to get up to speed quickly. ## How do I...? ### Setup a new project -**In LiveView** you create a new Phoenix project with `mix phx.new`. A simple hello world might look like this: +**In LiveView** you create a new Phoenix project with `mix phx.new`. A simple +hello world might look like this: ```elixir # lib/my_app_web/live/hello_live.ex @@ -29,7 +32,10 @@ To start your dev server, run `mix phx.start` --- -**In Lustre**, after you've created a new Gleam project with `gleam new`, you need to install the `lustre` package with `gleam add lustre`. Most Lustre projects will add the dev tools too with `gleam add --dev lustre_dev_tools`. A simple hello world might look like this: +**In Lustre**, after you've created a new Gleam project with `gleam new`, you need +to install the `lustre` package with `gleam add lustre`. Most Lustre projects will +dd the dev tools too with `gleam add --dev lustre_dev_tools`. A simple hello world +might look like this: ```gleam // main.gleam @@ -46,7 +52,8 @@ To start your dev server, run `gleam run -m lustre/dev start` ### Render some HTML -**In LiveView** you use HEEx templates to render HTML elements. This looks like HTML and allows you to interpolate Elixir code and dynamic values in your template. +**In LiveView** you use HEEx templates to render HTML elements. This looks like +HTML and allows you to interpolate Elixir code and dynamic values in your template. ```html @@ -54,7 +61,9 @@ To start your dev server, run `gleam run -m lustre/dev start` --- -**In Lustre** HTML is rendered by calling functions. Usually the first argument is a list of `Attribute` types, and the second argument a list of `Element` type children. +**In Lustre** HTML is rendered by calling functions. Usually the first argument +is a list of `Attribute` types, and the second argument a list of `Element` type +children. ```gleam button([class("primary")], [text("Click me")]) @@ -62,7 +71,8 @@ button([class("primary")], [text("Click me")]) ### Render some text -**In LiveView** a string is a valid type of node, so you can render text by just writing it in your HEEx template: +**In LiveView** a string is a valid type of node, so you can render text by just +writing it in your HEEx template: ```html Hello @@ -88,7 +98,9 @@ span([], [ ### Manage state -**In LiveView** all your state is stored in the `assigns` key of the socket. Updates happen by sending events to the LiveView process, where the event handlers will update the relevant state and return the updated socket. +**In LiveView** all your state is stored in the `assigns` key of the socket. Updates +happen by sending events to the LiveView process, where the event handlers will +update the relevant state and return the updated socket. ```elixir def mount(_params, _session, socket) do @@ -107,7 +119,10 @@ end --- -**In Lustre** all state is stored in a single `Model` type and updates happen through a central `update` function. A notable difference here is that Gleam does not allow pattern matching in function heads, so instead you use a `case` statement to match on the different messages and handle them accordingly. +**In Lustre** all state is stored in a single `Model` type and updates happen +through a central `update` function. A notable difference here is that Gleam does +not allow pattern matching in function heads, so instead you use a `case` statement +to match on the different messages and handle them accordingly. ```gleam fn init(_) { @@ -129,7 +144,11 @@ fn update(model, msg) { ### Handle events -**In LiveView** you can bind messages to events in your HEEx template and define `handle_event/3` functions that receive the event name, any addtional parameters and the socket. These usually change some kind of state, and return the updated socket. LiveView provides handlers for most common events and passes the accompanying values to your event handler. +**In LiveView** you can bind messages to events in your HEEx template and define +`handle_event/3` functions that receive the event name, any addtional parameters +and the socket. These usually change some kind of state, and return the updated +socket. LiveView provides handlers for most common events and passes the accompanying +values to your event handler. ```html @@ -159,7 +178,9 @@ Hooks.MouseMove = { --- -**In Lustre** event handlers are decoders for event objects. When the decoders succeeds, that value is passed to your `update` function. Lustre provides functions to handle most common events. +**In Lustre** event handlers are decoders for event objects. When the decoders +succeeds, that value is passed to your `update` function. Lustre provides functions +to handle most common events. ```gleam button([on_click(Decr)], [text("-")]) @@ -193,11 +214,13 @@ defp greet(assigns) do end ``` -LiveView also allows for live components that contain state, markup and events, but Lustre does not have the equivalent of these. +LiveView also allows for live components that contain state, markup and events, +but Lustre does not have the equivalent of these. --- -**In Lustre** components are more commonly referred to as "view functions". They are regular Gleam functions. +**In Lustre** components are more commonly referred to as "view functions". They +are regular Gleam functions. ```gleam fn greet(name: String) -> Element(Msg) { -- cgit v1.2.3