HTML::...Unicode(3pm)

💖 HTML::...Unicode — the perl doc you didn't know you needed 💖

okay bestie, gather round, because we're talking about HTML::...Unicode (that's the Unicode.pod page, if we're being official) and honestly? it's giving "short doc, huge glow-up". no cap.

---

✨ VERSION ✨

this is version 2.07, periodt.

---

🌸 DESCRIPTION 🌸

so like. it's about working with unicode. that's the whole vibe.

for a real live practical example, go look at the Catalyst application hanging out in the examples/unicode directory in this distribution. it's there, it's cute, go visit it 🦋

---

🎀 ASSUMPTIONS 🎀

okay so, for this whole tutorial we're assuming all encodings are UTF-8. lowkey you can mix different encodings from different sources, it's not that deep, but that's fully beyond the scope of this tutorial. not our problem today 🙈

for simplicity we're also assuming:

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

that said — the principles we're covering should translate to whatever technologies you chose to work with. it's the vibes that transfer 💅

---

🌈 BASICS 🌈

short and sweet, main character energy only:

you must decode all data going into your program, and encode all data coming from your program.

that's it. that's the whole thing. tattoo it.

if you wanna skip the yapping and just see what you need to do, jump straight to "CHANGES REQUIRED". iykyk 🫶

---

👑 INPUT 👑

💜 Input parameters from the browser

if you're using Catalyst, then Catalyst::Plugin::Unicode will decode all input parameters sent from the browser to your application — peep "Catalyst Configuration".

if you're using some other framework, or honestly if you just need to decode the input parameters yourself, go take a look at HTML::FormFu::Filter::Encode. it's right there ✨

🦋 Data from the database

if you're using DBIx::Class, then DBIx::Class::UTF8Columns is likely the best options (yes, "options", we're keeping it, it's iconic) — because 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 the 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. automatic. slay.

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. no exceptions bestie, that's the rule.

---

🔥 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';

⚠️ but 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. do NOT mess this up, bestie, we're begging 😭

---

💀 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. iconic behaviour honestly.

---

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

---

and that's the whole page bestie 💖 this one shipped with perl v5.28.1 and was dated 2019-01-12 — so yes, it's vintage, but it ATE and left no crumbs 🌸✨ take care of your encodings, hydrate, and go decode something 🦋💅