view release on metacpan or  search on metacpan

lib/CGI/Application/Plugin/Header.pm  view on Meta::CPAN

=head1 NAME

CGI::Application::Plugin::Header - Plugin for handling header props.

=head1 SYNOPSIS

  package MyApp;
  use parent 'CGI::Application';
  use CGI::Application::Plugin::Header;

  sub do_something {
      my $self = shift;

      my $header = $self->header; # => CGI::Header object

      # get header props.
      my $type = $header->type; # => "text/plain"

      # set header props.
      $header->type("text/html");

      # compatible with the core methods of CGI::Application
      $self->header_props( type => "text/plain" );
      $self->header_add( type => "text/plain" );

      ...
  }

=head1 DESCRIPTION

This plugin provides you the common syntax to handle CGI.pm-compatible
HTTP header properties.

By using this plugin, your application is capable of the following methods,
where C<$cgiapp> denotes the instance
of your application which inherits from L<CGI::Application>:

=head2 ATTRIBUTES

=over 4

=item $header = $cgiapp->header


Returns a L<CGI::Header> object associated with C<$cgiapp>.
You can use all methods of C<$header>.

  sub cgiapp_postrun {
      my ( $self, $body_ref ) = @_;
      $self->header->set( 'Content-Length' => length $$body_ref );
  }

=item $header = $cgiapp->header( CGI::Header->new(...) )

You can also define your C<header> class which inherits from C<CGI::Header>.
For example,

  package MyApp::Header;
  use parent 'CGI::Header';
  use CGI::Cookie;

  sub cookies {
      my $self    = shift;
      my $cookies = $self->header->{cookies} ||= [];

      return $cookies unless @_;

      if ( ref $_[0] eq 'HASH' ) {
          push @$cookies, map { CGI::Cookie->new($_) } @_;
      }
      else {
          push @$cookies, CGI::Cookie->new( @_ );
      }

      $self;
  }

You can set C<header> as follows:

  # using new()

  my $query  = CGI->new;
  my $header = MyApp::Header->new( query => $query );
  my $app    = MyApp->new( query => $query, header => $header );


  # using header()

  my $app = MyApp->new;

  $app->header( MyApp::Header->new( query => $app->query ) );

=back

=head2 METHODS

This plugin overrides the following methods of L<CGI::Application>:

=over 4

=item %header_props = $cgiapp->header_props

=item %header_props = $cgiapp->header_props( $k1 => $v1, $k2 => $v2, ... )

=item %header_props = $cgiapp->header_props({ $k1 => $v1, $k2 => $v2, ... })

=item %header_props = $cgiapp->header_props({})

Behaves like L<CGI::Application>'s C<header_props> method,
but the return format is modified. C<keys> of C<%header_props>
are lowercased and start with a dash. The following aliases are used:

  '-content-type' -> '-type'
  '-cookie'       -> '-cookies'

It's guaranteed that the keys are unique.

=item $cgiapp->header_add( $k1 => $v1, $k2 => $v2, ... )

=item $cgiapp->header_add({ $k1 => $v1, $k2 => $v2, ... })

Behaves like L<CGI::Application>'s C<header_add> method.

=back

=head2 COMPATIBILITY

Header property names are normalized by C<$header> automatically,
and so this plugin breaks your code which depends on the return value of
C<header_props>:

  my %header_props = $cgiapp->header_props; # => ( -cookies => 'ID=123456' )