data/TWiki/TWikiOopsExceptionDotPm.txt
author Colas Nahaboo <colas@nahaboo.net>
Sat, 26 Jan 2008 15:50:53 +0100
changeset 0 414e01d06fd5
permissions -rw-r--r--
RELEASE 4.2.0 freetown
colas@0
     1
---+ Package =TWiki::OopsException=
colas@0
     2
colas@0
     3
Exception used to raise a request to redirect to an Oops URL.
colas@0
     4
colas@0
     5
An OopsException thrown anywhere in the code will redirect the
colas@0
     6
browser to a url based on the =oops= script. =oops= requires
colas@0
     7
the name of an oops template file from the =templates= directory.
colas@0
     8
This file will be expanded and the
colas@0
     9
parameter values passed to the exception instantiated. The
colas@0
    10
result will be shown in the browser.
colas@0
    11
colas@0
    12
Plugins may throw TWiki::OopsException. For example:
colas@0
    13
colas@0
    14
<verbatim>
colas@0
    15
use Error;
colas@0
    16
colas@0
    17
...
colas@0
    18
colas@0
    19
throw TWiki::OopsException( 'bathplugin',
colas@0
    20
                            def => 'toestuck',
colas@0
    21
                            web => $web,
colas@0
    22
                            topic => $topic,
colas@0
    23
                            params => [ 'bigtoe', 'hot tap' ] );
colas@0
    24
colas@0
    25
colas@0
    26
%TOC%
colas@0
    27
colas@0
    28
---++ ClassMethod *new* <tt>($template,...)</tt>
colas@0
    29
   * =template= is the name of an oops template. e.g. 'bathplugin' refers to =templates/oopsbathplugin.tmpl=
colas@0
    30
The remaining parameters are interpreted as key-value pairs. The following keys are used:
colas@0
    31
   * =web= will be used as the web for the oops
colas@0
    32
   * =topic= will be used as the topic for the oops
colas@0
    33
   * =def= - is the (optional) name of a TMPL:DEF within the template
colas@0
    34
   * =keep= - if set, the exception handler should try its damnedest to retain parameter values from the query.
colas@0
    35
   * =params= is a reference to an array of parameters. These will be substituted for !%PARAM1%, !%PARAM2% ... !%PARAMn% in the template.
colas@0
    36
colas@0
    37
For an example of how to use the =def= parameter, see the =oopsattention=
colas@0
    38
template.
colas@0
    39
colas@0
    40
NOTE: parameter values are automatically and unconditionally entity-encoded
colas@0
    41
colas@0
    42
colas@0
    43
colas@0
    44
---++ ObjectMethod *stringify* <tt>([$session]) -> $string</tt>
colas@0
    45
colas@0
    46
Generates a string representation for the object. if a session is passed in,
colas@0
    47
and the exception specifies a def, then that def is expanded. This is to allow
colas@0
    48
internal expansion of oops exceptions for example when performing bulk
colas@0
    49
operations, and also for debugging.
colas@0
    50
colas@0
    51
colas@0
    52
colas@0
    53
---++ ObjectMethod *redirect* <tt>($twiki)</tt>
colas@0
    54
colas@0
    55
Generate a redirect to an 'oops' script for this exception.
colas@0
    56
colas@0
    57
If the 'keep' parameter is set in the
colas@0
    58
exception, it saves parameter values into the query as well. This is needed
colas@0
    59
if the query string might get lost during a passthrough, due to a POST
colas@0
    60
being redirected to a GET.
colas@0
    61
colas@0
    62