Skip to content

Commit

Permalink
Update v3 references.
Browse files Browse the repository at this point in the history
  • Loading branch information
dillonkearns committed May 31, 2023
1 parent 58f9996 commit 19a9aaa
Show file tree
Hide file tree
Showing 12 changed files with 21 additions and 21 deletions.
2 changes: 1 addition & 1 deletion docs.json

Large diffs are not rendered by default.

8 changes: 4 additions & 4 deletions examples/docs/content/docs/01-what-is-elm-pages.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,19 +9,19 @@ Elm Backend refers to a traditional server or serverless provider for [server-re

## Route Modules

You [define Routes by adding Route Modules](/docs/file-based-routing) to the `app/Route/` folder. Each Route module has `Data`, which is a special type for data resolved with a [`BackendTask`](https://package.elm-lang.org/packages/dillonkearns/elm-pages-v3-beta/latest/BackendTask). A Route's `Data` type has a lifecycle that is manged by the `elm-pages` framework (similar to how the Elm runtime manages the lifecycle your `Model` in a traditional Elm app), but it is resolved on your `elm-pages` Backend. The `Data` type is available to your `view` function, and it will be available without any loading spinners or Maybe values.
You [define Routes by adding Route Modules](/docs/file-based-routing) to the `app/Route/` folder. Each Route module has `Data`, which is a special type for data resolved with a [`BackendTask`](https://package.elm-lang.org/packages/dillonkearns/elm-pages/latest/BackendTask). A Route's `Data` type has a lifecycle that is manged by the `elm-pages` framework (similar to how the Elm runtime manages the lifecycle your `Model` in a traditional Elm app), but it is resolved on your `elm-pages` Backend. The `Data` type is available to your `view` function, and it will be available without any loading spinners or Maybe values.

`elm-pages` is a superset of a vanilla Elm app, so the familiar Elm Architecture (`Model`/`init`/`update`/`view`) are all available in your Route modules in addition to your Route `Data` and other features that the `elm-pages` framework adds to the core Elm Architecture. `elm-pages` provides abstractions that leverage web standards to give a better user experience and a simpler developer experience. But because `elm-pages` is a superset of Elm, you can always perform vanilla `elm/http` requests from your Route modules or use other patterns you're familiar with from vanilla Elm apps.

## Server-Rendered Routes

Server-rendered routes in `elm-pages` give you a full-stack Elm application that lets you

- Resolve Elm data (through the [`BackendTask`](https://package.elm-lang.org/packages/dillonkearns/elm-pages-v3-beta/latest/BackendTask) API) that is resolved server-side, and then available in your hydrated Elm application on the frontend
- Resolve Elm data (through the [`BackendTask`](https://package.elm-lang.org/packages/dillonkearns/elm-pages/latest/BackendTask) API) that is resolved server-side, and then available in your hydrated Elm application on the frontend
- Parse the incoming HTTP request and use it to get dynamic and/or user-specific data, including headers, cookies, and query parameters
- Set cookies and headers on the response, and manage signed key-value sessions using the [`Server.Session`](https://package.elm-lang.org/packages/dillonkearns/elm-pages-v3-beta/latest/Server-Session) API
- Set cookies and headers on the response, and manage signed key-value sessions using the [`Server.Session`](https://package.elm-lang.org/packages/dillonkearns/elm-pages/latest/Server-Session) API
- Serve up an initial HTML response, including meta tags, from the server (helpful for both performance and SEO)
- Respond to follow-up form submissions using the [`Pages.Form`](https://package.elm-lang.org/packages/dillonkearns/elm-pages-v3-beta/latest/Pages-Form) API
- Respond to follow-up form submissions using the [`Pages.Form`](https://package.elm-lang.org/packages/dillonkearns/elm-pages/latest/Pages-Form) API

The goals of server-rendered routes in `elm-pages` are to support performance and maintainability.

Expand Down
2 changes: 1 addition & 1 deletion examples/docs/content/docs/04-file-structure.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ There's nothing wrong with using this if it suites your needs, the Effect patter
The `Effect` module must expose a `type Effect msg` and a `perform` function. These are the core of the module, and this pair defines which Effect's
can happen from your `init` and `update` on your frontend and how to perform them

> Note: Effects are unrelated to [the `BackendTask` API](https://package.elm-lang.org/packages/dillonkearns/elm-pages-v3-beta/latest/BackendTask). An `Effect` is something that is executed on the frontend of an `elm-pages` app.
> Note: Effects are unrelated to [the `BackendTask` API](https://package.elm-lang.org/packages/dillonkearns/elm-pages/latest/BackendTask). An `Effect` is something that is executed on the frontend of an `elm-pages` app.
## `Shared.elm`

Expand Down
4 changes: 2 additions & 2 deletions examples/docs/content/docs/05-use-the-platform.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,15 +16,15 @@ When you leverage these features such as using the URL to manage state, you are

Cookie-based sessions provide some benefits over client-side authentication methods like JWT Tokens. JWT tokens need to be appended to your HTTP requests manually when you perform requests to your API. They also need some place to store them on the client, often using LocalStorage. This can be a security risk, and it also means that you need to write more code to handle the authentication flow.

With cookie-based sessions, your requests to your server automatically have the session cookie attached. This means that you don't need to write any extra code to store and retrieve the token and ensure that it is attached to API requests. It also has security benefits because you can use [HTTP-only cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#httponly) (the default when you use the [`Server.Session` API](https://package.elm-lang.org/packages/dillonkearns/elm-pages-v3-beta/latest/Server-Session)). HTTP-only cookies are only accessible to the server that initially set the cookie (it can't be accessed through JavaScript with `document.cookie`, or through LocalStorage).
With cookie-based sessions, your requests to your server automatically have the session cookie attached. This means that you don't need to write any extra code to store and retrieve the token and ensure that it is attached to API requests. It also has security benefits because you can use [HTTP-only cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#httponly) (the default when you use the [`Server.Session` API](https://package.elm-lang.org/packages/dillonkearns/elm-pages/latest/Server-Session)). HTTP-only cookies are only accessible to the server that initially set the cookie (it can't be accessed through JavaScript with `document.cookie`, or through LocalStorage).

## Redirects

Elm apps work best when we can check for pre-conditions and filter out invalid states and violations of constraints at the top-level. For example, if a user is not logged in and is trying to access the user settings page, we want to avoid checking a `Maybe` or `RemoteData` everywhere we display the current user settings in that Route.

Redirects are a great mechanism that can help you make intuitive user experiences in cases like this. If you're not logged in, you can redirect to the login route. If you're logged in, then we can get the user settings data and render the page.

In server-rendered routes, you can return a [`Server.Response`](https://package.elm-lang.org/packages/dillonkearns/elm-pages-v3-beta/latest/Server-Response) where you either resolve to the `Data` needed for that Route, or alternatively redirect. By redirecting, you short-circuiting the `Data` for that Route by instead navigating to another Route. You can create a redirect Response using [Server.Response.temporaryRedirect](https://package.elm-lang.org/packages/dillonkearns/elm-pages-v3-beta/latest/Server-Response#temporaryRedirect), or using the code in the generated `Route` module `Route.redirectTo` (this takes an argument of your `Route` type so it is more type-safe).
In server-rendered routes, you can return a [`Server.Response`](https://package.elm-lang.org/packages/dillonkearns/elm-pages/latest/Server-Response) where you either resolve to the `Data` needed for that Route, or alternatively redirect. By redirecting, you short-circuiting the `Data` for that Route by instead navigating to another Route. You can create a redirect Response using [Server.Response.temporaryRedirect](https://package.elm-lang.org/packages/dillonkearns/elm-pages/latest/Server-Response#temporaryRedirect), or using the code in the generated `Route` module `Route.redirectTo` (this takes an argument of your `Route` type so it is more type-safe).

## Forms

Expand Down
8 changes: 4 additions & 4 deletions examples/docs/content/docs/11-elm-pages-scripts.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ description: You can run scripts written in pure Elm with the `elm-pages run` CL

# `elm-pages` Scripts

The `elm-pages run` command lets you use [`BackendTask`](https://package.elm-lang.org/packages/dillonkearns/elm-pages-v3-beta/latest/BackendTask)'s to do scripting tasks with Elm. The goal is to make it as simple as possible to write a Script in Elm and run it from the command line. You can use any of the techniques from BackendTask's to read files, make HTTP requests, get environment variables, or async NodeJS functions through [`BackendTask.Custom.run`](https://package.elm-lang.org/packages/dillonkearns/elm-pages-v3-beta/latest/BackendTask-Custom#run).
The `elm-pages run` command lets you use [`BackendTask`](https://package.elm-lang.org/packages/dillonkearns/elm-pages/latest/BackendTask)'s to do scripting tasks with Elm. The goal is to make it as simple as possible to write a Script in Elm and run it from the command line. You can use any of the techniques from BackendTask's to read files, make HTTP requests, get environment variables, or async NodeJS functions through [`BackendTask.Custom.run`](https://package.elm-lang.org/packages/dillonkearns/elm-pages/latest/BackendTask-Custom#run).

## Quick Start

Expand Down Expand Up @@ -48,7 +48,7 @@ npx elm-pages run Hello

The `script/` folder is a regular Elm project folder. That means it will need to have an `elm.json` file, and an Elm module in the `src/` folder (or whichever `source-directories` path you define in your `elm.json`). It will also need `elm-pages` installed as a dependency.

If you use [`BackendTask.Custom.run`](https://package.elm-lang.org/packages/dillonkearns/elm-pages-v3-beta/latest/BackendTask-Custom#run) from your Script, it will use the `custom-backend-task.ts` (or `.js`) file defined in your `script/` project folder.
If you use [`BackendTask.Custom.run`](https://package.elm-lang.org/packages/dillonkearns/elm-pages/latest/BackendTask-Custom#run) from your Script, it will use the `custom-backend-task.ts` (or `.js`) file defined in your `script/` project folder.

The name `script/` is a convention and is not required. You can execute the `elm-pages run` command on any file as long as it is part of an Elm project (in its `source-directories`), and that project has `elm-pages` installed as a dependency.

Expand Down Expand Up @@ -140,7 +140,7 @@ run script/src/Stars.elm --user elm --name json

## `FatalError`'s

If the `BackendTask` in your script resolves to a [`FatalError`](https://package.elm-lang.org/packages/dillonkearns/elm-pages-v3-beta/latest/FatalError), the script will print the error message and exit with a non-zero exit code. As with any `BackendTask`, if you want to ensure that your script will not encounter a `FatalError`, you can ensure that you have handled every possible error by using a value with the type `BackendTask Never ()`.
If the `BackendTask` in your script resolves to a [`FatalError`](https://package.elm-lang.org/packages/dillonkearns/elm-pages/latest/FatalError), the script will print the error message and exit with a non-zero exit code. As with any `BackendTask`, if you want to ensure that your script will not encounter a `FatalError`, you can ensure that you have handled every possible error by using a value with the type `BackendTask Never ()`.

## Scaffolding a Route Module

Expand All @@ -152,7 +152,7 @@ The `elm-pages` package includes some modules that help you generate Elm files.

`elm-codegen` helps ensure that you are generating valid code by generating functions that mirror the code they will generate, giving you an extra layer of type safety. `elm-pages` Scripts are general-purpose, so you can do what you want with them, but there are some built-in helpers to make it easy for you to scaffold code for your `elm-pages` app that work well with `elm-codegen`.

Take a look at [the `AddRoute.elm` Script from the `elm-pages` starter repo](https://github.com/dillonkearns/elm-pages-3-alpha-starter/blob/main/script/src/AddRoute.elm). This Script is a great starting point for customizing your own scaffolding Scripts for your project. It is designed to lock in the essential details for defining a Route Module and a Form, while leaving the rest up to you to customize in the script. See [`Scaffold.Route`](https://package.elm-lang.org/packages/dillonkearns/elm-pages-v3-beta/latest/Scaffold-Route) and [`Scaffold.Form`](https://package.elm-lang.org/packages/dillonkearns/elm-pages-v3-beta/latest/Scaffold-Route) in the docs.
Take a look at [the `AddRoute.elm` Script from the `elm-pages` starter repo](https://github.com/dillonkearns/elm-pages-3-alpha-starter/blob/main/script/src/AddRoute.elm). This Script is a great starting point for customizing your own scaffolding Scripts for your project. It is designed to lock in the essential details for defining a Route Module and a Form, while leaving the rest up to you to customize in the script. See [`Scaffold.Route`](https://package.elm-lang.org/packages/dillonkearns/elm-pages/latest/Scaffold-Route) and [`Scaffold.Form`](https://package.elm-lang.org/packages/dillonkearns/elm-pages/latest/Scaffold-Route) in the docs.

## Compiling Scripts to an Executable JavaScript File

Expand Down
4 changes: 2 additions & 2 deletions examples/docs/content/docs/13-error-pages.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Error Pages

In your server-rendered routes, you can choose to short-circuit rendering your route and instead render an error page. This is useful for things like 404 pages, or 500 pages, or even custom error pages for specific errors. In order to render your route, you must resolve to the `Data` type in your Route module with [Server.Response.render](https://package.elm-lang.org/packages/dillonkearns/elm-pages-v3-beta/latest/Server-Response#render).
In your server-rendered routes, you can choose to short-circuit rendering your route and instead render an error page. This is useful for things like 404 pages, or 500 pages, or even custom error pages for specific errors. In order to render your route, you must resolve to the `Data` type in your Route module with [Server.Response.render](https://package.elm-lang.org/packages/dillonkearns/elm-pages/latest/Server-Response#render).

For example, let's say you have the following Route module:

Expand Down Expand Up @@ -29,7 +29,7 @@ data routeParams =
)
```

In this example, we are attempting to lookup a user profile by id. If we find the profile, we render the route. If we don't find the profile, we render a 404 error page. A good rule of thumb is that if you are able to successfully resolve the `Data` for your Route, use `Server.Response.render`. If you are unable to resolve the `Data` for your Route, use [`Server.Response.errorPage`](https://package.elm-lang.org/packages/dillonkearns/elm-pages-v3-beta/latest/Server-Response#errorPage).
In this example, we are attempting to lookup a user profile by id. If we find the profile, we render the route. If we don't find the profile, we render a 404 error page. A good rule of thumb is that if you are able to successfully resolve the `Data` for your Route, use `Server.Response.render`. If you are unable to resolve the `Data` for your Route, use [`Server.Response.errorPage`](https://package.elm-lang.org/packages/dillonkearns/elm-pages/latest/Server-Response#errorPage).

## Custom Error Types

Expand Down
2 changes: 1 addition & 1 deletion examples/docs/content/docs/15-adapters.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ export default {

You can also use the adapter API directly to build your own adapter. An adapter is an async function that can execute any scripting setup needed to move/copy/generate files or do other setup to prepare an `elm-pages` app for deployment on a given hosting provider. The function return value is ignored, it is just an async function that can perform some actions.

You can see [the full implementation of the Netlify adapter script](https://github.com/dillonkearns/elm-pages-v3-beta/blob/master/adapter/netlify.js) for reference.
You can see [the full implementation of the Netlify adapter script](https://github.com/dillonkearns/elm-pages/blob/master/adapter/netlify.js) for reference.

It is run after `elm-pages build` has generated the `dist/` folder, so you can assume that the `dist/` folder exists and contains the output of `elm-pages build`.

Expand Down
2 changes: 1 addition & 1 deletion src/Pages/ConcurrentSubmission.elm
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ from your `Route` module through `app.concurrentSubmissions` as a `Dict String (
You can use this state to declaratively derive Pending UI or Optimistic UI from your pending submissions (without managing the state in your `Model`, since `elm-pages`
manages form submission state for you).
You can [see the full-stack TodoMVC example](https://github.com/dillonkearns/elm-pages-v3-beta/blob/master/examples/todos/app/Route/Visibility__.elm) for a complete example of deriving Pending UI state from `app.concurrentSubmissions`.
You can [see the full-stack TodoMVC example](https://github.com/dillonkearns/elm-pages/blob/master/examples/todos/app/Route/Visibility__.elm) for a complete example of deriving Pending UI state from `app.concurrentSubmissions`.
For example, this how the TodoMVC example derives the list of new items that are being created (but are still pending).
Expand Down
4 changes: 2 additions & 2 deletions src/Pages/Script.elm
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ module Pages.Script exposing

{-| An elm-pages Script is a way to execute an `elm-pages` `BackendTask`.
Read more about using the `elm-pages` CLI to run (or bundle) scripts, plus a brief tutorial, at <https://elm-pages-v3.netlify.app/docs/elm-pages-scripts>.
Read more about using the `elm-pages` CLI to run (or bundle) scripts, plus a brief tutorial, at <https://elm-pages.com/docs/elm-pages-scripts>.
@docs Script
Expand Down Expand Up @@ -154,7 +154,7 @@ pass in additional options for the script.
Uses <https://package.elm-lang.org/packages/dillonkearns/elm-cli-options-parser/latest/>.
Read more at <https://elm-pages-v3.netlify.app/docs/elm-pages-scripts/#adding-command-line-options>.
Read more at <https://elm-pages.com/docs/elm-pages-scripts/#adding-command-line-options>.
-}
withCliOptions : Program.Config cliOptions -> (cliOptions -> BackendTask FatalError ()) -> Script
Expand Down
2 changes: 1 addition & 1 deletion src/Scaffold/Form.elm
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ Using the `AddRoute` script from the default starter template, you can run a com
`npx elm-pages run AddRoute Profile.Username_.Edit first last bio:textarea dob:date` to generate a Route module `app/Route/Profile/Username_/Edit.elm`
with the wiring form a `Form`.
[Learn more about writing and running elm-pages Scripts for scaffolding](https://elm-pages-v3.netlify.app/docs/elm-pages-scripts#scaffolding-a-route-module).
[Learn more about writing and running elm-pages Scripts for scaffolding](https://elm-pages.com/docs/elm-pages-scripts#scaffolding-a-route-module).
@docs Kind, provide, restArgsParser
Expand Down
2 changes: 1 addition & 1 deletion src/Scaffold/Route.elm
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ module Scaffold.Route exposing
{-| This module provides some functions for scaffolding code for a new Route Module. It uses [`elm-codegen`'s API](https://package.elm-lang.org/packages/mdgriffith/elm-codegen/latest/) for generating code.
Typically you'll want to use this via the `elm-pages run` CLI command. The default starter template includes a Script that uses these functions, which you can tweak to customize your scaffolding commands.
[Learn more about writing and running elm-pages Scripts for scaffolding](https://elm-pages-v3.netlify.app/docs/elm-pages-scripts#scaffolding-a-route-module).
[Learn more about writing and running elm-pages Scripts for scaffolding](https://elm-pages.com/docs/elm-pages-scripts#scaffolding-a-route-module).
It's typically easiest to modify the `AddRoute` script from the starter template and adjust it to your needs rather than writing one from scratch.
Expand Down
2 changes: 1 addition & 1 deletion src/Server/Response.elm
Original file line number Diff line number Diff line change
Expand Up @@ -172,7 +172,7 @@ render data =

{-| Instead of rendering the current Route Module, you can render an `ErrorPage` such as a 404 page or a 500 error page.
[Read more about Error Pages](https://elm-pages-v3.netlify.app/docs/error-pages) to learn about
[Read more about Error Pages](https://elm-pages.com/docs/error-pages) to learn about
defining and rendering your custom ErrorPage type.
-}
Expand Down

0 comments on commit 19a9aaa

Please sign in to comment.