NAME

OpenInteract2::Action - Represent and dispatch actions

SYNOPSIS

 # Define an action in configuration to have its content generated by
 # the TT generator (Template Toolkit) and security
 # checked. (Previously you had to subclass SPOPS::Secure.)
 
 [news]
 class             = OpenInteract2::Handler::News
 is_secure         = yes
 content_generator = TT
 
 # The tasks 'listing' and 'latest' can be cached, for 600 and 300
 # seconds respectively.
 
 [news cache_expire]
 listing           = 600
 latest            = 300
 
 # Cached content depends on these parameters (multiple ok)
 
 [news cache_param]
 listing           = num_items
 listing           = language
 latest            = num_items
 
 # You can declare security levels in the action configuration, or you
 # can override the method find_security_level()
 
 [news security]
 default           = write
 show              = read
 listing           = read
 latest            = read
 
 # Same handler class, but mapped to a different action and with an
 # extra parameter, and the 'edit' and 'remove' tasks are marked as
 # invalid.
 
 [newsuk]
 class             = OpenInteract2::Handler::News
 is_secure         = no
 news_from         = uk
 content_generator = TT
 task_invalid      = edit
 task_invalid      = remove
 
 [newsuk cache_expire]
 listing           = 600
 latest            = 600
 
 # Future: Use the same code to generate a SOAP response; at server
 # startup this should setup SOAP::Lite to respond to a request at
 # the URL '/SoapNews'.
 
 [news_rpc]
 class             = OpenInteract2::Handler::News
 is_secure         = yes
 content_generator = SOAP
 url               = SoapNews
 
 [news_rpc cache_expire]
 listing           = 600
 latest            = 300
 
 [news_rpc security]
 default           = write
 show              = read
 
 # Dispatch a request to the action by looking up the action in the
 # OpenInteract2::Context object:
 
 # ...using the default task
 my $action = CTX->lookup_action( 'news' );
 return $action->execute;
 
 # ...specifying a task
 my $action = CTX->lookup_action( 'news' );
 $action->task( 'show' );
 return $action->execute;
 
 # ...specifying a task and passing parameters
 my $action = CTX->lookup_action( 'news' );
 $action->task( 'show' );
 $action->param( news => $news );
 $action->param( grafs => 3 );
 return $action->execute;
 
 # Dispatch a request to the action by manually creating an action
 # object
 
 # ...using the default task
 my $action = OpenInteract2::Action->new( 'news' );
 
 # ...specifying a task
 my $action = OpenInteract2::Action->new( 'news', { task => 'show' } );
 
 # ...specifying a task and passing parameters
 my $action = OpenInteract2::Action->new( 'news',
                                         { task  => 'show',
                                           news  => $news,
                                           grafs => 3 } );
 
 # Set parameters after the action has been created
 $action->param( news  => $news );
 $action->param( grafs => 3 );
 
 # Run the action and return the content
 return $action->execute;

DESCRIPTION

The Action object is a core piece of the OpenInteract framework. Every component in the system and part of an application is represented by an action. An action always returns content from its primary interface, the execute() method. This content can be built by the action directly, constructed by passing parameters to a content generator, or passed off to another action for generation. (See "GENERATING CONTENT FOR ACTION" below.)

Action Tasks

Each action can be viewed as an associated collection of tasks. Generally, each task maps to a subroutine in the package of the action. For instance, the following package defines three tasks that all operate on 'news' objects:

 package My::News;
 
 use strict;
 use base qw( OpenInteract2::Action );
 
 sub list { return "Lots of news in the last week" }
 sub show { return "This is the show task!" }
 sub edit { return "Editing..." }
 
 1;

Here is how you would call them, assuming that this action is mapped to the 'news' key:

 my $action = CTX->lookup_action( 'news' );
 $action->task( 'list' );
 print $action->execute;
 # Lots of news in the last week
 
 $action->task( 'show' );
 print $action->execute;
 # This is the show task!
 
 $action->task( 'edit' );
 print $action->execute;
 # Editing...

