Server.Response

Responses

type alias Response data error =

PageServerResponse data error

Response's for Route Modules

In a server-rendered Route Module, you return a Response. You'll typically want to return one of 3 types of Responses from your Route Modules:

Server.Response.render to render the current Route Module
Server.Response.errorPage to render an ErrorPage
Server.Response.temporaryRedirect to redirect to another page (the easiest way to build a redirect response is with Route.redirectTo : Route -> Response data error).

    import Server.Response as Response
    import Route

    data routeParams request =
        case loggedInUser request of
            Just user ->
                findProjectById routeParams.id user
                |> BackendTask.map
                    (\maybeProject ->
                        case maybeProject of
                            Just project ->
                                Response.render project

                            Nothing ->
                                Response.errorPage ErrorPage.notFound
                    )
            Nothing ->
                -- the generated module `Route` contains a high-level helper for returning a redirect `Response`
                Route.redirectTo Route.Login

Render Responses

render : data -> Response data error

Render the Route Module with the supplied data. Used for both the data and action functions in a server-rendered Route Module.

Response.render project

map :

(data -> mappedData)

-> Response data error

-> Response mappedData error

Maps the data for a Render response. Usually not needed, but always good to have the option.

Rendering Error Pages

errorPage : errorPage -> Response data errorPage

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 to learn about defining and rendering your custom ErrorPage type.

mapError :

(errorPage -> mappedErrorPage)

-> Response data errorPage

-> Response data mappedErrorPage

Maps the error for an ErrorPage response. Usually not needed, but always good to have the option.

Redirects

temporaryRedirect : String -> Response data error

permanentRedirect : String -> Response data error

Build a 308 permanent redirect response.

Permanent redirects tell the browser that a resource has permanently moved. If you redirect because a user is not logged in, then you do not want to use a permanent redirect because the page they are looking for hasn't changed, you are just temporarily pointing them to a new page since they need to authenticate.

Permanent redirects are aggressively cached so be careful not to use them when you mean to use temporary redirects instead.

If you need to specifically rely on a 301 permanent redirect (see https://stackoverflow.com/a/42138726 on the difference between 301 and 308), use customResponse instead.

Response's for Server-Rendered ApiRoutes

When defining your server-rendered ApiRoute's (ApiRoute.serverRender) in your app/Api.elm module, you can send a low-level server Response. You can set a String body, a list of headers, the status code, etc. The Server Response helpers like json and temporaryRedirect are just helpers for building up those low-level Server Responses.

Render Responses are a little more special in the way they are connected to your elm-pages app. They allow you to render the current Route Module. To do that, you'll need to pass along the data for your Route Module.

You can use withHeader and withStatusCode to customize either type of Response (Server Responses or Render Responses).

Response Body

json : Value -> Response data error

Build a JSON body from a Json.Encode.Value.

Json.Encode.object
    [ ( "message", Json.Encode.string "Hello" ) ]
    |> Response.json

Sets the Content-Type to application/json.

plainText : String -> Response data error

Build a Response with a String body. Sets the Content-Type to text/plain.

Response.plainText "Hello"

emptyBody : Response data error

Build a Response with no HTTP response body.

body : String -> Response data error

Same as plainText, but doesn't set a Content-Type.

bytesBody : Bytes -> Response data error

Build a Response with a Bytes.

Under the hood, it will be converted to a base64 encoded String with isBase64Encoded = True. Your adapter will need to handle isBase64Encoded to turn it into the appropriate response.

base64Body : String -> Response data error

Build a Response with a String that should represent a base64 encoded value.

Your adapter will need to handle isBase64Encoded to turn it into the appropriate response.

Response.base64Body "SGVsbG8gV29ybGQ="

Amending Responses

withHeader : String -> String -> Response data error -> Response data error

Add a header to the response.

Response.plainText "Hello!"
    -- allow CORS requests
    |> Response.withHeader "Access-Control-Allow-Origin" "*"
    |> Response.withHeader "Access-Control-Allow-Methods" "GET, POST, OPTIONS"

withHeaders :

List ( String, String )

-> Response data error

Same as withHeader, but allows you to add multiple headers at once.

Response.plainText "Hello!"
    -- allow CORS requests
    |> Response.withHeaders
        [ ( "Access-Control-Allow-Origin", "*" )
        , ( "Access-Control-Allow-Methods", "GET, POST, OPTIONS" )
        ]

withStatusCode : Int -> Response data Never -> Response data Never

Set the HTTP Response status code for the Response.

Response.plainText "Not Authorized"
    |> Response.withStatusCode 401

withSetCookieHeader : SetCookie -> Response data error -> Response data error

Set a Server.SetCookie value on the response.

The easiest way to manage cookies in your Routes is through the Server.Session API, but this provides a more granular way to set cookies.

Internals

toJson : Response Never Never -> Value

For internal use or more advanced use cases for meta frameworks.