=encoding utf8

=head1 NAME

HTML::FromMail::Field - output a header field as HTML

=head1 INHERITANCE

 HTML::FromMail::Field
   is a HTML::FromMail::Page
   is a HTML::FromMail::Object
   is a Mail::Reporter

=head1 SYNOPSIS

=head1 DESCRIPTION

Extends L<"DESCRIPTION" in HTML::FromMail::Page|HTML::FromMail::Page/"DESCRIPTION">.

=head1 METHODS

Extends L<"METHODS" in HTML::FromMail::Page|HTML::FromMail::Page/"METHODS">.

=head2 Constructors

Extends L<"Constructors" in HTML::FromMail::Page|HTML::FromMail::Page/"Constructors">.

=over 4

=item $class-E<gt>B<new>(%options)

Z<>

 -Option  --Defined in            --Default
  settings  HTML::FromMail::Object  {}
  topic     HTML::FromMail::Object  'field'

=over 2

=item settings => \%map

=item topic => STRING

=back

=back

=head2 Attributes

Extends L<"Attributes" in HTML::FromMail::Page|HTML::FromMail::Page/"Attributes">.

=over 4

=item $obj-E<gt>B<settings>( [TOPIC] )

Inherited, see L<HTML::FromMail::Object/"Attributes">

=item $obj-E<gt>B<topic>()

Inherited, see L<HTML::FromMail::Object/"Attributes">

=back

=head2 Other methods

Extends L<"Other methods" in HTML::FromMail::Page|HTML::FromMail::Page/"Other methods">.

=over 4

=item $obj-E<gt>B<addressField>($field, $how, \%options)

Produce text for a header C<$field> containing addresses.  On C<$how> this
is done is defining the result.  Possible values are C<'ADDRESS'>,
C<'PHRASE'>, C<'PLAIN'>, C<'MAILTO'>, or C<'LINK'>.  See L</address HOW>
for details.

=item $obj-E<gt>B<fromHead>($head, $name, \%options)

Returns the fields from the header with C<$name>.  Some fields appear
more than once, some may not be present.

=item $obj-E<gt>B<htmlAddresses>($field, \%options)

Returns an array with address info.

=item $obj-E<gt>B<htmlBody>(\%options)

Produce the body of the field: everything after the first colon on the
header line.

 -Option --Default
  address  'MAILTO'
  content  <depends>
  wrap     78

=over 2

=item address => 'ADDRESS'|'PHRASE'|'PLAIN'|'MAILTO'|'LINK'

See L</address HOW>

=item content => 'FOLDED'|'REFOLD'|'UNFOLDED'|'DECODED'

How to included the body of the field.  If a C<wrap> is defined, then
REFOLD is taken as default, otherwise DECODED is the default. See
L</content HOW>

=item wrap => INTEGER

In combination with C<content REFOLD>, it specifies the maximum number
of characters requested per line.  See L</wrap INTEGER>.

=back

=item $obj-E<gt>B<htmlName>(\%options)

Returns the name of the header field.

 -Option  --Default
  capitals  'UNCHANGED'

=over 2

=item capitals => 'UNCHANGED'|'WELLFORMED'

Overrules the default from L<new(settings)|HTML::FromMail::Object/"Constructors"> C<names>.
See L</names HOW>.

=back

=item $obj-E<gt>B<lookup>($label, \%options)

Inherited, see L<HTML::FromMail::Page/"Other methods">

=item $obj-E<gt>B<plain2html>(STRING)

Inherited, see L<HTML::FromMail::Object/"Other methods">

=back

=head1 DETAILS

=head2 Settings

You can specify the following settings in L<HTML::FromMail::new(settings)|HTML::FromMail/"Constructors">
for topic C<field>:

=head3 address HOW

Some fields are pre-defined to contain e-mail addresses.  In many web-based
clients, you see that these addresses are bluntly linked to, but you here
have a choice.  As example, the header field contains the address
  "My Name" E<lt>me@example.comE<gt>
  you@example.com

The possible settings for this parameter are

=over 4

=item * C<'PLAIN'>

Show the address as was specified in the message header, without smart
processing.
  "My Name" E<lt>me@example.com E<gt>
  you@example.com

=item * C<'PHRASE'>

According to the standards, the phrase is ment to represent the user
in an understandable way.  Usually this is the full name of the user.
No link is made.
  My Name
  you@example.com

=item * C<'ADDRESS'>

Only show the address of the users.
  my@example.com
  you@example.com

=item * C<'MAILTO'>

Create a link behind the phrase.  In case there is no phrase, the
address itself is displayed.  This is the most convenient link, if
you decide to create a link.
  <a href="mailto:me@example.com">My Name </a>
  <a href="mailto:you@example.com">you@example.com </a>

=item * C<'LINK'>

Often seen, but more for simplicity of implementation is the link
under the address.  The C<'MAILTO'> is probably easier to understand.
  "My Name" <a href="mailto:me@example.com">me@example.com</a>
  <a href="mailto:you@example.com">you@example.com</a>

=back

=head3 content HOW

Defined HOW field bodies are handled, by default UNFOLDED.
Valid values are

=over 4

=item * C<'FOLDED'>

Included the content FOLDED as found in the source message.  This is the
fastest choice, and usually in a preformatted html block, otherwise the
folding will be lost again.

=item * C<'REFOLD'>

Do not accept the folding as found in the message headers, but force it
into the wrap which is defined by C<wrap>.

=item * C<'UNFOLDED'>

All line folding is removed from the field.  This useful when the field body
is displayed in a proportional font.

=item * C<'DECODED'>

Fields may be character-set encoded.  Decoding these fields is nicest,
but consumes considerable time.

=back

=head3 names HOW

Defines HOW field names are displayed: either C<'WELLFORMED'> or
C<'UNCHANGED'>.  Field names have a certain capitization (as
defined by the message), but this may be different from the preferred use
of capitals.  The correct use of capitals is implemented by
Mail::Message::Field subroutine wellformedName and will be used when WELLFORMED
is selected.  By default, the names are displayed UNCHANGED.

=head4 » Example: using HTML::FromMail::Format::Magic

  <!--{name capitals => WELLFORMED}-->

=head3 wrap INTEGER

Used in combination with C<content REFOLD>, to specify how many characters
are requested per line.

=head1 DIAGNOSTICS

=over 4

=item Error: don't know address field formatting '$how'.

Cast by C<addressField()>

=back

=head1 SEE ALSO

This module is part of HTML-FromMail version 4.00,
built on December 11, 2025. Website: F<http://perl.overmeer.net/CPAN/>

=head1 LICENSE

For contributors see file ChangeLog.

This software is copyright (c) 2003-2025 by Mark Overmeer.

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

