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