elm-router

This library helps with routing in elm applications.

Features

• Maintain state of all opened pages
• Remember Viewport of opened pages. (scroll position)
• Manage page update, view
• Manage page subscriptions individually (subscriptions from previously opened pages will run in background)

Change log

• 1.0.1 Added example
• 1.0.2 Added example passing data from model to parser so you can use that data in page init
• 1.1.0 Added query methods: currentUrl, currentRoute, currentViewPort
• 2.0.0
  • Added onUrlChanged to config so you will be notified if the url has changed (optional)
  • Modified init so it will grab viewport

To do

• Find a way to skip some routes from caching

Notes

• Official Guide might be easier for your app

Config

type alias Config msg route routeMsg =
    { parser : Parser (route -> route) route
    , update : routeMsg -> ( route, Cmd routeMsg )
    , view : route -> List (Html routeMsg)
    , message : Msg routeMsg -> msg
    , subscriptions : route -> Sub routeMsg
    , notFound : Url -> List (Html msg)
    , routeTitle : route -> Maybe String
    , onUrlChanged : Maybe (Url -> msg)
    }

Usage (assume file Route.elm containing)

Two static pages with no model and one with a model, message, and subscription:

type Route
    = Home
    | About
    | Contact Contact.Model

type Msg
    = ContactMsg Contact.Model Contact.Msg

You will need to provide the parser like:

parser : Parser (Route -> a) a
parser =
    Parser.oneOf
        [ Router.mapRoute Parser.top Home
        , Router.mapRoute (Parser.s "about") About
        , Router.mapRoute (Parser.s "contact") <| Contact <| Contact.init "" ""
        ]

An update function like:

update : Msg -> ( Route, Cmd Msg )
update message =
    case message of
        ContactMsg model msg ->
            Contact.update msg model
                |> Router.mapUpdate Contact ContactMsg

A view function like:

view : Route -> List (Html Msg)
view route =
    case route of
        Home ->
            Home.view

        About ->
            About.view

        Contact mdl ->
            Contact.view mdl
                |> Router.mapMsg (ContactMsg mdl)

A subscriptions function like:

subscriptions : Route -> Sub Msg
subscriptions route =
    case route of
        Home ->
            Sub.none

        About ->
            Sub.none

        Contact mdl ->
            Contact.subscriptions mdl
                |> Sub.map (ContactMsg mdl)

A title function like:

title : Route -> Maybe String
title route =
    case route of
        Home ->
            Nothing

        About ->
            Just "About"

        Contact _ ->
            Just "Contact"

And a notFound function like:

where

import Html as H exposing (Html)
import Url exposing (Url)

notFound : Url -> List (Html msg)
notFound url =
    [ H.h1 [] [ H.text "Page not found!" ]
    , H.h3 [] [ H.text <| Url.toString url ]
    ]

build a Config like:

config : Config App.Msg Route Route.Msg
config =
    { parser = Route.parser
    , update = Route.update
    , view = Route.view
    , message = App.Router
    , subscriptions = Route.subscriptions
    , notFound = Route.notFound
    , routeTitle = Route.title
    , onUrlChanged = Nothing
    }

where:

• App.Msg is your application Msg
• App.Router is the message in your application Msg created for the Router

And use the config created in your application like:

Assuming:

import Route exposing (Route)
import Router

type alias Model =
    { router : Router Route }

type Msg
    = Router (Router.Msg Route.Msg)

then :

init : () -> Url -> Key -> ( Model, Cmd Msg )
init _ url key =
    let
        (router, cmd) =
            Router.init config url key
    in
    ( Model router, cmd )

update : Msg -> Model -> ( Model, Cmd Msg )
update message ({ router } as model) =
    case message of
        Router msg ->
            let
                ( newRouter, cmd ) =
                    Router.update config msg router
            in
            ( { model | router = newRouter }, cmd )

view : Model -> Document Msg
view { router } =
    { title = Router.title router "My app"
    , body =
        [ H.nav []
            [ H.a [ A.href "/" ] [ H.text "Home" ]
            , H.a [ A.href "/about" ] [ H.text "About" ]
            , H.a [ A.href "/contact" ] [ H.text "Contact" ]
            , H.a [ A.href "/something_not_routed" ] [ H.text "404" ]
            ]
        , H.main_ [] (Router.view config router)
        ]
    }

subscriptions : Model -> Sub Msg
subscriptions { router } =
    Router.subscriptions config router

main : Program () Model Msg
main =
    Browser.application
        { init = init
        , update = update
        , view = view
        , subscriptions = subscriptions
        , onUrlChange = Router.onUrlChange config
        , onUrlRequest = Router.onUrlRequest config
        }