catalyst::plugin::unicode::encoding(3pm) [debian man page]
Catalyst::Plugin::Unicode::Encoding(3pm) User Contributed Perl Documentation Catalyst::Plugin::Unicode::Encoding(3pm)NAME
Catalyst::Plugin::Unicode::Encoding - Unicode aware Catalyst
SYNOPSIS
use Catalyst qw[Unicode::Encoding];
MyApp->config( encoding => 'UTF-8' ); # A valid Encode encoding
DESCRIPTION
On request, decodes all params from encoding into a sequence of logical characters. On response, encodes body into encoding.
METHODS
encoding
Returns an instance of an "Encode" encoding
print $c->encoding->name
OVERLOADED METHODS
finalize_headers
Encodes body into encoding.
prepare_uploads
Decodes parameters, query_parameters, body_parameters and filenames in file uploads into a sequence of logical characters.
prepare_action
Decodes request arguments (i.e. "$c->request->arguments") and captures (i.e. "$c->request->captures").
setup
Setups "$c->encoding" with encoding specified in "$c->config->{encoding}".
handle_unicode_encoding_exception ($exception_context)
Method called when decoding process for a request fails.
An $exception_context hashref is provided to allow you to override the behaviour of your application when given data with incorrect
encodings.
The default method throws exceptions in the case of invalid request parameters (resulting in a 500 error), but ignores errors in upload
filenames.
The keys passed in the $exception_context hash are:
param_value
The value which was not able to be decoded.
error_msg
The exception recieved from Encode.
encoding_step
What type of data was being decoded. Valid values are (currently) "params" - for request parameters / arguments / captures and
"uploads" - for request upload filenames.
SEE ALSO
Encode, Encode::Encoding, Catalyst::Plugin::Unicode, Catalyst.
AUTHORS
Christian Hansen, "ch@ngmedia.com"
Masahiro Chiba
Tomas Doran, "bobtfish@bobtfish.net"
LICENSE
This library is free software . You can redistribute it and/or modify it under the same terms as perl itself.
perl v5.14.2 2012-05-09 Catalyst::Plugin::Unicode::Encoding(3pm)
Check Out this Related Man Page
HTML::FormFu::Manual::Unicode(3pm) User Contributed Perl Documentation HTML::FormFu::Manual::Unicode(3pm)NAME
HTML::FormFu::Manual::Unicode - Working with unicode
DESCRIPTION
Working with unicode.
For a practical example, see the Catalyst application in the "examples/unicode" directory in this distribution.
ASSUMPTIONS
In this tutorial, we're assuming that all encodings are UTF-8. It's relatively simple to combine different encodings from different
sources, but that's beyond the scope of this tutorial.
For simplicity, we're also going to assume that you're using Catalyst for your web-framework, DBIx::Class for your database ORM, TT for
your templating system, and YAML format "HTML::FormFu" configuration files, with YAML::XS installed. However, the principles we'll cover
should translate to whatever technologies you chose to work with.
BASICS
To make it short and sweet: you must decode all data going into your program, and encode all data coming from your program.
Skip to "CHANGES REQUIRED" if you want to see what you need to do without any other explanation.
INPUT
Input parameters from the browser
If you're using "Catalyst", Catalyst::Plugin::Unicode will decode all input parameters sent from the browser to your application - see
"Catalyst Configuration".
If you're using some other framework or, in any case, you need to decode the input parameters yourself, please take a look at
HTML::FormFu::Filter::Encode.
Data from the database
If you're using DBIx::Class, DBIx::Class::UTF8Columns is likely the best options, as it will decode all input retrieved from the database -
see "DBIx::Class Configuration".
In other cases (i.e. plain DBI), you still need to decode the string data coming from the database. This varies depending on the database
server. For MySQL, for instance, you can use the "mysql_enable_utf8" attribute: see DBD::mysql documentation for details.
Your template files
Set TT to decode all template files - see "TT Configuration".
HTML::FormFu's own template files
Set "HTML::FormFu" to decode all template files - see "HTML::FormFu Template Configuration".
HTML::FormFu form configuration files
If you're using "YAML" config files, your files will automatically be decoded by "load_config_file|HTML::FormFu/load_config_file" and
"load_config_filestem|HTML::FormFu/load_config_filestem".
If you have Config::General config files, your files will automatically be decoded by "load_config_file|HTML::FormFu/load_config_file" and
"load_config_filestem|HTML::FormFu/load_config_filestem", which automatically sets Config::General's "-UTF8" setting.
Your perl source code
Any perl source files which contain Unicode characters must use the utf8 module.
OUTPUT
Data saved to the database
With "DBIx::Class", DBIx::Class::UTF8Columns will encode all data sent to the database - see "DBIx::Class Configuration".
HTML sent to the browser
With "Catalyst", Catalyst::Plugin::Unicode will encode all output sent from your application to the browser - see "Catalyst Configuration".
In other circumstances you need to be sure to output your Unicode (decoded) strings in UTF-8. To do this you can encode your output before
it's sent to the browser with something like:
use utf8;
if ( $output && utf8::is_utf8($output) ){
utf8::encode( $output ); # Encodes in-place
}
Another option is to set the "binmode" for "STDOUT":
bindmode STDOUT, ':utf8';
However, be sure to do this only when sending UTF-8 data: if you're serving images, PFD files, etc, "binmode" should remain set to ":raw".
CHANGES REQUIRED
Catalyst Configuration
Add Catalyst::Plugin::Unicode to the list of Catalyst plugins:
use Catalyst qw( ConfigLoader Static::Simple Unicode );
DBIx::Class Configuration
Add DBIx::Class::UTF8Columns to the list of components loaded, for each table that has columns storing unicode:
__PACKAGE__->load_components( qw( UTF8Columns HTML::FormFu PK::Auto Core ) );
Pass each column name that will store unicode to "utf8_columns()":
__PACKAGE__->utf8_columns( qw( lastname firstname ) );
TT Configuration
Tell TT to decode all template files, by adding the following to your application config in MyApp.pm
package MyApp;
use strict;
use parent 'Catalyst';
use Catalyst qw( ConfigLoader );
MyApp->config({
'View::TT' => {
ENCODING => 'UTF-8',
},
});
1;
HTML::FormFu Template Configuration
Make "HTML::FormFu" tell TT to decode all template files, by adding the following to your "myapp.yml" Catalyst configuration file:
package MyApp;
use strict;
use parent 'Catalyst';
use Catalyst qw( ConfigLoader );
MyApp->config({
'Controller::HTML::FormFu' => {
constructor => {
tt_args => {
ENCODING => 'UTF-8',
},
},
},
});
1;
These above 2 examples should be combined, like so:
package MyApp;
use strict;
use parent 'Catalyst';
use Catalyst qw( ConfigLoader );
MyApp->config({
'Controller::HTML::FormFu' => {
constructor => {
tt_args => {
ENCODING => 'UTF-8',
},
},
},
'View::TT' => {
ENCODING => 'UTF-8',
},
});
1;
AUTHORS
Carl Franks "cfranks@cpan.org" Michele Beltrame "arthas@cpan.org" (contributions)
COPYRIGHT
This document is free, you can redistribute it and/or modify it under the same terms as Perl itself.
perl v5.14.2 2011-05-10 HTML::FormFu::Manual::Unicode(3pm)