You can also create your own dispatcher by defining the method 'handler' in your action class. For instance:

 package My::News;
 
 use strict;
 use base qw( OpenInteract2::Action );
 
 sub handler {
     my ( $self ) = @_;
     my $task = $self->task;
     my $language = CTX->user->language;
     if ( $task eq 'list' and $language eq 'es' ) {
         return $self->list_spanish;
     }
     elsif ( $task eq 'list' and $language eq 'ru' ) {
         return $self->list_russian;
     }
     else {
         return $self->list_english;
     }
     return $self->$task();
 }
 
 sub list_spanish { return "Lots of spanish news in the last week" }
 sub list_russian { return "Lots of russian news in the last week" }
 sub list_english { return "Lots of english news in the last week" }
 sub show { return "This is the show task!" }
 sub edit { return "Editing..." }
 
 1;

You have control over whether a subroutine in your action class is exposed as a task. The following tasks will never be run:

Tasks beginning with an underscore.
Tasks listed in the task_invalid property.

Additionally, if you have defined the task_valid property then only those tasks will be valid. All others will be forbidden.

To use our example above, assume we have configured the action with the following:

 [news]
 class        = OpenInteract2::Handler::News
 task_valid   = list
 task_valid   = show

Then the 'edit' task will not be valid. You could also explicitly forbid the 'edit' task from being executed with:

 [news]
 class        = OpenInteract2::Handler::News
 task_invalid = edit

See discussion of find_task() and check_task_validity() for more information.

Action Types

An action type implements one or more public methods in a sufficiently generic fashion as to be applicable to different applications. Actions implemented using action types normally do not need any code: the action type relies on configuration information and/or parameters to perform its functions.

To use an action type, you just need to specify it in your configuration:

 [foo]
 action_type       = foo_type
 is_secure         = yes

Action Properties vs. Parameters

Action Properties are found in every action. These represent standard information about the action: name, task, security information, etc. All properties are described in PROPERTIES.

Action Parameters are extra information attached to the action. These are analogous in OpenInteract 1.x to the hashref passed into a handler as the second argument. For instance:

 # OpenInteract 1.x
 
 return $class->show({ object     => $foo,
                       error_msg  => $error_msg,
                       status_msg => $status_msg });
 
 sub show {
     my ( $class, $params ) = @_;
     if ( $params->{error_msg} ) {
         return $R->template->handler( {}, $params,
                                       { name => 'mypkg::error_page' } );
     }
 }

 # OpenInteract 2.x
 
 $action->task( 'show' );
 $action->param( object => $foo );
 $action->param_add( error_msg => $error_msg );
 $action->param_add( status_msg => $status_msg );
 return $action->execute;
 
 # also: assign parameters in one call
 
 $action->task( 'show' );
 $action->param_assign({ object     => $foo,
                         error_msg  => $error_msg,
                         status_msg => $status_msg });
 return $action->execute;
 
 # also: pass parameters in last statement
 
 $action->task( 'show' );
 return $action->execute({ object     => $foo,
                           error_msg  => $error_msg,
                           status_msg => $status_msg });
 
 sub show {
     my ( $self ) = @_;
     if ( $self->param( 'error_msg' ) ) {
         return $self->generate_content(
                              {}, { name => 'mypkg::error_page' } );
     }
 }

Observable Actions

All actions are observable. This means that any number of classes, objects or subroutines can register themselves with a type of action and be activated when that action publishes a notification. This is all very abstract, so here is a scenario:

Existing action: Register a new user

Notification published: When new user confirms registration.

Desired outcome: Add the publish the user name and email address to various services within the website network. This is done via an asynchronous message published to each site in the network. The network names are stored in a server configuration variable 'network_queue_server'.

