NAME

OpenInteract2::URL - Create URLs, parse URLs and generate action mappings

SYNOPSIS

 my ( $action_name, $task ) = OpenInteract2::URL->parse( '/foo/bar/?baz=42' );
 my $action = OpenInteract2::URL->parse_action( '/foo/bar/' );

DESCRIPTION

This class has methods to dealing with URLs. They are not complicated, but they ensure that OpenInteract applications can be deployed under any URL context without any changes to the code. They also ensure that URLs are mapped properly to the Action that should generate the relevant content.

All methods check the following configuration item:

 context_info.deployed_under

to see under what context the application is deployed. Many times this will be empty, which means the application sits at the root. This value may also set by the OpenInteract2::Context method assign_deploy_url().

METHODS

URL Parsing Methods

All methods are class methods.

parse_absolute_to_relative( $absolute_url )

Just strips the deployment context from the front of $absolute_url, returning the relative URL. If the deployment context does not lead $absolute_url, just returns $absolute_url.

Returns: relative URL.

Examples:

 CTX->assign_deploy_url( undef );
 my $relative_url = OpenInteract2::URL->parse_absolute_to_relative( '/games/explore/' );
 # $relative_url = '/games/explore/';
 
 CTX->assign_deploy_url( '/Public' );
 my $relative_url = OpenInteract2::URL->parse_absolute_to_relative( '/games/explore/' );
 # $relative_url = '/games/explore/';
 
 my $relative_url = OpenInteract2::URL->parse_absolute_to_relative( '/games/?foo=bar' );
 # $relative_url = '/games/?foo=bar'
 
 my $relative_url = OpenInteract2::URL->parse_absolute_to_relative( '/Public/games/explore/' );
 # $relative_url = '/games/explore/'
 
 my $relative_url = OpenInteract2::URL->parse_absolute_to_relative( '/Public/games/?foo=bar' );
 # $relative_url = '/games/?foo=bar'

parse( $url )

Parses $url into an action name and task and any additional parameters, disregarding the URL context. It does not attempt to verify whether the action name or the task is valid. This should only be used on relative URLs, or ones already stripped by the OpenInteract2::Request object.

Note that an action name, task and parameters are still returned if an application is deployed under a context and the URL does not start with that context. See parse_absolute() for a version that takes this into account.

Return: list with the action name and task and additional parameters pulled from $url; if the $url is empty or just a single '/' the list will be empty as well.

Examples:

 CTX->assign_deploy_url( undef );
 my ( $action_name, $task ) = OpenInteract2::URL->parse( '/games/explore/' );
 # $action_name = 'games', $task = 'explore'
 
 my ( $action_name, $task, @params ) = OpenInteract2::URL->parse( '/games/explore/1' );
 # $action_name = 'games', $task = 'explore', $params[0] = '1'
 
 CTX->assign_deploy_url( '/Public' );
 my ( $action_name, $task ) = OpenInteract2::URL->parse( '/games/explore/' );
 # $action_name = 'games', $task = 'explore';
 
 CTX->assign_deploy_url( '/Public' );
 my ( $action_name, $task ) = OpenInteract2::URL->parse( '/games/?foo=bar' );
 # $action_name = 'games', $task = undef;
 
 CTX->assign_deploy_url( '/Public' );
 my ( $action_name, $task, @params ) = OpenInteract2::URL->parse( '/games/display/42/?foo=bar' );
 # $action_name = 'games', $task = 'display', $params[0] = '42';
 
 my ( $action_name, $task ) = OpenInteract2::URL->parse( '/Public/games/explore/' );
 # $action_name = 'games', $task = 'explore'
 
 my ( $action_name, $task ) = OpenInteract2::URL->parse( '/Public/games/?foo=bar' );
 # $action_name = 'games', $task = undef
 
 my ( $action_name, $task, @params ) = OpenInteract2::URL->parse( '/Public/games/explore/55?foo=bar' );
 # $action_name = 'games', $task = 'explore', $params[0] = '55'

