data/TWiki/TWikiOopsExceptionDotPm.txt,v
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
     1 head	1.3;
     2 access;
     3 symbols;
     4 locks; strict;
     5 comment	@# @;
     6 
     7 
     8 1.3
     9 date	2008.01.22.03.21.26;	author TWikiContributor;	state Exp;
    10 branches;
    11 next	1.2;
    12 
    13 1.2
    14 date	2007.01.16.04.12.03;	author TWikiContributor;	state Exp;
    15 branches;
    16 next	1.1;
    17 
    18 1.1
    19 date	2006.02.01.12.01.25;	author TWikiContributor;	state Exp;
    20 branches;
    21 next	;
    22 
    23 
    24 desc
    25 @new-topic
    26 @
    27 
    28 
    29 1.3
    30 log
    31 @buildrelease
    32 @
    33 text
    34 @---+ Package =TWiki::OopsException=
    35 
    36 Exception used to raise a request to redirect to an Oops URL.
    37 
    38 An OopsException thrown anywhere in the code will redirect the
    39 browser to a url based on the =oops= script. =oops= requires
    40 the name of an oops template file from the =templates= directory.
    41 This file will be expanded and the
    42 parameter values passed to the exception instantiated. The
    43 result will be shown in the browser.
    44 
    45 Plugins may throw TWiki::OopsException. For example:
    46 
    47 <verbatim>
    48 use Error;
    49 
    50 ...
    51 
    52 throw TWiki::OopsException( 'bathplugin',
    53                             def => 'toestuck',
    54                             web => $web,
    55                             topic => $topic,
    56                             params => [ 'bigtoe', 'hot tap' ] );
    57 
    58 
    59 %TOC%
    60 
    61 ---++ ClassMethod *new* <tt>($template,...)</tt>
    62    * =template= is the name of an oops template. e.g. 'bathplugin' refers to =templates/oopsbathplugin.tmpl=
    63 The remaining parameters are interpreted as key-value pairs. The following keys are used:
    64    * =web= will be used as the web for the oops
    65    * =topic= will be used as the topic for the oops
    66    * =def= - is the (optional) name of a TMPL:DEF within the template
    67    * =keep= - if set, the exception handler should try its damnedest to retain parameter values from the query.
    68    * =params= is a reference to an array of parameters. These will be substituted for !%PARAM1%, !%PARAM2% ... !%PARAMn% in the template.
    69 
    70 For an example of how to use the =def= parameter, see the =oopsattention=
    71 template.
    72 
    73 NOTE: parameter values are automatically and unconditionally entity-encoded
    74 
    75 
    76 
    77 ---++ ObjectMethod *stringify* <tt>([$session]) -> $string</tt>
    78 
    79 Generates a string representation for the object. if a session is passed in,
    80 and the exception specifies a def, then that def is expanded. This is to allow
    81 internal expansion of oops exceptions for example when performing bulk
    82 operations, and also for debugging.
    83 
    84 
    85 
    86 ---++ ObjectMethod *redirect* <tt>($twiki)</tt>
    87 
    88 Generate a redirect to an 'oops' script for this exception.
    89 
    90 If the 'keep' parameter is set in the
    91 exception, it saves parameter values into the query as well. This is needed
    92 if the query string might get lost during a passthrough, due to a POST
    93 being redirected to a GET.
    94 
    95 
    96 @
    97 
    98 
    99 1.2
   100 log
   101 @buildrelease
   102 @
   103 text
   104 @a1 1
   105 *extends* <tt>Error</tt>
   106 d3 1
   107 a4 1
   108 Exception used to raise a request to redirect to an Oops URL.
   109 d6 3
   110 a8 3
   111 browser to a url based on the =oops= script. =oops= requires a
   112 =template= parameter, that is the name of a template file from
   113 the =templates= directory. This file will be expanded and the
   114 d12 13
   115 d29 1
   116 a29 1
   117    * =template= is the name of an oops template
   118 d34 1
   119 a34 1
   120    * =keep= - if set, the exception handler should try it's damndest to retain parameter values from the query.
   121 d37 5
   122 d46 15
   123 a60 3
   124 Generates a string representation for the object. if a session is passed in, and
   125 the excpetion specifies a def, then that def is expanded. This is to allow
   126 internal expansion of oops exceptions for example when performing bulk operations.
   127 @
   128 
   129 
   130 1.1
   131 log
   132 @buildrelease
   133 @
   134 text
   135 @d27 1
   136 a27 1
   137 ---++ ObjectMethod *stringify* <tt>() -> $string</tt>
   138 d29 3
   139 a31 1
   140 Generates a string representation for the object, mainly for debugging.
   141 @