view release on metacpan or  search on metacpan

lib/Catalyst/Plugin/I18N/Request.pm  view on Meta::CPAN

            
        Dispatched as:
            GET /search?searchTerms=Pirates HTTP/1.0
            Accept-Language: fr
            
        $c->uri_for('/search'):
            http://localhost/recherche
        
    German:
        
        Requested as:
            GET /suche?searchTerms=Pirates HTTP/1.0
            Accept-Language: de
            
        Dispatched as:
            GET /search?searchTerms=Pirates HTTP/1.0
            Accept-Language: de    
            
        $c->uri_for('/search'):
            http://localhost/suche

=head1 DESCRIPTION

This plugin is designed to work alongside Catalyst::Plugin::I18N in 
order to provide localization / delocalization of request paths and 
request parameter names.

=head1 DELOCALIZATION

Delocalization occurs when a request is first received, before any 
dispatching takes place. Delocalization assumes that there may exist 
paths or parameter names within the request which do not correlate to 
actual names used within the application itself. When functioning 
properly, this plugin will allow users to activate an action called 
'search' using:
    
    'recherche' (French requests)
    'suche'     (German requests)
     etc... 

This relies on the localize method provided to the application by 
Catalyst::Plugin::I18N. For the above examples to work, the following 
localizations must occur:
    
    Key                       | Localized text  | Language
    ==========================================================
    PATH_delocalize_recherche | search          | French
    PATH_delocalize_suche     | search          | German

That is, $c->localize('PATH_delocalize_recherche') must return 'search'.
A very similar behaviour applies to parameter names within the query 
string. The keys for these delocalizations begin with 
'PARAMETER_delocalize_' instead of 'PATH_delocalize_'.

=head1 LOCALIZATION

Localization involves taking paths and parameter names and replacing 
them with values which make more sense to users speaking the requested 
language. In the above example, 'search' may not look intuitive to 
German users. Out of the box, this plugin allows you to localize these 
values transparently via the standard $c->uri_for and 
$c->request->uri_with methods which are already standard features of 
the Catalyst framework. 

Like delocalization, this functionality depends upon the $c->localize 
method. However, PATH_delocalize_ is replaced with PATH_localize and 
PARAMETER_delocalize_ is replaced with PARAMETER_localize_. 
    
    Key                  | Localized text  | Language
    ==========================================================
    PATH_localize_search | recherche       | French
    PATH_localize_search | suche           | German

=head1 METHODS

=head2 setup ( )

Allows Catalyst::Request to localize the results of calls to uri_with. 

=cut

sub setup {
    my $self = shift;
    $self->next::method( @_ );
    
    no strict 'refs';
    no warnings 'redefine';
    
    my $uri_with = \&Catalyst::Request::uri_with;
    
    *Catalyst::Request::uri_with = sub {
        my ($request) = @_;
        my $uri = $uri_with->( @_ );
        
        return $request->{_context}->localize_uri( $uri );
    };
}

=head2 prepare ( )

Overrides Catalyst's C<prepare> method to push the context object to the request
object.

=cut

sub prepare {
    my $c = shift;
    $c = $c->next::method( @_ );

    unless( $c->request->{ _context } ) {
        Scalar::Util::weaken( $c->request->{ _context } = $c );
    }

    return $c;
}

=head2 uri_for ( $path [, @args ] [, \%query_values ] )

Calls the native uri_for, but proceeds to localize the resulting path 
and query values.