Copyright(c) digitally induced GmbH 2020
Safe HaskellNone

IHP.Controller.Param

Description

 
Synopsis

Documentation

param :: (?requestContext :: RequestContext) => ParamReader valueType => ByteString -> valueType Source #

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

paramList :: forall valueType. (?requestContext :: RequestContext) => ParamReader valueType => ByteString -> [valueType] Source #

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

data ParamNotFoundException Source #

Thrown when a parameter is missing when calling 'param "myParam"' or related functions

paramText :: (?requestContext :: RequestContext) => ByteString -> Text Source #

Specialisied version of param for Text.

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

paramInt :: (?requestContext :: RequestContext) => ByteString -> Int Source #

Specialisied version of param for Int.

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

paramBool :: (?requestContext :: RequestContext) => ByteString -> Bool Source #

Specialisied version of param for Bool.

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

paramUUID :: (?requestContext :: RequestContext) => ByteString -> UUID Source #

Specialisied version of param for UUID.

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

hasParam :: (?requestContext :: RequestContext) => ByteString -> Bool Source #

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

paramOrDefault :: (?requestContext :: RequestContext) => ParamReader a => a -> ByteString -> a Source #

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.

paramOrNothing :: (?requestContext :: RequestContext) => ParamReader a => ByteString -> Maybe a Source #

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.

queryOrBodyParam :: (?requestContext :: RequestContext) => ByteString -> Maybe ByteString Source #

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

allParams :: (?requestContext :: RequestContext) => [(ByteString, Maybe ByteString)] Source #

Returns all params available in the current request

class ParamReader a where Source #

Input parser for param.

Parses the input bytestring. Returns Left "some error" when there is an error parsing the value. Returns Right value when the parsing succeeded.

Instances

Instances details
ParamReader Bool Source #

Parses a boolean.

Html form checkboxes usually use on or off for representation. These values are supported here.

Instance details

Defined in IHP.Controller.Param

ParamReader Double Source # 
Instance details

Defined in IHP.Controller.Param

ParamReader Float Source # 
Instance details

Defined in IHP.Controller.Param

ParamReader Int Source # 
Instance details

Defined in IHP.Controller.Param

ParamReader Integer Source # 
Instance details

Defined in IHP.Controller.Param

ParamReader ByteString Source # 
Instance details

Defined in IHP.Controller.Param

ParamReader Text Source # 
Instance details

Defined in IHP.Controller.Param

ParamReader Day Source # 
Instance details

Defined in IHP.Controller.Param

ParamReader UTCTime Source # 
Instance details

Defined in IHP.Controller.Param

ParamReader UUID Source # 
Instance details

Defined in IHP.Controller.Param

ParamReader PostgresType Source # 
Instance details

Defined in IHP.IDE.SchemaDesigner.Controller.Helper

ParamReader value => ParamReader [value] Source # 
Instance details

Defined in IHP.Controller.Param

ParamReader param => ParamReader (Maybe param) Source # 
Instance details

Defined in IHP.Controller.Param

(TypeError ('Text "Use 'let x = param \"..\"' instead of 'x <- param \"..\"'") :: Constraint) => ParamReader (IO param) Source #

Custom error hint when the param is called with do-notation

Example:

action Example = do
    myParam <- param "hello"

Now a custom type error will be shown telling the user to use let myParam = param "hello" instead of do-notation.

Instance details

Defined in IHP.Controller.Param

ParamReader (PrimaryKey model') => ParamReader (Id' model') Source # 
Instance details

Defined in IHP.Controller.Param

enumParamReader :: forall parameter. (Enum parameter, InputValue parameter) => ByteString -> Either ByteString parameter Source #

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

Example:

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

instance ParamReader Color
    readParameter = enumParamReader

class FillParams (params :: [Symbol]) record where Source #

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 aissgn them to the user.

Methods

fill :: (?requestContext :: RequestContext, HasField "meta" record MetaBag, SetField "meta" record MetaBag) => record -> record Source #

Instances

Instances details
FillParams ('[] :: [Symbol]) record Source # 
Instance details

Defined in IHP.Controller.Param

Methods

fill :: record -> record Source #

(FillParams rest record, KnownSymbol fieldName, SetField fieldName record fieldType, ParamReader fieldType, HasField "meta" record MetaBag, SetField "meta" record MetaBag) => FillParams (fieldName ': rest) record Source # 
Instance details

Defined in IHP.Controller.Param

Methods

fill :: record -> record Source #

ifValid :: HasField "meta" model MetaBag => (Either model model -> IO r) -> model -> IO r Source #

ifNew :: forall record id. (?requestContext :: RequestContext, ?modelContext :: ModelContext, HasField "id" record id, Default id, Eq id) => (record -> record) -> record -> record Source #

emptyValueToNothing :: forall (name :: Symbol) model a. (KnownSymbol name, HasField name model (Maybe a), SetField name model (Maybe a), MonoFoldable a) => Proxy name -> model -> model Source #