Not a developer? Go to MovableType.com

MovableType.org
Documentation
Home / Documentation / Developer Applications

Control Flow in a Template

When a mode handler completes its operation it can return either a block of HTML that will be returned directly to the browser, or it can return a number of values to control the flow of the user to another page in the application. For example, a handler can signal to Movable Type that there was an error, or that a redirect to another URL is needed. Here is a list of the various return functions:

$app->add_return_arg( %hash )

This method is used prior to returning from your mode handler. It is used to append querystring parameters to the URL of the page the user is ultimately redirected to. A common usage for this method is to append a querystring parameter that can be used to surface a status message of some kind on the destination page. This is how, for example, Movable Type is able to add the “You entry has been saved” informational message to the screen after saving and publishing a blog post.

Let’s take a look at the following code sample.

sub handler {
    my $app = shift;
    # do something
    $app->add_return_arg( object_saved => 1 );
    return $app->call_return;
}

Let’s say that the user invoked this mode from the following URL:

http://somedomain.com/cgi-bin/mt/mt.cgi?__mode=my_handler

Then the code above will return the user to the same URL, but with the following URL:

http://somedomain.com/cgi-bin/mt/mt.cgi?__mode=my_handler&object_saved=1

$app->call_return()

Invoking call_return() will return the user to the page from which they originated. This method is commonly invoked in conjunction with the add_return_arg() method as discussed above.

$app->error($str)

The error method instructs Movable Type to return an application error with a message designated by the developer. The error message will also be logged in Movable Type’s Activity Log as an error.

sub handler {
    my $app = shift;
    # do something
    return $app->error("What are you doing Dave?");
}

$app->errtrans($str)

The errortrans method does the same as $app->error() except that it routes the error message through Movable Type’s built in translation system in an attempt to return the error message in the appropriate language. 

sub handler {
    my $app = shift;
    # do something
    return $app->errortrans("What are you doing Dave?");
}

$app->logout()

This method can be invoked to forcibly logout the current user from the blog or application.

$app->mode($mode)

This sets the current mode of the application. It can be used to control which application mode is used to render the page in response to the current request. The following code sample for example will process the request, and then invoke the mode registered with name of “a_different_mode”.

sub handler {
    my $app = shift;
    # do something
    return $app->mode( 'a_different_mode' );
}

$app->redirect($url, %options)

The redirect method initiates an HTTP redirect by setting the HTTP “Location” header for the response. The value can be set at any time during the course of the request. 

sub handler {
    my $app = shift;
    # do something
    $app->redirect('http://www.somedomain.com/');
    # do something else
    return;
}

Redirects made in this manner are sent in conjunction with an HTTP status code of 302.

Allowable options are:

  • UseMeta - If set to true then the request will be redirected by issuing a text/html entity body that contains a “meta redirect” tag. This option can be used to work around clients that won’t accept cookies as part of a 302 Redirect response.

$app->trace($msg)

This method is used for debugging. Under normal operating conditions this method will do nothing. When DebugMode is turned on however, this method will result in the message provided to be displayed at the bottom of the screen in a special debugging section of the footer.

Back