How to implement:

 package OpenInteract2::NewUserPublish;
 
 use strict;
 
 sub update {
     my ( $class, $action, $notify_type ) = @_;
     if ( $notify_type eq 'register-confirm' ) {
         my $user = $action->param( 'user' );
         my $network_servers = CTX->server_config->{network_queue_server};
         foreach my $server_name ( @{ $network_servers } ) {
             my $server = CTX->queue_connect( $server_name );
             $server->publish( 'new_user', $user );
         }
     }
 }
 
 OpenInteract2::Handler::NewUser->add_observer( __PACKAGE__ );

And the action would notify all observers like this:

 package OpenInteract2::Handler::NewUser;
 
 # ... other methods here ...
 
 sub confirm_registration {
     my ( $self ) = @_;
     # ... check registration ...
     if ( $registration_ok ) {
         $self->notify_observers( 'register-confirm' );
         return $self->generate_content(
                        {}, { name => 'base_user::newuser_confirm_ok' } );
     }
 }

And in the documentation for the package 'base_user' (since this action lives there), you would have information about what notifications are published by the OpenInteract2::Handler::NewUser action.

MAPPING URL TO ACTION

In OI 1.x the name of an action determined what URL it responded to. This was simple but inflexible. This version gives you the option of decoupling the name and URL and allowing each action to respond to multiple URLs as well.

The default behavior is to respond to URLs generated from the action name. Unlike OI 1.x it is not strictly case-insensitive. It will respond to URLs formed from:

Lowercasing the action name
Uppercasing the action name
Uppercasing the first letter of the action name, lowercasing the rest.

For example, this action:

 [news]
 class = MyPackage::Action::News

will respond to the following URLs:

 /news/
 /NEWS/
 /News/

This default behavior can be modified and/or replaced by three properties:

url: Specify a single URL to which this action will respond. This replaces the default behavior.
url_none: Tell OI that this action cannot be accessed via URL, appropriate for box or other template-only actions. This replaces the default behavior.
url_alt: Specify a number of additional URLs to which this action will respond. This adds to the default behavior, and may also be used in conjunction with url (but not url_none).

Here are some examples to illustrate:

Use 'url' by itself:

 [news]
 class = MyPackage::Action::News
 url   = News

Responds to:

 /News/

Use 'url' with 'url_alt':

 [news]
 class   = MyPackage::Action::News
 url     = News
 url_alt = Nouvelles
 url_alt = Noticias

Responds to:

 /News/
 /Nouvelles/
 /Noticias/

Use default behavior with 'url_alt':

 [news]
 class   = MyPackage::Action::News
 url_alt = Nouvelles
 url_alt = Noticias

Responds to:

 /news/
 /NEWS/
 /News/
 /Nouvelles/
 /Noticias/

Use 'url_none':

 [news_box]
 class    = MyPackage::Action::News
 method   = box
 url_none = yes

Responds to: nothing

Use 'url_none' with 'url_alt':

 [news_box]
 class    = MyPackage::Action::News
 method   = box
 url_none = yes
 url_alt  = NoticiasBox

Responds to: nothing

The actual mapping of URL to Action is done in the OpenInteract2::Context method action_table(). Whenever the action table is assigned to the context is iterates through the actions, asks each one which URLs it responds to and creates a mapping so the URL can be quickly looked up.

One other thing to note about that context method: it also embeds primary URL for each action in the action information stored in the action table. Since the information is stored in a key that's not a property or parameter the action itself doesn't care about this. But it's useful to note because when you generate URLs based on an action the first URL is used, as discussed in the examples above.

So, to repeat the examples above, when you have:

 [news]
 class = MyPackage::Action::News
 url   = News

The first URL will be:

 /News/

When you have:

 [news]
 class   = MyPackage::Action::News
 url     = News
 url_alt = Nouvelles
 url_alt = Noticias

The first URL will still be:

 /News/

