Recipes

This section describes best-practise solutions to the common tasks you are facing when building web applications.

Static Pages

For adding a static page like e.g. a start page, terms of service, privacy, pricing etc. you usually use a normal controller which just renders the view for that page. The only special thing is, that you might want to customize the routing to have SEO-friendly urls.

Let’s say we have a controller like this defined in Web.Types:

data StaticController
    = AboutAction
    | TermsAction
    deriving (Eq, Show, Data)

The controller implementation will look like this in Web.Controller.Static:

module Web.Controller.Static where

import Web.Controller.Prelude
import Web.View.Static.Terms
import Web.View.Static.About

instance Controller StaticController where
    action TermsAction = render TermsView
    action AboutAction = render AboutView

We can now customize the routing in Web.Routes by first deleting the instance AutoRoute StaticController statement to delete the auto generated routing configuration and append:

instance HasPath StaticController where
    pathTo TermsAction = "/terms"
    pathTo AboutAction = "/about"

instance CanRoute StaticController where
    parseRoute' = 
        (string "/terms" <* endOfInput >> pure TermsAction)
        <|> (string "/about" <* endOfInput >> pure AboutAction)

Now the terms can be reached at /terms instead of /Terms. The about is at /about now, instead of /About.

Uploading a user profile picture

You can easily upload a user profile picture using uploadImageWithOptions inside your UpdateUserAction:

action UpdateUserAction { userId } = do
    user <- fetch userId
    accessDeniedUnless (userId == currentUserId)

    let profilePictureOptions = ImageUploadOptions
            { convertTo = "jpg"
            , imageMagickOptions = "-resize '1024x1024^' -gravity north -extent 1024x1024 -quality 85% -strip"
            }

    user
        |> fill @["firstname", "lastname", "pictureUrl"]
        |> uploadImageWithOptions profilePictureOptions #pictureUrl
        >>= ifValid \case
            Left user -> render EditView { .. }
            Right user -> do
                user <- user |> updateRecord
                setSuccessMessage "Your changes have been saved."
                redirectTo EditUserAction { .. }

This accepts any kind of image file compatible with imagemagick, resize it, reduce the image quality, strip all meta information and save it as jpg. The file is stored inside the static/uploads folder in the project (directory will be created if it does not exist).

In your view, just use the image url like <img src={get #pictureUrl currentUser}/>.

Checking that the current user has permission to access the action

Use accessDeniedUnless like this:

action EditPostAction { postId } = do
    post <- fetch postId
    accessDeniedUnless (get #authorId post == currentUserId)
    
    renderHtml EditView { .. }

Creating a custom validator

If needed you can just write your own constraint, e.g. like this:

nonEmpty :: Text -> ValidatorResult
nonEmpty "" = Failure "This field cannot be empty"
nonEmpty _ = Success

isAge :: Int -> ValidatorResult
isAge = isInRange (0, 100)

Checking that an email is unique

Use validateIsUnique.

Don’t auto-open the app in the browser

To prevent the IHP dev server automatically opening the dev tooling in your web browser when running ./start, set the IHP_BROWSER env variable to echo:

export IHP_BROWSER=echo
./start

This will then just print out the url which would be opened on start.