amelinium.http.middleware.coercion
added in 1.0.0
amelinium service, HTTP parameters coercion.
explain-errors-simple
(explain-errors-simple data translate-sub)
Like recode-errors-simple
but each error map contains the additional key :parameter/message
containing a human-readable messages created with translation function translate-sub
. Enriches the output map with :parameter/name
, :error/summary
and :error/description
entries. To be used in API responses.
get-form-params
(get-form-params req ids)
Using the request map req
gets the values of all parameters from ids
(expressed as a sequence of strings). Returns a map where keys are parameter names and values are parameter values.
handle-form-errors
(handle-form-errors req form-keep session-key)
Tries to obtain form errors from a previously visited page, saved as a session variable :form-errors
or as a query parameter form-errors
.
The result is a map of at least 3 keys: :errors
(parsed errors), :dest
(destination URI, matching current URI if using a session variable), :params
(map of other parameters and their values, only when session variable is a source).
The resulting map is then added to a request map under the :form/errors
key and can be later used by form generating or other HTML rendering functions to display errors and previous form values.
It is intended to be used as a wrapper in coercion middleware so it can catch erroneous form fields which were reported back (via POST redirect using 307 code) and remove them from the request map’s parameter maps to avoid trouble when pre-filling in forms.
init-coercer
(init-coercer k {:keys [init initializer config enabled?], :or {enabled? true}})
init-exceptions-handler
(init-exceptions-handler k {enabled? :enabled?, exception-handler :handler, responder :responder, raiser :raiser, :or {enabled? true, exception-handler default-exception-handler, responder identity, raiser (fn* [p1__52224#] (throw p1__52224#))}})
inject-errors
(inject-errors req errors)
Takes coercion errors, parses them, and puts into a newly created map under the key named :errors
among with a current URI associated with the key :dest
. The whole map is then injected into a request map req
under the key :form/errors
.
join-errors
(join-errors errors)
Used to produce a string containing parameter names and their types (as defined in schema) from a coercion errors simple map or coercion errors sequence (produced by list-errors-simple
or map-errors-simple
respectively).
For a non-empty string it simply returns it. Used to generate a query string containing form errors in a form of parameter-id
or parameter-id:parameter-type
separated by commas.
The whole string can then be encoded and used as a query parameter (i.e. :form-errors
) when redirecting anonymous user to a page with a previous form which needs to be corrected.
join-errors-with-values
(join-errors-with-values errors)
Used to produce a string containing parameter names and their types (as defined in schema) from a coercion errors simple map or coercion errors sequence (produced by list-errors-simple
or map-errors-simple
respectively). For anon-empty string it simply returns it. Used to generate a query string containing form errors in a form of parameter-id
or parameter-id:parameter-type:parameter-value
separated by commas. The whole string can then be encoded and used as a query parameter :form-errors
when redirecting anonymous user to a page with a previous form which needs to be corrected. Be aware that it might be hard to parse the output string if a value contains a comma character.
join-param-names
(join-param-names params)
Used to produce a string containing parameter names from a map or a sequence.
list-errors-simple
(list-errors-simple data)
Returns a sequence of coercion errors consisting of 3-element sequences. First element of each being a parameter identifier (a string), second element being a parameter type described by schema (if detected, a string), and third being its current value. Takes an exception data map which should contain the :coercion
key. Used, among other applications, to expose form errors to another page which should indicate them to a visitor.
map-errors-simple
(map-errors-simple data)
Like list-errors-simple
but returns a map in which keys are parameter names and values are parameter types (as defined in a schema used to validate and coerce them). Used to pass form errors to another page which should expose them to a visitor.
param-type
(param-type e)
Takes a coercion error expressed as a map e
and returns a string with parameter type if the type can easily be obtained (is a simple name expressed as a string or a string representation of keyword). For very complex schemas (which do not consist of a keyword or a vector with keyword at their first position) it returns nil
.
parse-errors
(parse-errors errors)
Transforms a string previously exposed with join-errors
, a list created with list-errors-simple
or a map resulted from calling map-errors-simple
, into a map containing parameter names as keys and parameter types as values.
Used to parse input from a query string or saved session variable when visiting a page containing a previously visited form which needs to be corrected (after redirecting to it).
The explain-form-error
template tag can make use of such map to decide whether an input field had invalid data.
parse-param-names
(parse-param-names s)
Takes a parameter names separated by commas, removes duplicates and empty strings, and returns a sequence of strings.
recode-errors-simple
(recode-errors-simple data)
Uses exception data to recode coercion errors in a form of a map. To be used mainly with API handlers. For web form error reporting map-errors-simple
, list-errors-simple
and explain-errors-simple
are better suited.
remove-params
(remove-params req to-remove to-keep)
Removes all parameters from known locations of the given request map req
except of parameters listed in to-keep
unless they also exist in to-remove
.
split-error
(split-error param-id param-type param-value)
(split-error param-id param-type)
(split-error param-id)
Takes param-id
and optional param-type
and tries to clean-up their string representations to produce a 3-element vector. When only 1 argument is present or when the second argument is nil
or empty, it will try to parse the first argument so if it contains a colon character it will be split into three parts: parameter ID, parameter type and value. Used as a helper by parse-errors
and by argument parsers in template tags.
translate-error
(translate-error req param-error-properties req param-id param-type req lang param-id param-type translate-sub param-error-properties translate-sub param-id param-type)
Takes a translation function with already applied language ID or a request map, parameter ID and parameter type and tries to find the best translations describing the erroneous field. Returns a map with the following keys :parameter/name
, :error/summary
and :error/description
. To be used after receiving form errors data after a redirect.
valid-param-name?
(valid-param-name? s)
Returns true
if the given parameter name or parameter type name matches a pattern and can be sefely converted to an identifier (a keyword or a symbol).