When you have:

 [news]
 class   = MyPackage::Action::News
 url_alt = Nouvelles
 url_alt = Noticias

The first URL will be:

 /news/

because the default always puts the lowercased entry first.

GENERATING CONTENT FOR ACTION

Actions always return content. The content is normally generated by passing data to some sort of template processor along with the template to use. The template processor passes the data to the template and returns the result.

The template processor is known as a 'content generator', since it does not need to use templates at all. OpenInteract maintains a list of content generators, each of which has a class and method associated with it. (You can grab a content generator from the OpenInteract2::Context object using get_content_generator().)

Generally, your handler can just call generate_content():

 sub show {
     my ( $self ) = @_;
     my $request = $self->request;
     my $news_id = $request->param( 'news_id' );
     my $news_class = CTX->lookup_object( 'news' );
     my $news = $news_class->fetch( $news_id )
                || $news_class->new();
     my %params = ( news => $news );
     return $self->generate_content(
                         \%params, { name => 'mypkg::error_page' } );
 }

And not care about how the object will get displayed. So this action could be declared in both of the following ways:

 [news]
 class             = OpenInteract2::Handler::News
 content_generator = TT
 
 [shownews]
 class             = OpenInteract2::Handler::News
 task              = show
 return_parameter  = news
 content_generator = SOAP

If the URL 'http://foo/news/show/?news_id=45' comes in from a browser we will pass the news object to the Template Toolkit generator which will display the news object in some sort of HTML page.

However, if the URL 'http://foo/news/shownews/' comes in via SOAP, with the parameter 'news_id' defined as '45', we will pass the same news object off to the SOAP content generator, which will take the 'news' parameter and place it into a SOAP response.

Caching

Another useful feature that comes from having the content generated in a central location is that your content can be cached transparently.

TODO: fill this in

PROPERTIES

You can set any of the properties with a method call. Examples are given for each.

request: The OpenInteract2::Request associated with the current request.

response: The OpenInteract2::Response associated with the current response.

name: The name of this action. This is normally used to lookup information from the action table.

This property is read-only -- it is set by the constructor when you create a new action, but you cannot change it after the action is created:

Example:

 print "Action name: ", $action->name, "\n";

url: URL used for this action. This is frequently the same as name, but you can override it in the action configuration. Note that this is not the fully qualified URL -- you need the create_url() method for that.

This property is read-only -- it is set by the constructor when you create a new action, but you cannot change it after the action is created:

Setting this property has implications as to what URLs your action will respond to. See "MAPPING URL TO ACTION" for more information.

Example:

 print "You requested ", $action->url, " within the application."

url_none: Set to 'yes' to tell OI that you do not want this action accessible via a URL. This is often done for boxes and other template-only actions. See "MAPPING URL TO ACTION" for more information.

Example:

 [myaction]
 class    = MyPackage::Action::MyBox
 method   = box
 title    = My Box
 weight   = 5
 url_none = yes

url_alt: A number of other URLs this action can be accessible by. See "MAPPING URL TO ACTION" for more information.

Example:

 [news]
 class    = MyPackage::Action::News
 url_alt  = Nouvelles
 url_alt  = Noticias

action_type: The type of action this is. Action types can provide default tasks, output filters, etc. This is not required.

Example:

 $action->action_type( 'common' );
 $action->action_type( 'directory_handler' );
 $action->action_type( 'template_only' );

task: What task should this action run? Generally this maps to a subroutine name, but the action can optionally provide its own dispatching mechanism which maps the task in a different manner. (See "Action Tasks" above for more information.)

Example:

 if ( $security_violation ) {
     $action->param( error_msg => "Security violation: $security_violation" );
     $action->task( 'search_form' );
     return $action->execute;
 }

content_generator: A named content generator. Your server configuration can have a number of content generators defined, and this property should contain the name of one.

Example:

 if ( $action->content_generator eq 'TT' ) {
     print "Content for this action will be generated by Template Toolkit.";
 }

