1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/data/TWiki/TWikiOopsExceptionDotPm.txt	Sat Jan 26 15:50:53 2008 +0100
     1.3 @@ -0,0 +1,62 @@
     1.4 +---+ Package =TWiki::OopsException=
     1.5 +
     1.6 +Exception used to raise a request to redirect to an Oops URL.
     1.7 +
     1.8 +An OopsException thrown anywhere in the code will redirect the
     1.9 +browser to a url based on the =oops= script. =oops= requires
    1.10 +the name of an oops template file from the =templates= directory.
    1.11 +This file will be expanded and the
    1.12 +parameter values passed to the exception instantiated. The
    1.13 +result will be shown in the browser.
    1.14 +
    1.15 +Plugins may throw TWiki::OopsException. For example:
    1.16 +
    1.17 +<verbatim>
    1.18 +use Error;
    1.19 +
    1.20 +...
    1.21 +
    1.22 +throw TWiki::OopsException( 'bathplugin',
    1.23 +                            def => 'toestuck',
    1.24 +                            web => $web,
    1.25 +                            topic => $topic,
    1.26 +                            params => [ 'bigtoe', 'hot tap' ] );
    1.27 +
    1.28 +
    1.29 +%TOC%
    1.30 +
    1.31 +---++ ClassMethod *new* <tt>($template,...)</tt>
    1.32 +   * =template= is the name of an oops template. e.g. 'bathplugin' refers to =templates/oopsbathplugin.tmpl=
    1.33 +The remaining parameters are interpreted as key-value pairs. The following keys are used:
    1.34 +   * =web= will be used as the web for the oops
    1.35 +   * =topic= will be used as the topic for the oops
    1.36 +   * =def= - is the (optional) name of a TMPL:DEF within the template
    1.37 +   * =keep= - if set, the exception handler should try its damnedest to retain parameter values from the query.
    1.38 +   * =params= is a reference to an array of parameters. These will be substituted for !%PARAM1%, !%PARAM2% ... !%PARAMn% in the template.
    1.39 +
    1.40 +For an example of how to use the =def= parameter, see the =oopsattention=
    1.41 +template.
    1.42 +
    1.43 +NOTE: parameter values are automatically and unconditionally entity-encoded
    1.44 +
    1.45 +
    1.46 +
    1.47 +---++ ObjectMethod *stringify* <tt>([$session]) -> $string</tt>
    1.48 +
    1.49 +Generates a string representation for the object. if a session is passed in,
    1.50 +and the exception specifies a def, then that def is expanded. This is to allow
    1.51 +internal expansion of oops exceptions for example when performing bulk
    1.52 +operations, and also for debugging.
    1.53 +
    1.54 +
    1.55 +
    1.56 +---++ ObjectMethod *redirect* <tt>($twiki)</tt>
    1.57 +
    1.58 +Generate a redirect to an 'oops' script for this exception.
    1.59 +
    1.60 +If the 'keep' parameter is set in the
    1.61 +exception, it saves parameter values into the query as well. This is needed
    1.62 +if the query string might get lost during a passthrough, due to a POST
    1.63 +being redirected to a GET.
    1.64 +
    1.65 +