modem

modem: a device that converts signals produced by one type of device (such as a computer) to a form compatible with another (such as a telephone) – Merriam-Webster

Modem is a little library for Lustre that helps you manage navigation and URLs in the browser. It converts url requests into messages that you can handle in your app’s update function. Modem isn’t a router, but it can help you build one!

Types

Options

</>

pub type Options {
  Options(
    handle_internal_links: Bool,
    handle_external_links: Bool,
  )
}

Constructors

```
Options(handle_internal_links: Bool, handle_external_links: Bool)
```
Arguments
- handle_internal_links
  
  Enable this option if you’d like to trigger your url change handler when a link to the same domain is clicked. When enabled, internal links will always update the url shown in the browser’s address bar but they won’t trigger a page load.
- handle_external_links
  
  Enable this option if you’d like to trigger your url change handler even when the link is to some external domain. You might want to do this for example to save some state in your app before the user navigates away.
  
  You will need to manually call load to actually navigate to the external link!

Functions

advanced

</>

pub fn advanced(
  options: Options,
  handler: fn(Uri) -> a,
) -> Effect(a)

Initialise an advanced modem that lets you configure what types of links to intercept. Take a look at the Options type for info on what can be configured.

Note: this effect is only meaningful in the browser. When executed in a backend JavaScript environment or in Erlang this effect will always be equivalent to effect.none()

back

</>

pub fn back(steps: Int) -> Effect(a)

The browser maintains a history stack of all the url’s the user has visited. This function lets you move back the given number of steps in that stack. If you reach the beginning of the stack, further attempts to go back will do nothing (unfortunately time travel is not quite possible yet).

Note: if you navigate back and then push a new url, you will clear the forward history of the stack.

Note: you can go too far back and end up navigating the user off your app if you’re not careful.

Note: this effect is only meaningful in the browser. When executed in a backend JavaScript environment or in Erlang this effect will always be equivalent to effect.none()

forward

</>

pub fn forward(steps: Int) -> Effect(a)

The browser maintains a history stack of all the url’s the user has visited. This function lets you move forward the given number of steps in that stack. If you reach the end of the stack, further attempts to go forward will do nothing (unfortunately time travel is not quite possible yet).

Note: you can go too far forward and end up navigating the user off your app if you’re not careful.

Note: this effect is only meaningful in the browser. When executed in a backend JavaScript environment or in Erlang this effect will always be equivalent to effect.none()

init

</>

pub fn init(handler: fn(Uri) -> a) -> Effect(a)

Initialise a simple modem that intercepts internal links and sends them to your update function through the provided handler.

Note: this effect is only meaningful in the browser. When executed in a backend JavaScript environment or in Erlang this effect will always be equivalent to effect.none()

initial_uri

</>

pub fn initial_uri() -> Result(Uri, Nil)

Get the Uri of the page when it first loaded. This can be useful to read in your own app’s init function so you can choose the correct initial route for your app.

To subscribe to changes in the uri when a user navigates around your app, see the init and advanced functions.

Note: this function is only meaningful when run in the browser. When run in a backend JavaScript environment or in Erlang this function will always fail.

load

</>

pub fn load(uri: Uri) -> Effect(a)

Load a new uri. This will always trigger a full page reload even if the uri is relative or the same as the current page.

Note: if you load a new uri while the user has navigated using the back or forward buttons, you will clear any forward history in the stack!

Note: this effect is only meaningful in the browser. When executed in a backend JavaScript environment or in Erlang this effect will always be equivalent to effect.none()

push

</>

pub fn push(
  path: String,
  query: Option(String),
  fragment: Option(String),
) -> Effect(a)

Push a new relative route onto the browser’s history stack. This will not trigger a full page reload.

Note: if you push a new uri while the user has navigated using the back or forward buttons, you will clear any forward history in the stack!

Note: this effect is only meaningful in the browser. When executed in a backend JavaScript environment or in Erlang this effect will always be equivalent to effect.none()

replace

</>

pub fn replace(
  path: String,
  query: Option(String),
  fragment: Option(String),
) -> Effect(a)

Replace the current uri in the browser’s history stack with a new relative route. This will not trigger a full page reload.

Note: this effect is only meaningful in the browser. When executed in a backend JavaScript environment or in Erlang this effect will always be equivalent to effect.none()

Constructors

Arguments