Foswiki::OopsException

package Foswiki::OopsException

Exception used to raise a request to output a preformatted page.

Despite the name, oops is not used just for errors; it is also used for one-time redirection, for example during the registration process.

The Foswiki::UI::run function, which is in the call stack for almost all cases where an OopsException will be thrown, traps the exception and outputs an oops page to the browser. This requires the name of a template file from the templates directory, which it expands. Parameter values passed to the exception are instantiated in the expanded template. The oops page is output with an HTTP status appropriate to the event that caused the exception (default 500).

Extensions may throw Foswiki::OopsException. For example:

use Error qw(:try);

...

throw Foswiki::OopsException( 'bathplugin',
                            status => 418,
                            web => $web,
                            topic => $topic,
                            params => [ 'big toe', 'stuck in', 'hot tap' ] );

This will raise an exception that uses the bathplugin.tmpl template. If UI::run handles the exception it will generate a redirect to:

oops?template=bathplugin;param1=bigtoe;param2=hot%20tap

The bathplugin.tmpl might contain:

%TMPL:INCLUDE{"oops"}%
%TMPL:DEF{"titleaction"}% %MAKETEXT{"Bathing problem"}% %TMPL:END%
%TMPL:DEF{"heading"}%%MAKETEXT{"Problem filling bath"}%%TMPL:END%
%TMPL:DEF{"topicactionbuttons"}%%TMPL:P{"oktopicaction"}%%TMPL:END%
%TMPL:DEF{"script"}%<meta http-equiv="refresh" content="0;url=%SCRIPTURL{view}%/%WEB%/%TOPIC%" />%TMPL:END%
%TMPL:DEF{"pagetitle"}%%TMPL:P{"heading"}%%TMPL:END%
%TMPL:DEF{"webaction"}% *%MAKETEXT{"Warning"}%* %TMPL:END%
%TMPL:DEF{"message"}%
%MAKETEXT{"Your bath cannot be filled because your [_1] is [_2] the [_3]%TMPL:END%

In this case the oops page will be rendered with a 418 ("I'm a teapot") status in the HTTP header.

A more practical example for plugins authors that does not require them to provide their own template file involves use of the generic message template available from oopsattention.tmpl:

throw Foswiki::OopsException( 'oopsattention', def => 'generic',
   params => [ Operation is not allowed  ] );

Note that to protect against cross site scripting all parameter values are automatically and unconditionally entity-encoded so you cannot pass macros if you need messages to be automatically translated you either need to handle it in the perl code before throwing Foswiki::OopsException or put the %MAKETEXT in the template. You cannot pass macros through the parameters.

API version $Date: 2009-12-11 10:25:14 +0100 (Fri, 11 Dec 2009) $ (revision $Rev: 6075 (2010-01-17) $)

Since date indicates where functions or parameters have been added since the baseline of the API (TWiki release 4.2.3). The date indicates the earliest date of a Foswiki release that will support that function or parameter.

Deprecated date indicates where a function or parameters has been deprecated. Deprecated functions will still work, though they should not be called in new plugins and should be replaced in older plugins as soon as possible. Deprecated parameters are simply ignored in Foswiki releases after date.

Until date indicates where a function or parameter has been removed. The date indicates the latest date at which Foswiki releases still supported the function or parameter.

ClassMethod new( $template, ...)

• template is the name of an oops template. e.g. 'bathplugin' refers to templates/oopsbathplugin.tmpl

The remaining parameters are interpreted as key-value pairs. The following keys are used:

• web will be used as the web for the oops
• topic will be used as the topic for the oops
• def - is the (optional) name of a TMPL:DEF within the template
• keep - if set, the exception handler should try its damnedest to retain parameter values from the query.
• params is a reference to an array of parameters. These will be substituted for %PARAM1%, %PARAM2% ... %PARAMn% in the template.

For an example of how to use the def parameter, see the oopsattention template.

NOTE: parameter values are automatically and unconditionally entity-encoded so you cannot pass macros

ObjectMethod stringify( [$session] ) -> $string

Generates a string representation for the object. if a session is passed in, and the exception specifies a def, then that def is expanded. This is to allow internal expansion of oops exceptions for example when performing bulk operations, and also for debugging.

ObjectMethod generate( $session )

Generate an error page for the exception. This will output the error page to the browser. The default HTTP Status for an Oops page is 500. This can be overridden using the 'status => ' parameter to the constructor.