The property is frequently inherited from the default action, so you may not see it explicitly declared in the action table.

is_secure: Whether to check security for this action. True is indicated by 'yes', false by 'no' (or anything else).

The return value is not the same as the value set. It returns a true value (1) if the action is secured (if set to 'yes'), a false one (0) if not.

Example:

 if ( $action->is_secure ) {
     my $level = CTX->check_security({ class => ref $action });
     if ( $level < SEC_LEVEL_WRITE ) {
         $action->param_add( error_msg => "Task forbidden due to security" );
         $action->task( 'search_form' );
         return $action->execute;
     }
 }

security_required: If the action is using security, what level is required for the action to successfully execute.

Example:

 if ( $action->is_secure ) {
     my $level = CTX->check_security({ class => ref $action });
     if ( $level < $action->security_required ) {
         $action->param_add( error_msg => "Task forbidden due to security" );
         $action->task( 'search_form' );
         return $action->execute;
     }
 }

(Note: you will never need to do this since the find_security_level() method does this (and more) for you.)

security_level: This is the security level found or set for this action and task. If you set this beforehand then the action dispatcher will not check it for you:

Example:

 # Action dispatcher will check the security level of the current user
 # for this action when 'execute()' is called.
 
 my $action = OpenInteract2::Action->new({
                    name           => 'bleeble',
                    task           => 'show' });
 return $action->execute;
 
 # Action dispatcher will use the provided level and not perform a
 # lookup for the security level on 'execute()'.
 
 my $action = OpenInteract2::Action->new({
                    name           => 'bleeble',
                    task           => 'show',
                    security_level => SEC_LEVEL_WRITE });
 return $action->execute;

task_valid: An arrayref of valid tasks for this action.

Example:

 my $ok_tasks = $action->task_valid;
 print "Tasks for this action: ", join( ', ', @{ $ok_tasks } ), "\n";

task_invalid: An arrayref of invalid tasks for this action. Note that the action dispatcher will never execute a task with a leading underscore (e.g., '_find_records');

Example:

 my $bad_tasks = $action->task_invalid;
 print "Tasks not allowed for action: ", join( ', ', @{ $bad_tasks } ), "\n";

METHODS

Class Methods

new( [ $name | $action | \%action_info ] [, \%values ] )

Create a new action. This has three flavors:

If passed $name we ask the OpenInteract2::Context to give us the action information for $name. If the action is not found an exception is thrown.

Any action properties provided in \%values will override the default properties set in the action table. And any items in \%values that are not action properties will be set into the action parameters, also overriding the values from the action table. (See param() below.)
If given $action we do a simulated clone: create an empty action object using the same class as $action and fill it with the properties and parameters from $action. Then we call init() on the new object and return it. (TODO: is init() redundant with a clone-type operation?)

Any values provided in \%properties will override the properties from the $action. Likewise, any parameters from \%properties will override the parameters from the $action.
If given \%action_info we create a new action of the type found in the 'class' key and assign the properties and paramters from the hashref to the action. We also do a 'require' on the given class to ensure it's available.

Any values provided in \%properties will override the properties from \%action_info. Likewise, any parameters from \%properties will override the parameters from the \%action_info. It's kind of beside the point since you can just pass them all in the first argument, but whatever floats your boat.

Returns: A new action object; throws an exception if $name is provided but not found in the Action Table.

Examples:

 # Create a new action of type 'news', set the task and execute
 
 my $action = OpenInteract2::Action->new( 'news' );
 $action->task( 'show' );
 $action->execute;
 
 # $new_action and $action are equivalent...
 
 my $new_action =
     OpenInteract2::Action->new( $action );

 # ...and this doesn't affect $action at all
 
 $new_action->task( 'list' );
 
 my $action = OpenInteract2::Action->new( 'news' );
 $action->task( 'show' );
 $action->param( soda => 'coke' );
 
 # $new_action and $action are equivalent except for the 'soda'
 # parameter and the 'task' property
 
 my $new_action =
     OpenInteract2::Action->new( $action, { soda => 'mr. pibb',
                                            task => 'list' } );
 
 # Create a new type of action on the fly
 
 my $action = OpenInteract2::Action->new(
                    { name         => 'foo',
                      class        => 'OpenInteract2::Action::FooAction',
                      task_default => 'drink',
                      soda         => 'Jolt' } );

