NAME

CatalystX::RequestModel::ContentBodyParser::FormURLEncoded - Parse HTML Form POSTS

SYNOPSIS

    TBD

DESCRIPTION

Given a flat list of HTML Form posted parameters will attempt to convert it to a hash of values, with nested and arrays of nested values as needed. For example you can convert something like:

    .-------------------------------------+--------------------------------------.
    | Parameter                           | Value                                |
    +-------------------------------------+--------------------------------------+
    | person.username                     | jjn                                  |
    | person.first_name [multiple]        | 2, John                              |
    | person.last_name                    | Napiorkowski                         |
    | person.password                     | abc123                               |
    | person.password_confirmation        | abc123                               |
    '-------------------------------------+--------------------------------------'

Into:

    {
      first_name => "John",
      last_name => "Napiorkowski",
      username => "jjn",
    }

Or:

    .-------------------------------------+--------------------------------------.
    | Parameter                           | Value                                |
    +-------------------------------------+--------------------------------------+
    | person.first_name [multiple]        | 2, John                              |
    | person.last_name                    | Napiorkowski                         |
    | person.person_roles[0]._nop         | 1                                    |
    | person.person_roles[1].role_id      | 1                                    |
    | person.person_roles[2].role_id      | 2                                    |
    | person.username                     | jjn                                  |
    '-------------------------------------+--------------------------------------'

Into:

    {
      first_name => "John",
      last_name => "Napiorkowski",
      username => "jjn",
      person_roles => [
        {
          role_id => 1,
        },
        {
          role_id => 2,
        },
      ],
    }

We define some settings described below to help you deal with some of the issues you find when trying to parse HTML form posted body content. For now please see the test cases for more examples.

VALUE PARSER CONFIGURATION

This parser defines the following attribute properties which effect how a value is parsed.

flatten

If the value associated with a field is an array, flatten it to a single value. Its really a hack to deal with HTML form POST and Query parameters since the way those formats work you can't be sure if a value is flat or an array.

always_array

Similar to flatten but opposite, it forces a value into an array even if there's just one value.

NOTE: The attribute property settings flatten and always_array are currently exclusive (only one of the two will apply if you supply both. The always_array property always takes precedence. At some point in the future supplying both might generate an exception so its best not to do that. I'm only leaving it allowed for now since I'm not sure there's a use case for both.

INDEXING

When POSTing deeply nested forms with repeated elements you can use a naming convention to indicate ordering:

    param[index]...

For example:

    .-------------------------------------+--------------------------------------.
    | Parameter                           | Value                                |
    +-------------------------------------+--------------------------------------+
    | person.person_roles[0]._nop         | 1                                    |
    | person.person_roles[1].role_id      | 1                                    |
    | person.person_roles[2].role_id      | 2                                    |
    | person.person_roles[].role_id       | 3                                    |
    '-------------------------------------+--------------------------------------'

Could convert to:

    [
      {
        role_id => 1,
      },
      {
        role_id => 2,
      },
    ]

Please note the the index value is just used for ordering purposed, the actual value is tossed after its used to do the sorting. Also if you just need to add a new item to the end of the indexed list you can use an empty index '[]' as in the example above. You might find this useful if you are building HTML forms and need to tack on an extra value but don't know the last index.

HTML FORM POST ISSUES

Many HTML From input controls don't make it easy to send a default value if they are left blank. For example HTML checkboxes will not send a 'false' value if you leave them unchecked. To deal with this issue you can either set a default attribute property or you can use a hidden field to send the 'unchecked' value and rely on the flatten option to choose the correct value.

You may also have this issue with indexed parameters if the indexed parameters are associated with a checkbox or other control that sends no default value. In that case you can do the same thing, either set a default empty arrayref as the value for the attribute or send a ignored indexed parameter (as in the above example '_nop').

EXCEPTIONS

See CatalystX::RequestModel::ContentBodyParser for exceptions.

AUTHOR

See CatalystX::RequestModel.

COPYRIGHT

See CatalystX::RequestModel.

LICENSE

See CatalystX::RequestModel.

cpanm CatalystX::RequestModel

perl -MCPAN -e shell
install CatalystX::RequestModel