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