register_action_type( $type, $class )

TODO: Do we still need this? It might be a good idea to keep to allow on-the-fly action creation but still allow some structure...

Let the main action class know about a custom action type. Once the type is registered you can create new actions of that type:

 OpenInteract2::Action->register_action_type( 'mytype', 'My::Action' );
 my $action = OpenInteract2::Action->new( 'test',
                                         { action_type => 'mytype',
                                           task        => 'show' });
 $action->execute;

Even though the action name 'test' might not be in the action table, the action knows what class to use since you have registered and use the type 'mytype'.

Returns: The class registered

Object Methods

init()

This method allows action subclasses to perform any additional initialization required. Note that before this method is called from new() all of the properties and parameters from new() have been set into the object whether you've created it using a name or by cloning anouther action.

If you define this you must call SUPER::init() so that all parent classes have a chance to perform initialization as well.

Returns: The action object, or undef if initialization failed.

Example:

 package OpenInteract2::Action::MyAction;
 
 use base qw( OpenInteract2::Action );
 
 my %DEFAULTS = ( foo => 'bar', baz => 'quux' );
 sub init {
     my ( $self ) = @_;
     while ( my ( $key, $value ) = each %DEFAULTS ) {
         unless ( $self->param( $key ) ) {
             $self->param( $key, $value );
         }
     }
     return $self->SUPER::init();
 }

create_url( \%params )

Generate a self-referencing URL to this action, using \%params as an appended query string. Under the covers we use OpenInteract2::URL to do the real work.

Note that you can also override the task set in the current action using the 'TASK' parameter. So you could be on the form display for a particular object and generate a URL for the removal task by passing 'remove' in the 'TASK' parameter.

See "MAPPING URL TO ACTION" for a discussion of how an action is mapped to multiple URLs and which URL will be chosen as the base for the URL generated by this method.

Returns: URL for this action

Examples:

 my $action = OpenInteract2::Action->new({ name => 'games',
                                           task => 'explore' });
 my $url = $action->create_url;
 # $url: "/games/explore/"
 my $url = $action->create_url({ edit => 'yes' });
 # $url: "/games/explore/?edit=yes"
 my $url = $action->create_url({ TASK => 'edit', game_id => 42 });
 # $url: "/games/edit/?game_id=42"
 
 <a href="[% action.create_url( edit = 'yes' ) %]">Click me!</a>
 # <a href="/games/explore/?edit=yes">Click me!</a>
 <a href="[% action.create_url( task = 'EDIT', game_id = 42 ) %]">Click me!</a>
 # <a href="/games/edit/?game_id=42">Click me!</a>
 
 CTX->assign_deploy_url( '/Archives' );
 my $url = $action->create_url;
 # $url: "/Archives/games/explore/"
 my $url = $action->create_url({ edit => 'yes' });
 # $url: "/Archives/games/explore/?edit=yes"
 my $url = $action->create_url({ TASK => 'edit', game_id => 42 });
 # $url: "/Archives/games/edit/?game_id=42"
 
 <a href="[% action.create_url( edit = 'yes' ) %]">Click me!</a>
 # <a href="/Archives/games/explore/?edit=yes">Click me!</a>
 <a href="[% action.create_url( task = 'EDIT', game_id = 42 ) %]">Click me!</a>
 # <a href="/Archives/games/edit/?game_id=42">Click me!</a>

get_dispatch_urls

