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.

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, 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 and task 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: two-item list of the action name and task pulled from $url. Note that the second item may be undefined.

Examples:

CTX->assign_deploy_url( undef );
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/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;

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

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 ) = 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 )

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.

If no \%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're doing further manipulation of the URL, such as you with if you were embedding it in generated Javascript.

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', { 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', { 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'

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 )

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.

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

Examples:

CTX->server_config->{context_info}{deployed_under_image} = 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->server_config->{context_info}{deployed_under_image} = '/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.

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

Examples:

CTX->server_config->{context_info}{deployed_under_static} = 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->server_config->{context_info}{deployed_under_static} = '/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 )

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.

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%20Lemiux'

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