view release on metacpan or  search on metacpan

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

This points to an array ref of fields that are not expected to be required by the template. 
It defaults to template, pageId and internalId, changefreq.

=item objects

This points to a hash ref. Each key is a parameter name (upto the dot). The value
is something that defines a smart object as described in L<HTML::Template::Plugin::Dot>.
The point about a smart object is that usually it defines an AUTOLOAD function so if the template
has <TMPL_VAR NAME="object.getcarter"> and the pagelookup_config has mapped object to some
object $MySmartObject then the method $MySmartObject->getcarter() will be called. Alternatively
there may be no AUTOLOAD function but the smart object may have methods that take additional arguments.
This way the template can be much more decoupled from the structure of the database.

There are three ways a smart object can be defined. Firstly if the value is a CODE ref,
then the ref is passed 1.) the reference to the CGI::Application object; 2.) the page id; 3.) the template,
4.) the parameter name 5.) any argument overrides. Otherwise if the CGI::Application has the value as a method, then the method is called with 
the same arguments as above. Finally the value is assumed to be the name of a module and the new constructor
of the supposed module is called with the same arguments. A typical smart object might be coded as follows:

	package MySmartObject;

	sub new {
		my $class = shift;
		my $self = .....
		......
		return bless $self, $class;
	}

	# If you do not have this, then HTML::Template::Plugin::Dot will not know that you can!
	# [Note really can is supposed to return a subroutine ref, but this works in this context.]
	sub can { return 1; }

	# This is the function that actually produces the value to be inserted into the template.
	sub AUTOLOAD {
		my $self = shift;
		my $method = $AUTOLOAD;
		if ($method =~ s/^MySmartObject\:\:(.+)$/) {
			$method = $1;	# Now we have what is in the template.
		}
		else {
			....
		}
		.....
		return $value;
	}

Note that the smart object does not have access to HASH ref because the data is changing at the point
it would be used and so is non-deterministic.

=item charset

This is a string defining the character encoding. This defaults to 'utf-8'.

=item template_params

This is a hashref containing additional parameters that are to be passed to the load_templ function.

=item default_lang

This is a two letter code and defaults to 'en'. It is used when creating a notfound page when a language
cannot otherwise be guessed.

=item status_404

This is the internal id corresponding to the not found page.

=item msg_param

This is the parameter used to store error messages.

=item xml_sitemap_base_url

This is the url for the whole site. It is mandatory to set this if you want XML sitemaps (which you should).

=back

=cut

sub pagelookup_config {
   my $self = shift;
   my %args = @_;

   croak "Calling pagelookup_config after the pagelookup has already been configured" if defined $self->{__cgi_application_plugin_pagelookup};

   $args{prefix} = "cgiapp_" unless exists $args{prefix};
   $args{handle_notfound} = 1 unless exists $args{handle_notfound};
   $args{expiry} = 1 unless exists $args{expiry};
   $args{remove} = ['template', 'pageId', 'internalId', 'changefreq'] unless exists $args{remove};
   $args{objects} = {} unless exists $args{objects};
   $args{template_params} = {} unless exists $args{template_params};
   $args{default_lang} = 'en' unless exists $args{default_lang};
   $args{status_404} = '404' unless exists $args{status_404};
   $args{msg_param} = 'pagelookup_message' unless exists $args{msg_param};
   $args{charset} = 'utf-8' unless exists $args{charset};

   $self->{__cgi_application_plugin_pagelookup} = \%args;

   $self->pagelookup_set_charset();
   return;
}

=head2 pagelookup_get_config 

Returns config including any overrides passed in as arguments.

=cut

sub pagelookup_get_config {
   my $self = shift;
   my %args = (%{$self->{__cgi_application_plugin_pagelookup}}, @_);
   return %args;
}

=head2 pagelookup_set_charset

This function sets the character set based upon the config.

=cut

sub pagelookup_set_charset {
   my $self = shift;

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

   croak "no template returned: $page_id" unless $template;
   return $template->output;
}