Retrieve an arrayref of the URLs this action is dispatched under. This may be an empty arrayref if the action is not URL-accessible.

This is normally only called at OpenInteract2::Context startup when it reads in the actions from all the packages, but it might be informative elsewhere as well. (For instance, we use it in the management task 'list_actions' to show all the URLs each action responds to.) See "MAPPING URL TO ACTION" for how the method works.

Returns: arrayref of URLs this action is dispatched under.

Example:

 my $urls = $action->get_dispatch_urls;
 print "This action is available under the following URLs: \n";
 foreach my $url ( @{ $urls } ) {
     print " *  $url\n";
 }

Object Execution Methods

execute( \%params )

Generate content for this action and task. If the task has an error it can generate error content and die with it; it can also just die with an error message, but that's not very helpful to your users.

The \%params argument will set properties and parameters (via property_assign() and param_assign()) before generating the content.

Returns: content generated by the action

forward( $new_action )

Forwards execution to $new_action.

Returns: content generated by calling execute() on $new_action.

Examples:

 sub edit {
     my ( $self ) = @_;
     # ... do edit ...
     my $list_action = CTX->lookup_action( 'object_list' );
     return $self->forward( $list_action );
 }

find_task()

Tries to find a task for the action. In order, the method looks:

In the 'method' property of the action. This means the action is hardwired to a particular method and cannot be changed, even if you set 'task' manually.

TODO: This might change... why use 'method' when we could keep with the task terminology and use something like 'task_concrete' or 'task_only'?
In the 'task' property of the action: it might already be defined!
In the 'task_default' property of the action.

If a task is not found we throw an exception.

Returns: name of task.

check_task_validity()

Ensure that task assigned is valid. If it is not we throw an OpenInteract2::Exception.

A valid task:

Does not begin with an underscore.
Is not listed in the task_invalid property.
Is listed in the task_valid property, if that property is defined.

Returns: nothing, throwing an exception if the check fails.

find_task_method()

Finds a valid method to call for the action task. If the method handler() is defined in the action class or any of its parents, that is called. Otherwise we check to see if the method $task() -- which should already have been checked for validity -- is defined in the action class or any of its parents. If neither is found we throw an exception.

You are currently not allowed to have a task of the same name as one of the action properties. If you try to execute a task by this name you'll get a message in the error log to this effect.

Note that we cache the returned code reference, so if you do something funky with the symbol table or the @ISA for your class after a method has been called, everything will be mucked up.

Returns: code reference to method for task.

find_security_level()

If this action is secured, finds the security level for this combination of action, user and groups.

First it looks at the 'is_secure' action property -- if true we continue, otherwise we return SEC_LEVEL_WRITE so the system will allow any user to perform the task.
Second, we call get_security_requirements() to get a hashref of security required for the action. If one is not returned we throw an exception.
Third, we find the security level required for this particular task. If neither the task nor 'DEFAULT' is not defined in the hashref of security requirements, we assume that SEC_LEVEL_WRITE security is required.
Fourth, we find the actual security level for this action and user.
Finally, we compare the required security with the actual security. If the actual is less than the required we throw an OpenInteract2::Exception::Security object. Otherwise we set the actual security level under the property 'security_level'.

Returns: valid security level found; if security level less than required an exception is thrown.

Object Content Methods

generate_content( \%content_params, \%template_source, [ \%template_params ] )

This is used to generate content for an action.

TODO: fill this in

Object Property and Parameter Methods

property_assign( \%properties )

Assigns values from properties specified in \%properties. Only the valid properties for actions will be set, everything else will be skipped.

Currently we only set properties for which there is a defined value.

Returns: action object ($self)

See PROPERTIES for the list of properties in each action.

property( [ $name, $value ] )

Get/set action properties. (In addition to direct method call, see below.) This can be called in three ways:

 my $props   = $action->property;            # $props is hashref
 my $value   = $action->property( $name );   # $value is any type of scalar
 $new_value  = $action->property( $name, $new_value );

