diff options
Diffstat (limited to 'examples/02-interactivity')
| -rw-r--r-- | examples/02-interactivity/README.md | 111 | ||||
| -rw-r--r-- | examples/02-interactivity/gleam.toml | 11 | ||||
| -rw-r--r-- | examples/02-interactivity/manifest.toml | 24 | ||||
| -rw-r--r-- | examples/02-interactivity/src/app.gleam | 66 |
4 files changed, 212 insertions, 0 deletions
diff --git a/examples/02-interactivity/README.md b/examples/02-interactivity/README.md new file mode 100644 index 0000000..d97f618 --- /dev/null +++ b/examples/02-interactivity/README.md @@ -0,0 +1,111 @@ +# 02 Interactivity + +In this example we show the basic structure of all Lustre applications with a +classic counter example. + +## The Model-View-Update architecture + +All Lustre applications are built around the Model-View-Update (MVU) architecture. +This is a pattern that's been popularised by the Elm programming language and +has since been adopted by many other frameworks and languages. + +MVU applications are built around three main concepts: + +- A `Model` and a function to initialise it. +- A `Msg` type and a function to update the model based on messages. +- A `View` function to render the model as a Lustre `Element`. + +These three pieces come together to form a self-contained update loop. You produce +an initial model, render it as HTML, and convert any user interactions into +messages to handle in the update function. + + ```text + +--------+ + | | + | update | + | | + +--------+ + ^ | + | | + Msg | | Model + | | + | v ++------+ +------------------------+ +| | Model | | +| init |------------------------>| Lustre Runtime | +| | | | ++------+ +------------------------+ + ^ | + | | + Msg | | Model + | | + | v + +--------+ + | | + | view | + | | + +--------+ +``` + +### Model + +The model represents the entire state of your application. For most Lustre +applications this will be a record, but for this example we're aliasing `Int` to +our `Model` type to keep things simple. + +We also need to write an `init` function that returns the initial state of our +application. It takes one argument, known as "flags" which is provided when the +application is first started. + +```gleam +fn init(initial_count: Int) -> Model { + case initial_count < 0 { + True -> 0 + False -> initial_count + } +} +``` + +Our `init` function takes a starting count, but ensures it cannot be below `0`. + +### Update + +In many other frameworks, it's common to update state directly in an event handler. +MVU applications take a different approach: instead of state updates being scattered +around your codebase, they are handled in a single `update` function. + +To achieve this, we define a `Msg` type that represents all the different kinds of +messages our application can receive. If you're familiar with Erlang this approach +to state management will be familiar to you. If you're coming from a JavaScript +background, this approach is most-similar to state management solutions like Redux +or Vuex. + +```gleam +pub opaque type Msg { + Incr + Decr +} +``` + +This approach means it is easy to quickly get an idea of all the ways your app +can change state, and makes it easy to add new state changes over time. By pattern +matching on an incoming message in our `update` function, we can lean on Gleam's +_exhaustiveness checking_ to ensure we handle all possible messages. + +### View + + + +```gleam +fn view(model: Model) -> Element(Msg) { + ... +} +``` + + +## Creating a dynamic Lustre application + +In the previous example we used the `lustre.element` function to construct a +static Lustre app. To construct a simple interactive app we can use `lustre.simple` +instead. From now on we'll see that all the different ways to construct a Lustre +application all take the same three `init`, `update`, and `view` functions. diff --git a/examples/02-interactivity/gleam.toml b/examples/02-interactivity/gleam.toml new file mode 100644 index 0000000..4368c0c --- /dev/null +++ b/examples/02-interactivity/gleam.toml @@ -0,0 +1,11 @@ +name = "app" +version = "1.0.0" +target = "javascript" + +[dependencies] +gleam_stdlib = "~> 0.34 or ~> 1.0" +lustre = { path = "../../" } +lustre_ui = "~> 0.3" + +[dev-dependencies] +gleeunit = "~> 1.0" diff --git a/examples/02-interactivity/manifest.toml b/examples/02-interactivity/manifest.toml new file mode 100644 index 0000000..4033048 --- /dev/null +++ b/examples/02-interactivity/manifest.toml @@ -0,0 +1,24 @@ +# This file was generated by Gleam +# You typically do not need to edit this file + +packages = [ + { name = "argv", version = "1.0.1", build_tools = ["gleam"], requirements = [], otp_app = "argv", source = "hex", outer_checksum = "A6E9009E50BBE863EB37D963E4315398D41A3D87D0075480FC244125808F964A" }, + { name = "gleam_community_ansi", version = "1.4.0", build_tools = ["gleam"], requirements = ["gleam_stdlib", "gleam_community_colour"], otp_app = "gleam_community_ansi", source = "hex", outer_checksum = "FE79E08BF97009729259B6357EC058315B6FBB916FAD1C2FF9355115FEB0D3A4" }, + { name = "gleam_community_colour", version = "1.3.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_community_colour", source = "hex", outer_checksum = "A49A5E3AE8B637A5ACBA80ECB9B1AFE89FD3D5351FF6410A42B84F666D40D7D5" }, + { name = "gleam_erlang", version = "0.24.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_erlang", source = "hex", outer_checksum = "26BDB52E61889F56A291CB34167315780EE4AA20961917314446542C90D1C1A0" }, + { name = "gleam_json", version = "0.7.0", build_tools = ["gleam"], requirements = ["gleam_stdlib", "thoas"], otp_app = "gleam_json", source = "hex", outer_checksum = "CB405BD93A8828BCD870463DE29375E7B2D252D9D124C109E5B618AAC00B86FC" }, + { name = "gleam_otp", version = "0.9.0", build_tools = ["gleam"], requirements = ["gleam_erlang", "gleam_stdlib"], otp_app = "gleam_otp", source = "hex", outer_checksum = "5FADBBEC5ECF3F8B6BE91101D432758503192AE2ADBAD5602158977341489F71" }, + { name = "gleam_stdlib", version = "0.34.0", build_tools = ["gleam"], requirements = [], otp_app = "gleam_stdlib", source = "hex", outer_checksum = "1FB8454D2991E9B4C0C804544D8A9AD0F6184725E20D63C3155F0AEB4230B016" }, + { name = "gleeunit", version = "1.0.2", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleeunit", source = "hex", outer_checksum = "D364C87AFEB26BDB4FB8A5ABDE67D635DC9FA52D6AB68416044C35B096C6882D" }, + { name = "glint", version = "0.14.0", build_tools = ["gleam"], requirements = ["gleam_community_ansi", "gleam_stdlib", "snag", "gleam_community_colour"], otp_app = "glint", source = "hex", outer_checksum = "21AB16D5A50D4EF34DF935915FDBEE06B2DAEDEE3FCC8584C6E635A866566B38" }, + { name = "lustre", version = "3.1.3", build_tools = ["gleam"], requirements = ["argv", "gleam_community_ansi", "gleam_erlang", "gleam_json", "gleam_otp", "gleam_stdlib", "glint"], source = "local", path = "../.." }, + { name = "lustre_ui", version = "0.3.0", build_tools = ["gleam"], requirements = ["gleam_community_colour", "lustre", "gleam_stdlib"], otp_app = "lustre_ui", source = "hex", outer_checksum = "F81BE5D20153CFFC717C2C4687A19375A8613528908AF7069DDA1B929C8398B1" }, + { name = "snag", version = "0.3.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "snag", source = "hex", outer_checksum = "54D32E16E33655346AA3E66CBA7E191DE0A8793D2C05284E3EFB90AD2CE92BCC" }, + { name = "thoas", version = "0.4.1", build_tools = ["rebar3"], requirements = [], otp_app = "thoas", source = "hex", outer_checksum = "4918D50026C073C4AB1388437132C77A6F6F7C8AC43C60C13758CC0ADCE2134E" }, +] + +[requirements] +gleam_stdlib = { version = "~> 0.34 or ~> 1.0" } +gleeunit = { version = "~> 1.0" } +lustre = { path = "../../" } +lustre_ui = { version = "~> 0.3"} diff --git a/examples/02-interactivity/src/app.gleam b/examples/02-interactivity/src/app.gleam new file mode 100644 index 0000000..e47b7a4 --- /dev/null +++ b/examples/02-interactivity/src/app.gleam @@ -0,0 +1,66 @@ +import gleam/int +import lustre +import lustre/attribute +import lustre/element.{type Element} +import lustre/element/html +import lustre/event +// These examples are written with lustre_ui in mind. They'll work regardless, +// but to see what lustre_ui can do make sure to run each of these examples with +// the `--include-styles` flag: +// +// $ gleam run -m lustre/try -- --include-styles +// +// In your own apps, make sure to add the `lustre_ui` dependency and include the +// stylesheet somewhere. +import lustre/ui + +// MAIN ------------------------------------------------------------------------ + +pub fn main() { + let app = lustre.simple(init, update, view) + let assert Ok(_) = lustre.start(app, "#app", 0) +} + +// MODEL ----------------------------------------------------------------------- + +type Model = + Int + +fn init(initial_count: Int) -> Model { + case initial_count < 0 { + True -> 0 + False -> initial_count + } +} + +// UPDATE ---------------------------------------------------------------------- + +pub opaque type Msg { + Incr + Decr +} + +fn update(model: Model, msg: Msg) -> Model { + case msg { + Incr -> model + 1 + Decr -> model - 1 + } +} + +// VIEW ------------------------------------------------------------------------ + +fn view(model: Model) -> Element(Msg) { + let count = int.to_string(model) + let styles = [#("width", "100vw"), #("height", "100vh")] + + ui.centre( + [attribute.style(styles)], + ui.stack([], [ + ui.button([event.on_click(Incr)], [element.text("+")]), + html.p([attribute.style([#("text-align", "center")])], [ + element.text(count), + ]), + ui.button([event.on_click(Decr)], [element.text("-")]), + ]), + ) +} |