=head2 xml_sitemap_rm

This method is intended to be installed as a sitemap. Since the format is fixed, it is self-contained and does not load
templates from files. Note if a page as a null priority then it is not put in the sitemap.
For this function to work it is necessary to set the base BASE_URL parameter.

=cut

sub xml_sitemap_rm {
   my $self = shift;
   my $dbh = $self->dbh();
   my $base_url = $self->xml_sitemap_base_url();
   my $sql = $self->xml_sitemap_sql();
   my $sth = $dbh->prepare($sql) || croak $dbh->errstr;
   $sth->execute or  croak $dbh->errstr;
   my $hash_ref = $sth->fetchall_arrayref({});
   my $template =<<"EOS"
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<TMPL_LOOP NAME="urls">
   <url>
      <loc>$base_url<TMPL_VAR NAME="pageId"></loc>
      <lastmod><TMPL_VAR NAME="lastmod"></lastmod>
      <changefreq><TMPL_VAR NAME="changefreq"></changefreq>
      <priority><TMPL_VAR NAME="priority"></priority>
   </url>
</TMPL_LOOP>
</urlset>
EOS
;
   my $t = $self->load_tmpl(\$template);
   $t->param(urls=>$hash_ref);
   $self->header_add( -type => 'text/xml', -charset=>'utf-8' );
   return $t->output;
}

=head2 pagelookup_notfound

This function takes a page id which has failed a page lookup and tries to find the best fitting
404 page. First of all it attempts to find the correct by language by assuming that if the first three 
characters of the page id consists of two characters followed by a '/'. If this matches then the first
two characters are taken to be the language. If that fails then the language is taken to be $self->pagelookup_default_lang.
Then the relevant 404 page is looked up by language and internal id. The internalId is taken to be $self->pagelookup_404 . 
Of course it is assumed that this page lookup cannot fail. The header  404 status is added
to the header and the original page id is inserted into the $self->pagelookup_msg_param parameter.
If this logic does not match your URL structure you can omit exporting this function or turn notfound handling off
and implement your own logic.

=cut

sub pagelookup_notfound {
   my $self = shift;
   my $page_id = shift;
   my @inargs = @_;
   my %args = $self->pagelookup_get_config(@inargs);

   # Best guess at language
   my $lang = $self->pagelookup_default_lang(@inargs);
   if ($page_id =~ /^(\w\w)\//) {
	$lang = $1;
   }

   my $template = $self->pagelookup({lang=>$lang, internalId => $self->pagelookup_404}, handle_notfound=>0) || croak "failed to construct 'not found' page";
   $template->param( $self->pagelookup_msg_param(@inargs) => $page_id);
   $self->header_add( -status => 404 );
   return $template;

}

=head2 pagelookup_set_expiry

This function sets the expiry header based upon the hash_ref.

=cut

sub pagelookup_set_expiry {
   my $self = shift;
   my $hash_ref = shift;
   my $changefreq = $hash_ref->{changefreq} or return;
   my %mapping = (always=>'-1d', hourly=>'+1h', daily=>'+1d', weekly=>'+7d', monthly=>'+1M', yearly=>'+1y', never=>'+3y');
   $self->header_add(-expires=>$mapping{$changefreq});
   return;
}

=head2 pagelookup_default_lang 

This returns the default language code.

=cut

sub pagelookup_default_lang {
   my $self = shift;
   my %args = $self->pagelookup_get_config(@_);
   return $args{default_lang};
}

=head2 pagelookup_404

This returns the core id used by 404 pages.

=cut

sub pagelookup_404 {
   my $self = shift;
   my %args = $self->pagelookup_get_config(@_);
   return $args{status_404};
}

=head2 pagelookup_msg_param

This returns the parameter that pagelookup uses for inserting error messages.

=cut

sub pagelookup_msg_param {
   my $self = shift;
   my %args = $self->pagelookup_get_config(@_);