head	1.3;
access;
symbols;
locks; strict;
comment	@# @;


1.3
date	2008.01.22.03.21.26;	author TWikiContributor;	state Exp;
branches;
next	1.2;

1.2
date	2007.01.16.04.12.03;	author TWikiContributor;	state Exp;
branches;
next	1.1;

1.1
date	2006.02.01.12.01.25;	author TWikiContributor;	state Exp;
branches;
next	;


desc
@new-topic
@


1.3
log
@buildrelease
@
text
@---+ Package =TWiki::OopsException=

Exception used to raise a request to redirect to an Oops URL.

An OopsException thrown anywhere in the code will redirect the
browser to a url based on the =oops= script. =oops= requires
the name of an oops template file from the =templates= directory.
This file will be expanded and the
parameter values passed to the exception instantiated. The
result will be shown in the browser.

Plugins may throw TWiki::OopsException. For example:

<verbatim>
use Error;

...

throw TWiki::OopsException( 'bathplugin',
                            def => 'toestuck',
                            web => $web,
                            topic => $topic,
                            params => [ 'bigtoe', 'hot tap' ] );


%TOC%

---++ ClassMethod *new* <tt>($template,...)</tt>
   * =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



---++ ObjectMethod *stringify* <tt>([$session]) -> $string</tt>

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 *redirect* <tt>($twiki)</tt>

Generate a redirect to an 'oops' script for this exception.

If the 'keep' parameter is set in the
exception, it saves parameter values into the query as well. This is needed
if the query string might get lost during a passthrough, due to a POST
being redirected to a GET.


@


1.2
log
@buildrelease
@
text
@a1 1
*extends* <tt>Error</tt>
d3 1
a4 1
Exception used to raise a request to redirect to an Oops URL.
d6 3
a8 3
browser to a url based on the =oops= script. =oops= requires a
=template= parameter, that is the name of a template file from
the =templates= directory. This file will be expanded and the
d12 13
d29 1
a29 1
   * =template= is the name of an oops template
d34 1
a34 1
   * =keep= - if set, the exception handler should try it's damndest to retain parameter values from the query.
d37 5
d46 15
a60 3
Generates a string representation for the object. if a session is passed in, and
the excpetion specifies a def, then that def is expanded. This is to allow
internal expansion of oops exceptions for example when performing bulk operations.
@


1.1
log
@buildrelease
@
text
@d27 1
a27 1
---++ ObjectMethod *stringify* <tt>() -> $string</tt>
d29 3
a31 1
Generates a string representation for the object, mainly for debugging.
@