Alias: parse_relative( $url )

parse_absolute( $url )

Almost exactly the same as parse( $url ), except if the application is deployed under a context and $url does not begin with that context no values are returned.

Return: two-item list of the action name and task pulled from $url.

Examples:

 CTX->assign_deploy_url( undef );
 my ( $action_name, $task ) = OpenInteract2::URL->parse_absolute( '/games/explore/' );
 # $action_name = 'games', $task = 'explore'
 
 CTX->assign_deploy_url( '/Public' );
 my ( $action_name, $task ) = OpenInteract2::URL->parse_absolute( '/games/explore/' );
 # $action_name = undef, $task = undef;
 
 my ( $action_name, $task ) = OpenInteract2::URL->parse_absolute( '/games/?foo=bar' );
 # $action_name = undef, $task = undef;
 
 my ( $action_name, $task ) = OpenInteract2::URL->parse_absolute( '/Public/games/explore/' );
 # $action_name = 'games', $task = 'explore'
 
 my ( $action_name, $task, @params ) = OpenInteract2::URL->parse_absolute( '/Public/games/explore/42' );
 # $action_name = 'games', $task = 'explore', $params[0] = '42'
 
 my ( $action_name, $task ) = OpenInteract2::URL->parse_absolute( '/Public/games/?foo=bar' );
 # $action_name = 'games', $task = undef

URL Creation Methods

create_relative_to_absolute( $relative_url )

Just ensures $relative_url is located under the server context. If it already is then relative_url is returned, otherwise we prepend the current server context to it and return that.

Returns: URL with leading server context.

create( $base_url, [ \%params, $do_not_escape ] )

Create a URL using the deployed context (if any), a $base_url and \%params as a query string. This allows you to deploy your application under any URL context and have all the internal URLs continue to work properly.

One of the entries in \%params is special: URL_PARAMS. If specified we append its params (a simple scalar or arrayref ) to $base_url as extra path information. This information will not have a trailing '/'.

If no other \%params are specified then the resulting URL will not have a trailing '?' to indicate the start of a query string. This is important to note if you are doing further manipulation of the URL, such as you with if you were embedding it in generated Javascript. Note that the parameter names and values are URI-escaped.

Unless $do_not_escape is set to a true value we also escape the $base_url. (This makes URL-escaping the default.) So if you specify:

  $url->create( '/foo/bar is baz/' );

You'll get in return:

  /foo/bar%20is%20baz/

Finally: if $base_url begins with 'http:' we do not modify it in any way (including escaping it or adding a context) except to append the \%params, including URL_PARAMS.

Return: URL formed from the deployed context, $base_url and \%params.

