1HTML::FormFu::Manual::UUnsiecrodCeo(n3t)ributed Perl DocHuTmMeLn:t:aFtoiromnFu::Manual::Unicode(3)
2
3
4

NAME

6       Unicode.pod - Working with unicode
7

VERSION

9       version 2.07
10

DESCRIPTION

12       Working with unicode.
13
14       For a practical example, see the Catalyst application in the
15       "examples/unicode" directory in this distribution.
16

ASSUMPTIONS

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
22       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

BASICS

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
32       Skip to "CHANGES REQUIRED" if you want to see what you need to do
33       without any other explanation.
34

INPUT

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
41       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
45   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
50       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
55   Your template files
56       Set TT to decode all template files - see "TT Configuration".
57
58   HTML::FormFu's own template files
59       Set "HTML::FormFu" to decode all template files - see "HTML::FormFu
60       Template Configuration".
61
62   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
67       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
72   Your perl source code
73       Any perl source files which contain Unicode characters must use the
74       utf8 module.
75

OUTPUT

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
81   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
85       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
89           use utf8;
90           if ( $output && utf8::is_utf8($output) ){
91               utf8::encode( $output ); # Encodes in-place
92           }
93
94       Another option is to set the "binmode" for "STDOUT":
95
96           bindmode STDOUT, ':utf8';
97
98       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

CHANGES REQUIRED

102   Catalyst Configuration
103       Add Catalyst::Plugin::Unicode to the list of Catalyst plugins:
104
105           use Catalyst qw( ConfigLoader Static::Simple Unicode );
106
107   DBIx::Class Configuration
108       Add DBIx::Class::UTF8Columns to the list of components loaded, for each
109       table that has columns storing unicode:
110
111           __PACKAGE__->load_components( qw( UTF8Columns HTML::FormFu PK::Auto Core ) );
112
113       Pass each column name that will store unicode to utf8_columns():
114
115           __PACKAGE__->utf8_columns( qw( lastname firstname ) );
116
117   TT Configuration
118       Tell TT to decode all template files, by adding the following to your
119       application config in MyApp.pm
120
121           package MyApp;
122               use parent 'Catalyst';
123           use Catalyst qw( ConfigLoader );
124
125           MyApp->config({
126               'View::TT' => {
127                   ENCODING => 'UTF-8',
128               },
129           });
130
131           1;
132
133   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
137           package MyApp;
138               use parent 'Catalyst';
139           use Catalyst qw( ConfigLoader );
140
141           MyApp->config({
142               'Controller::HTML::FormFu' => {
143                   constructor => {
144                       tt_args => {
145                           ENCODING => 'UTF-8',
146                       },
147                   },
148               },
149           });
150
151           1;
152
153       These above 2 examples should be combined, like so:
154
155           package MyApp;
156               use parent 'Catalyst';
157           use Catalyst qw( ConfigLoader );
158
159           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
172           1;
173

AUTHORS

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

AUTHOR

183       Carl Franks <cpan@fireartist.com>
184
186       This software is copyright (c) 2018 by Carl Franks.
187
188       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.
190
191
192
193perl v5.38.0                      2023-07-20  HTML::FormFu::Manual::Unicode(3)
Impressum