elm-spa/docs.json

[{"name":"Spa","comment":" When you create an app with the [elm/browser](/packages/elm/browser/latest) package,\nyou can build anything from a static `Html msg` page to a fully-fledged web `Browser.application`.\n\n`elm-spa` uses the existing design at the page-level, so you can quickly add new pages to your Elm application!\n\n\n## the four kinds of pages:\n\n1.  [static](#static-pages) – a page that only renders HTML.\n2.  [sandbox](#sandbox-pages) – a page with state.\n3.  [element](#element-pages) – a page with side-effects.\n4.  [component](#component-pages) – a page with global state.\n\n\n# static pages\n\nJust like [Elm's intro \"Hello!\" example](https://elm-lang.org/examples/hello),\nsometimes you just want a page that renders some HTML, without having any state.\n\n@docs static\n\n**Note:** Static pages don't store data, so Model is always an empty tuple: ()\n\n\n# sandbox pages\n\nWhen you're ready to keep track of state, like in\n[Elm's \"Counter\" example](https://elm-lang.org/examples/buttons),\nyou can use a sandbox page.\n\nSimilar to `Browser.sandbox`, this allows you to init your model, and update it with messages!\n\n@docs sandbox\n\n\n# element pages\n\nIf you're ready to [send HTTP requests](https://elm-lang.org/examples/cat-gifs) or [listen to events](https://elm-lang.org/examples/time) for updates, it's time to upgrade to an element page!\n\nAdditionally, an element will give you access to Flags, so you can access things like URL parameters.\n\n@docs element\n\n**New to Cmd or Sub?** I recommend checking out Elm's official guide , that's a great place to wrap your head around these two concepts.\n\n\n# component pages\n\nIf you need to access shared state across all pages, or need to send a global commands like signing in/signing out a user, a component page is what you'll need.\n\nComponent pages gain access to the `Global.Model`, and return an additional `Cmd Global.Msg` so you can read/update the global state of your application.\n\n@docs component\n\n**Cool trick:** Don't need access to Global.Model in all of your functions? Use always to skip the first argument.\n\nIn the following example, only the view function receives Global.Model:\n\n    import Global\n    import Spa exposing (Page)\n\n    page : Page Flags Model Msg Global.Model Global.Msg\n    page =\n        Spa.component\n            { init = always init\n            , update = always update\n            , view = view -- not using \"always\"!\n            , subscriptions = always subscriptions\n            }\n\n\n# putting pages together\n\n**Note:** The [elm-spa cli tool](https://www.npmjs.com/package/elm-spa) will generate all the upcoming code\nfor you. You can continue reading to understand what it's doing under the hood!\n\n@docs Page\n\n\n## learning with an example\n\nLet's imagine we are building a website for a restaurant! This website has the following routes:\n\n1.  `/home` - the homepage\n2.  `/menu` - the menu\n3.  `/faqs` - frequently asked questions\n\nWith `elm-spa` we'd create a module for each page, and import them together in one file.\n\n    module Pages exposing (Model, Msg, init, update, view, subscriptions)\n\n    import Pages.Home\n    import Pages.Menu\n    import Pages.Faqs\n\nIf we want to implement the `Pages.init` function, we'll need to return the same type of value. This means we need to make a shared model and a shared msg type to handle all the different pages in our application:\n\n    type Model\n        = Home_Model Pages.Home.Model\n        | Menu_Model Pages.Menu.Model\n        | Faqs_Model Pages.Faqs.Model\n\n    type Msg\n        = Home_Msg Pages.Home.Msg\n        | Menu_Msg Pages.Menu.Msg\n        | Faqs_Msg Pages.Faqs.Msg\n\nThese two types allow `init` to return `( Model, Cmd Msg, Cmd Global.Msg )` for any page that the user is looking at!\n\n\n## upgrading pages\n\nWith the custom types above:\n\n1.  `Home_Model` can upgrade a `Pages.Home.Model` to a `Model`\n2.  `Home_Msg` can upgrade a `Pages.Home.Msg` to a `Msg`\n\nWe use the upgrade function to return a record that makes writin