Examples:

 CTX->assign_deploy_url( undef );

 $url = OpenInteract2::URL->create( '/foo');
 # $url = '/foo'
 
 $url = OpenInteract2::URL->create( '/foo', { bar => 'baz' } );
 # $url = '/foo?bar=baz'
 
 $url = OpenInteract2::URL->create(
            '/foo', { URL_PARAMS => '22', bar => 'baz' } );
 # $url = '/foo/22?bar=baz'
 
 $url = OpenInteract2::URL->create(
            '/foo', { URL_PARAMS => [ '22', 'baseball' ], bar => 'baz' } );
 # $url = '/foo/22/baseball?bar=baz'
 
 $url = OpenInteract2::URL->create(
            '/foo', { bar => 'baz', blah => 'blech' } );
 # $url = '/foo?bar=baz;blah=blech'
 
 $url = OpenInteract2::URL->create(
            '/foo', { name => 'Mario Lemieux' } );
 # $url = '/foo?name=Mario%20Lemiux'
 
 CTX->assign_deploy_url( '/Public' );
 $url = OpenInteract2::URL->create( '/foo', { bar => 'baz' } );
 # $url = '/Public/foo?bar=baz'
 
 $url = OpenInteract2::URL->create(
            '/foo', { URL_PARAMS => '99', bar => 'baz' } );
 # $url = '/Public/foo/99?bar=baz'
 
 $url = OpenInteract2::URL->create(
            '/foo', { bar => 'baz', blah => 'blech' } );
 # $url = '/Public/foo?bar=baz;blah=blech'
 
 $url = OpenInteract2::URL->create(
            '/foo', { name => 'Mario Lemieux' } );
 # $url = '/Public/foo?name=Mario%20Lemiux'
 
 $url = OpenInteract2::URL->create(
            'http://foo bar/foo', { URL_PARAMS => '66', name => 'Mario Lemieux' } );
 # $url = 'http://foo bar/foo/66?name=Mario%20Lemiux'
 
 CTX->assign_deploy_url( '/cgi-bin/oi.cgi' );
 $url = OpenInteract2::URL->create( '/foo', { bar => 'baz' } );
 # $url = '/cgi-bin/oi.cgi/Public/foo?bar=baz'
 
 $url = OpenInteract2::URL->create( '/foo', { bar => 'baz', blah => 'blech' } );
 # $url = '/cgi-bin/oi.cgi/Public/foo?bar=baz;blah=blech'
 
 $url = OpenInteract2::URL->create( '/foo', { name => 'Mario Lemieux' } );
 # $url = '/cgi-bin/oi.cgi/Public/foo?name=Mario%20Lemiux'

create_image( $base_url, [ \%params, $do_not_escape ] )

Create a URL using the deployed image context (if any), a $base_url and \%params as a query string. This allows you to keep your images under any URL context and have all the internal URLs continue to work properly.

We treat URL_PARAMS in \%params as create() does.

Unless $do_not_escape is set to a true value we URI-escape the $base_url. (We always URI-escape the query arguments and values created from \%params.)

Return: URL formed from the deployed context, $base_url and \%params.

Examples:

 CTX->assign_deploy_image_url( undef );
 $url = OpenInteract2::URL->create_image( '/images/foo.png' );
 # $url = '/images/foo.png'
 
 $url = OpenInteract2::URL->create_image( '/gallery/photo.php',
                                          { id => 154393 } );
 # $url = '/gallery/photo.php?id=154393'
 
 CTX->assign_deploy_image_url( '/IMG' );
 $url = OpenInteract2::URL->create_image( '/images/foo.png' );
 # $url = '/IMG/images/foo.png'
 
 $url = OpenInteract2::URL->create_image( '/gallery/photo.php',
                                          { id => 154393 } );
 # $url = '/IMG/gallery/photo.php?id=154393'

create_static( $base_url, \%params )

Create a URL using the deployed static context (if any), a $base_url and \%params as a query string. This allows you to keep your static files under any URL context and have all the internal URLs continue to work properly.

We treat URL_PARAMS in \%params as create() does.

Unless $do_not_escape is set to a true value we URI-escape the $base_url. (We always URI-escape the query arguments and values created from \%params.)

Return: URL formed from the deployed context, $base_url and \%params.

Examples:

 CTX->assign_static_deploy_url( undef );
 $url = OpenInteract2::URL->create_static( '/static/site.rdf' );
 # $url = '/static/site.rdf'
 
 $url = OpenInteract2::URL->create_static( '/reports/q1-2003-01.pdf' );
 # $url = '/reports/q1-2003-01.pdf'
 
 CTX->assign_static_deploy_url( '/STAT' );
 $url = OpenInteract2::URL->create_static( '/static/site.rdf' );
 # $url = '/STAT/static/site.rdf'
 
 $url = OpenInteract2::URL->create_static( '/reports/q1-2003-01.pdf' );
 # $url = '/STAT/reports/q1-2003-01.pdf'

create_from_action( $action, [ $task, \%params, $do_not_escape ] )

Similar to create(), except first we find the primary URL for $action from the OpenInteract2::Context object, add the optional $task to that and send it to create() as the 'base_url' parameter.

