Returns a query or body parameter from the current request. The raw string value is parsed before returning it. So the return value type depends on what you expect (e.g. can be Int, Text, UUID, Bool, some custom type).

When the parameter is missing or cannot be parsed, an exception is thrown and the current action is aborted. Use paramOrDefault when you want to get a default value instead of an exception, or paramOrNothing to get Nothing when the parameter is missing.

You can define a custom parameter parser by defining a ParamReader instance.

Example: Accessing a query parameter.

Let's say the request is:

GET /UsersAction?maxItems=50

We can read maxItems like this:

action UsersAction = do
    let maxItems :: Int = param "maxItems"

Example: Working with forms (Accessing a body parameter).

Let's say we have the following html form:

<form method="POST" action="/HelloWorld"
    <input type="text" name="firstname" placeholder="Your firstname" />
    <button type="submit">Send</button>
</form>

The form has firstname text field and a send button. When the form is submitted, it's send to /HelloWorld.

The following action reads the value of the submitted firstname and prints out Hello firstname:

action HelloWorldAction = do
    let firstname = param "firstname"
    renderPlain ("Hello " <> firstname)

Example: Missing parameters

Let's say the request is:

GET /HelloWorldAction

But the action requires us to provide a firstname, like:

action HelloWorldAction = do
    let firstname = param "firstname"
    renderPlain ("Hello " <> firstname)

Running the request GET /HelloWorldAction without the firstname parameter will cause an ParamNotFoundException to be thrown with:

param: Parameter 'firstname' not found

Like param, but returns Nothing the parameter is missing instead of throwing an exception.

Use paramOrDefault when you want to deal with a default value.

Example:

When calling GET /Users the variable page will be set to Nothing.

action UsersAction = do
    let page :: Maybe Int = paramOrNothing "page"

When calling GET /Users?page=1 the variable page will be set to Just 1.

Like param, but returns a default value when the parameter is missing instead of throwing an exception.

Use paramOrNothing when you want to get Maybe.

Example: Pagination

When calling GET /Users the variable page will be set to the default value 0.

action UsersAction = do
    let page :: Int = paramOrDefault 0 "page"

When calling GET /Users?page=1 the variable page will be set to 1.

Like param, but returns Left "Some error message" if the parameter is missing or invalid

Similiar to param but works with multiple params. Useful when working with checkboxes.

Given a query like:

ingredients=milk&ingredients=egg

This will return:

>>> paramList @Text "ingredients"
["milk", "egg"]

When no parameter with the name is given, an empty list is returned:

>>> paramList @Text "not_given_in_url"
[]

When a value cannot be parsed, this function will fail similiar to param.

Related: https://stackoverflow.com/questions/63875081/how-can-i-pass-list-params-in-ihp-forms/63879113

Similiar to paramOrNothing but works with multiple params. This is useful when submitting multiple input fields with the same name, and some may be empty.

Given a query like (note the ingredients in the middle that has no value):

ingredients=milk&ingredients&ingredients=egg

This will return:

>>> paramListOrNothing @Text "ingredients"
[Just "milk", Nothing, Just "egg"]

When no parameter with the name is given, an empty list is returned:

>>> paramListOrNothing @Text "not_given_in_url"
[]

Returns True when a parameter is given in the request via the query or request body.

Use paramOrDefault when you want to use this for providing a default value.

Example:

Given the request GET /HelloWorld

action HelloWorldAction = do
    if hasParam "firstname"
        then ...
        else renderPlain "Please provide your firstname"

This will render Please provide your firstname because hasParam "firstname" returns False

Returns a parameter without any parsing. Returns Nothing when the parameter is missing.

Returns all params available in the current request

Specialized version of param for Text.

This way you don't need to know about the type application syntax.

Specialized version of param for Int.

This way you don't need to know about the type application syntax.

Specialized version of param for Bool.

This way you don't need to know about the type application syntax.

Specialized version of param for UUID.

This way you don't need to know about the type application syntax.

Can be used as a default implementation for readParameter for enum structures

Example:

data Color = Yellow | Red | Blue deriving (Enum)

instance ParamReader Color where
    readParameter = enumParamReader
    readParameterJSON = enumParamReaderJSON

Provides the fill function for mass-assignment of multiple parameters to a record

Accepts a type-level list of parameter names (type-list syntax is like @'["a", "b", "c"]) and a record. Then each parameter is read from the request using the param API. The parameter value is written to the record field. Because the parameter is assigned to the record, the parameter name list can only contain attribute names of the record.

When there is a parser error, the error will be attached as a validation error to the record. The remaining parameters will continue to be read.

If a parameter is missing from the request, this will be ignored and the function proceeds as usual.

Example:

action UpdateUserAction { userId } = do
    user :: User <- fetch userId
    user
        |> fill @["firstname", "lastname", "email"]

This code will read the firstname, lastname and email from the request and assign them to the user.

Transforms Just "" to Nothing

Example: We have record called Company with a optional field comment :: Maybe Text

When we have a form that submits the comment field and the field is empty, it will not be NULL inside the database, instead it will be set to the empty string. To avoid this we can apply emptyValueToNothing #comment. This function turns the empty string into a Nothing value.

action UpdateCompanyAction { companyId } = do
    company <- fetch companyId
    company
        |> fill '["name", "comment"]
        |> emptyValueToNothing #comment
        |> updateRecord