NAME

XAO::DO::Web::Action - base for mode-dependant displayable objects

SYNOPSIS

package XAO::DO::Web::Fubar;
use strict;
use XAO::Objects;
use XAO::Errors qw(XAO::DO::Web::Fubar);
use base XAO::Objects->load(objname => 'Web::Action');


# <%Fubar mode='foo'%>
#
sub display_foo ($@) {
   ...
}

# <%Fubar mode='kick' target='ass'%>
#
sub data_kick ($@) {
   my $self=shift;
   my $args=get_args(\@_);
   my $target=$args->{'target'} || 'self';
   return {
       force   => $self->siteconfig->get("/targets/$target/force"),
       target  => $target,
   }
}

# Gets called with prepared data
#
sub display_kick ($@) {
   my $self=shift;
   my $args=get_args(\@_);
   dprint "force=",$args->{'force'};
   ...
}

# Data only method, will output JSON
# (will also set content-type to application/json!)
#
# <%Fubar mode='api'%>
#
# Data prepared as above, but displayed with a custom
# display method:
#
# <%Fubar mode='api' displaymode='api-summary'%>
#
sub data_api ($@) {
   my $self=shift;
   my $args=get_args(\@_);
   return $self->data_kick($args);
}

sub display_api_summary ($@) {
   my $self=shift;
   my $args=get_args(\@_);
   return $self->textout($args->{'data'}->{'target'}.' will get kicked');
}

# This is obsolete, but still supported
#
sub check_mode ($$) {
    my $self=shift;
    my $args=get_args(\@_);
    my $mode=$args->{'mode'};
    if($mode eq "foo") {
        $self->foo($args);
    }
    elsif($mode eq "kick") {
        $self->kick($args);
    }
    else {
        $self->SUPER::check_mode($args);
    }
}

DESCRIPTION

Very simple object with overridable check_mode method. Simplifies implementation of objects with arguments like:

<%Fubar mode="kick" target="ass"%>

The code will attempt to find and call a "data_kick" method first (dashes in 'mode' are replaced with underscores). It needs to return some data, a hash or an array reference typically. If there is no matching data_* method found then no data is built.

The next step is to try finding a "display_kick" method. If it exists it is called with original arguments plus "data" set to the data received. If there is no data, then there is no extra argument added to the display_* method (and should there be a 'data' argument it is not modified).

The name of the data producing method is derived from 'datamode' defaulting to 'mode' arguments. The name of display method is derived from 'displaymode' defaulting to 'mode' arguments. This allows to reuse the same data builder with various "views", aka display methods. You can also force data display in the presense of a custom display method by setting 'displaymode' to 'data'.

If there is a data_* method, but there is no display_* method, then the default is to call display_data() -- which outputs the data in a format given by 'format' argument (only JSON and XML is supported currently).

If there are both data_* and display_* methods then the output depends on its content.

If there is no data_* and no display_* then a check_mode() method is called that needs to work out what needs to be done. This is an obsolete practice.

The default check_mode() method does not have any functionality and always simply throws an error with the content of 'mode':

throw $self "- unknown mode ($mode)";

Remember that using "throw $self" you actually throw an error that depends on the namespace of your object and therefore can be caught separately if required.

JSON Encoding Configuration

The JSON encoding can be controlled with two site configuration values:

/xao/action/json_pretty    - insert line breaks to make JSON easier to read
/xao/action/json_canonical - sort hash keys to stabilize the output

EXPORTS

Nothing.

AUTHOR

Copyright (c) 2005-2013 Andrew Maltsev, Ejelta LLC

Copyright (c) 2001-2004 Andrew Maltsev, XAO Inc.

<am@ejelta.com> -- http://ejelta.com/xao/

SEE ALSO

Recommended reading: XAO::Web, XAO::DO::Web::Page.