If $action is not found in the context we return undef. And if there is no primary URL for $action in the context we also return undef.

We treat URL_PARAMS in \%params as create() does.

Unless $do_not_escape is set to a true value we URI-escape the URL created from the action name and task. (We always URI-escape the query arguments and values created from \%params.)

See discussion in OpenInteract2::Action under MAPPING URL TO ACTION for what the 'primary URL' is and other issues.

Return: URL formed from the deployed context, URL formed by looking up the primary URL of $action and the $task, plus any additional \%params.

Examples, assuming that 'Foo' is the primary URL for action 'foo'.

 CTX->assign_deploy_url( undef );
 $url = OpenInteract2::URL->create_from_action(
                    'foo', 'edit', { bar => 'baz' } );
 # $url = '/Foo/edit/?bar=baz'
 
 $url = OpenInteract2::URL->create_from_action(
                    'foo', 'edit', { bar => 'baz', blah => 'blech' } );
 # $url = '/Foo/edit/?bar=baz;blah=blech'
 
 $url = OpenInteract2::URL->create_from_action(
                    'foo', undef, { name => 'Mario Lemieux' } );
 # $url = '/Foo/?name=Mario%20Lemiux'
 
 CTX->assign_deploy_url( '/Public' );
 $url = OpenInteract2::URL->create_from_action(
                    'foo', 'show', { bar => 'baz' } );
 # $url = '/Public/Foo/show/?bar=baz'
 
 $url = OpenInteract2::URL->create_from_action(
                    'foo', undef, { bar => 'baz', blah => 'blech' } );
 # $url = '/Public/Foo/?bar=baz;blah=blech'
 
 $url = OpenInteract2::URL->create_from_action(
                    'foo', 'show', { name => 'Mario Lemieux' } );
 # $url = '/Public/Foo/show/?name=Mario%20Lemiux'
 
 CTX->assign_deploy_url( '/cgi-bin/oi.cgi' );
 $url = OpenInteract2::URL->create_from_action(
                    'foo', 'list', { bar => 'baz' } );
 # $url = '/cgi-bin/oi.cgi/Public/Foo/list/?bar=baz'
 
 $url = OpenInteract2::URL->create_from_action(
                    'foo', undef, { bar => 'baz', blah => 'blech' } );
 # $url = '/cgi-bin/oi.cgi/Public/Foo/?bar=baz;blah=blech'
 
 $url = OpenInteract2::URL->create_from_action(
                    'foo', 'detail', { name => 'Mario Lemieux' } );
 # $url = '/cgi-bin/oi.cgi/Public/Foo/detail/?name=Mario%20Lemieux'

add_params_to_url( $url, \%params )

Adds the escaped key/value pairs in \%params as GET parameters to $url, which is assumed to be contextualized and escaped already.

We do NOT treat URL_PARAMS in \%params as create() does -- it's just another parameter.

So:

 my $url = '/foo/bar';
 my %params = ( id => '55', undercover => 'yes' );
 my $url_with_params = OpenInteract2::URL->add_params_to_url( $url, \%params );
 # $url_with_params = '/foo/bar?id=55&undercover=yes

The method can detect if you've already got query parameters in your url:

 my $url = '/foo/bar?keep=no';
 my %params = ( id => '55', undercover => 'yes' );
 my $url_with_params = OpenInteract2::URL->add_params_to_url( $url, \%params );
 # $url_with_params = '/foo/bar?keep=no&id=55&undercover=yes

strip_deployment_context( $url )

Removes any deployment context from $url and returns the modified string.

COPYRIGHT

AUTHORS

Chris Winters <chris@cwinters.com>

To install OpenInteract2::URL, copy and paste the appropriate command in to your terminal.

cpanm

cpanm OpenInteract2::URL

CPAN shell

perl -MCPAN -e shell
install OpenInteract2::URL

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

METHODS

URL Parsing Methods

URL Creation Methods

SEE ALSO

COPYRIGHT

AUTHORS

Module Install Instructions