1HTML::FormFu::Manual::UUnsiecrodCeo(n3t)ributed Perl DocHuTmMeLn:t:aFtoiromnFu::Manual::Unicode(3)
2
6 Unicode.pod - Working with unicode
7
9 version 2.07
10
12 Working with unicode.
13 For a practical example, see the Catalyst application in the
15 "examples/unicode" directory in this distribution.
16
18 In this tutorial, we're assuming that all encodings are UTF-8. It's
19 relatively simple to combine different encodings from different
20 sources, but that's beyond the scope of this tutorial.
21 For simplicity, we're also going to assume that you're using Catalyst
23 for your web-framework, DBIx::Class for your database ORM, TT for your
24 templating system, and YAML format "HTML::FormFu" configuration files,
25 with YAML::XS installed. However, the principles we'll cover should
26 translate to whatever technologies you chose to work with.
27
29 To make it short and sweet: you must decode all data going into your
30 program, and encode all data coming from your program.
31 Skip to "CHANGES REQUIRED" if you want to see what you need to do
33 without any other explanation.
34
36 Input parameters from the browser
37 If you're using "Catalyst", Catalyst::Plugin::Unicode will decode all
38 input parameters sent from the browser to your application - see
39 "Catalyst Configuration".
40 If you're using some other framework or, in any case, you need to
42 decode the input parameters yourself, please take a look at
43 HTML::FormFu::Filter::Encode.
44 Data from the database
46 If you're using DBIx::Class, DBIx::Class::UTF8Columns is likely the
47 best options, as it will decode all input retrieved from the database -
48 see "DBIx::Class Configuration".
49 In other cases (i.e. plain DBI), you still need to decode the string
51 data coming from the database. This varies depending on the database
52 server. For MySQL, for instance, you can use the "mysql_enable_utf8"
53 attribute: see DBD::mysql documentation for details.
54 Your template files
56 Set TT to decode all template files - see "TT Configuration".
57 HTML::FormFu's own template files
59 Set "HTML::FormFu" to decode all template files - see "HTML::FormFu
60 Template Configuration".
61 HTML::FormFu form configuration files
63 If you're using "YAML" config files, your files will automatically be
64 decoded by "load_config_file|HTML::FormFu/load_config_file" and
65 "load_config_filestem|HTML::FormFu/load_config_filestem".
66 If you have Config::General config files, your files will automatically
68 be decoded by "load_config_file|HTML::FormFu/load_config_file" and
69 "load_config_filestem|HTML::FormFu/load_config_filestem", which
70 automatically sets Config::General's "-UTF8" setting.
71 Your perl source code
73 Any perl source files which contain Unicode characters must use the
74 utf8 module.
75
77 Data saved to the database
78 With "DBIx::Class", DBIx::Class::UTF8Columns will encode all data sent
79 to the database - see "DBIx::Class Configuration".
80 HTML sent to the browser
82 With "Catalyst", Catalyst::Plugin::Unicode will encode all output sent
83 from your application to the browser - see "Catalyst Configuration".
84 In other circumstances you need to be sure to output your Unicode
86 (decoded) strings in UTF-8. To do this you can encode your output
87 before it's sent to the browser with something like:
88 use utf8;
90 if ( $output && utf8::is_utf8($output) ){
91 utf8::encode( $output ); # Encodes in-place
92 }
93 Another option is to set the "binmode" for "STDOUT":
95 bindmode STDOUT, ':utf8';
97 However, be sure to do this only when sending UTF-8 data: if you're
99 serving images, PFD files, etc, "binmode" should remain set to ":raw".
100
102 Catalyst Configuration
103 Add Catalyst::Plugin::Unicode to the list of Catalyst plugins:
104 use Catalyst qw( ConfigLoader Static::Simple Unicode );
106 DBIx::Class Configuration
108 Add DBIx::Class::UTF8Columns to the list of components loaded, for each
109 table that has columns storing unicode:
110 __PACKAGE__->load_components( qw( UTF8Columns HTML::FormFu PK::Auto Core ) );
112 Pass each column name that will store unicode to "utf8_columns()":
114 __PACKAGE__->utf8_columns( qw( lastname firstname ) );
116 TT Configuration
118 Tell TT to decode all template files, by adding the following to your
119 application config in MyApp.pm
120 package MyApp;
122 use parent 'Catalyst';
123 use Catalyst qw( ConfigLoader );
124 MyApp->config({
126 'View::TT' => {
127 ENCODING => 'UTF-8',
128 },
129 });
130 1;
132 HTML::FormFu Template Configuration
134 Make "HTML::FormFu" tell TT to decode all template files, by adding the
135 following to your "myapp.yml" Catalyst configuration file:
136 package MyApp;
138 use parent 'Catalyst';
139 use Catalyst qw( ConfigLoader );
140 MyApp->config({
142 'Controller::HTML::FormFu' => {
143 constructor => {
144 tt_args => {
145 ENCODING => 'UTF-8',
146 },
147 },
148 },
149 });
150 1;
152 These above 2 examples should be combined, like so:
154 package MyApp;
156 use parent 'Catalyst';
157 use Catalyst qw( ConfigLoader );
158 MyApp->config({
160 'Controller::HTML::FormFu' => {
161 constructor => {
162 tt_args => {
163 ENCODING => 'UTF-8',
164 },
165 },
166 },
167 'View::TT' => {
168 ENCODING => 'UTF-8',
169 },
170 });
171 1;
173
175 Carl Franks "cfranks@cpan.org" Michele Beltrame "arthas@cpan.org"
176 (contributions)
177
179 This document is free, you can redistribute it and/or modify it under
180 the same terms as Perl itself.
181
183 Carl Franks <cpan@fireartist.com>
184
186 This software is copyright (c) 2018 by Carl Franks.
187 This is free software; you can redistribute it and/or modify it under
189 the same terms as the Perl 5 programming language system itself.
190perl v5.32.1 2021-01-27 HTML::FormFu::Manual::Unicode(3)