Returns: if called without arguments, returns a copy of the hashref of properties attached to the action (changes made to the hashref will not affect the action); if called with one or two arguments, returns the new value of the property $name.

Note that this performs the same action as the direct method call with the property name:

 # Same
 $action->property( $property_name );
 $action->$property_name();

 # Same
 $action->property( $property_name, $value );
 $action->$property_name( $value );

See PROPERTIES for the list of properties in each action.

property_clear( $key )

Sets the property defined by $key to undef. This is the only way to unset a property.

Returns: value previously set for the property $key.

See PROPERTIES for the list of properties in each action.

param_assign( \%params )

Assigns all items from \%params that are not valid properties to the action as parameters.

Currently we only set parameters for which there is a defined value.

Returns: action object ($self)

param( [ $key, $value ] )

Get/set action parameters. This can be called in three ways:

 my $params  = $action->param;             # $params is hashref
 my $value   = $action->param( $name );    # $value is any type of scalar
 $action->param( $name, $new_value );
 my ( @params ) = $action->param( $name ); # ...context senstive

Returns: if called without arguments, returns a copy of the hashref of parameters attached to the action (changes made to the hashref will not affect the action); if called with one or two arguments, returns the context-sensitve new value of the parameter $name.

param_add( $key, @values )

Adds the values @value to the parameter $key. If there is a value already set for $key, or if you pass multiple values, it's turned into an array reference and @values pushed onto the end. If there is no value already set and you only pass a single value it acts like the call to param( $key, $value ).

This is useful for potentially multivalue parameters, such as the often-used 'error_msg' and 'status_msg'. You can still access the values with param() in context:

 $action->param( error_msg => "Ooops I..." );
 $action->param_add( error_msg => "did it again" );
 my $full_msg = join( ' ', $action->param( 'error_msg' ) );
 # $full_msg = 'Ooops I... did it again'
 
 $action->param( error_msg => "Ooops I..." );
 $action->param_add( error_msg => "did it again" );
 $action->param( error_msg => 'and again' );
 my $full_msg = join( ' ', $action->param( 'error_msg' ) );
 # $full_msg = 'and again'
 
 $action->param( error_msg => "Ooops I..." );
 $action->param_add( error_msg => "did it again" );
 my $messages = $action->param( 'error_msg' );
 # $messages->[0] = 'Ooops I...'
 # $messages->[1] = 'did it again'

Returns: Context senstive value in of $key

param_clear( $key )

Removes all parameter values defined by $key. This is the only way to remove a parameter.

Returns: value(s) previously set for the parameter $key, non-context sensitive.

param_from_request( @param_names )

Sets the action parameter value to the request parameter value for each name in @param_names.

This will overwrite existing action parameters if they are not already defined.

Returns: nothing

BUGS

None known.

TO DO

URL handling

How we respond to URLs and the URLs we generate for ourselves is a little confusing. We may want to ensure that when a use requests an alternate URL -- for instance '/Nouvelles/' for '/News/' -- that the URL generated from 'create_url()' also uses '/Nouvelles/'. Currently it does not, since we're using OI2::URL to generate the URL for us and on the method call it's divorced from the action state.

We could get around this with an additional property 'url_requested' (or something) which would only be set in the constructor if the 'REQUEST_URL' is passed in. Then the 'create_url' would use it and call the 'create' method rather than 'create_from_action' method in OI2::URL.

COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

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

Action Tasks

Action Types

Action Properties vs. Parameters

Observable Actions

MAPPING URL TO ACTION

GENERATING CONTENT FOR ACTION

Caching

PROPERTIES

METHODS

Class Methods

Object Methods

Object Execution Methods

Object Content Methods

Object Property and Parameter Methods

BUGS

TO DO

SEE ALSO

COPYRIGHT

AUTHORS

Module Install Instructions