Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
HTML::FormFu::Manual::UseroContributed Perl DoHTML::FormFu::Manual::Unicode(3)

NAME
       Unicode.pod - Working with unicode

VERSION
       version 2.07

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

AUTHOR
       Carl Franks <cpan@fireartist.com>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2018 by Carl Franks.

       This is free software; you can redistribute it and/or modify it under
       the same	terms as the Perl 5 programming	language system	itself.

perl v5.32.0			  2018-12-14  HTML::FormFu::Manual::Unicode(3)

NAME | VERSION | DESCRIPTION | ASSUMPTIONS | BASICS | INPUT | OUTPUT | CHANGES REQUIRED | AUTHORS | COPYRIGHT | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=HTML::FormFu::Manual::Unicode&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help