/ 
Dancer-Plugin-Params-Normalization-0.52
River stage zero No dependents
/ Dancer::Plugin::Params::Normalization

NAME

Dancer::Plugin::Params::Normalization - A plugin for normalizing query parameters in Dancer

VERSION

version 0.52

DESCRIPTION

This plugin helps you normalize the query parameters in Dancer.

SYNOPSYS

In configuration file :

plugins:
  Params::Normalization:
    method: lowercase

In your Dancer App :

package MyWebService;

use Dancer;
use Dancer::Plugin::Params::Normalization;

get '/hello' => sub {
    'Hello ' . params->{name};
};

Requests

# This will work, as NAME will be lowercased to name
curl http://mywebservice/test?NAME=John

CONFIGURATION

The behaviour of this plugin is primarily setup in the configuration file, in your main config.yml or environment config file.

# Example 1 : always lowercase all parameters
plugins:
  Params::Normalization:
    method: lowercase

# Example 2 : always uppercase all parameters
plugins:
  Params::Normalization:
    method: uppercase

# Example 3 : on-demand uppercase parameters that starts with 'a'
plugins:
  Params::Normalization:
    general_rule: ondemand
    method: uppercase
    params_filter: ^[aA]

Here is a list of configuration fields:

general_rule

This field specifies if the normalization should always happen, or on demand.

Value can be of:

always

Parameters will be normalized behind the scene, automatically.

ondemand

Parameters are not normalized by default. The code in the route definition needs to call normalize_params to have the parameters normalized

Default value: always

method

This field specifies what kind of normalization to do.

Value can be of:

lowercase

parameters names are lowercased

uppercase

parameters names are uppercased

ucfirst

parameters names are ucfirst'ed

Custom::Class::Name

Used to execute a custom normalization method.

The given class should inherit Dancer::Plugin::Params::Normalization::Abstract and implement the method normalize. this method takes in argument a hashref of the parameters, and returns a hashrefs of the normalized parameters. It can have an init method if it requires initialization.

As an example, see Dancer::Plugin::Params::Normalization::Trim, contributed by Sam Batschelet, and part of this distribution.

Using a custom normalization is incompatible with params_filter (see below).

passthrough

Doesn't do any normalization. Useful to disable the normalization without to change the code

Default value: passthrough

params_types

Optional, used to specify on which parameters types the normalization should apply. The value is an array, that can contain any combination of these strings:

query

If present in the array, the parameters from the query string will be normalized

body

If present in the array, the parameters from the request's body will be normalized

route

If present in the array, the parameters from the route definition will be normalized

Default value: [ 'query', 'body']

params_filter

Optional, used to filters which parameters the normalization should apply to.

The value is a regexp string that will be evaluated against the parameter names.

no_conflict_warn

Optional, if set to a true value, the plugin won't issue a warning when parameters name conflict happens. See "PARAMETERS NAMES CONFLICT".

KEYWORDS

normalize

The general usage of this plugin is to enable normalization automatically in the configuration.

However, If the configuration field general_rule is set to ondemand, then the normalization doesn't happen automatically. The normalize keyword can then be used to normalize the parameters on demand.

All you have to do is add

normalize;

to your route code

PARAMETERS NAMES CONFLICT

if two normalized parameters names clash, a warning is issued. Example, if while lowercasing parameters the route receives two params : param and Param, they will be both normalized to param, which leads to a conflict. You can avoid the warning being issued by adding the configuration key no_conflict_warn to a true value.

SEE ALSO

Dancer

AUTHOR

Damien "dams" Krotkine

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Damien "dams" Krotkine.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.