Skip to content

Commit

Permalink
use sections (much easier to read)
Browse files Browse the repository at this point in the history
  • Loading branch information
@racke
racke committed Dec 5, 2008
1 parent 59176f2 commit ca7741e
Showing 1 changed file with 117 additions and 95 deletions.
212 changes: 117 additions & 95 deletions refs/SpecialSub
View file
Expand Up @@ -10,109 +10,131 @@ __END__


__NAME__ description
<para>
The directive specifies &PERL; subroutines that should be called to
handle certain events.
handle certain events. The available events are described below.
</para>
<refsect2>
<title>Request (<literal>request_init</literal>)</title>
<para>
Event triggered on every request, right after catalog
selection and before &glos-session; assignment.
</para>
</refsect2>
<refsect2>
<title>Request (<literal>admin_init</literal>)</title>
<para>
Event triggered on every request for users with administrator privileges,
request, after initialization of embedded Perl objects. This allows
&glos-catalog; subroutines to be specified as request handlers and have
properly initialized &glos-session; variables by the time they run.
</para>
</refsect2>
<refsect2>
<title>Debug Qualify (<literal>debug_qualify</literal>)</title>
<para>
Event triggered to determine whether &glos-debug; mode should be
enabled for the incoming client connection. Have in mind that simple,
host-based decision can be made by using the &conf-DebugHost;
configuration directive. The <literal>debug_qualify</literal>
specialSub is invoked only if &conf-DebugHost; is either undefined,
or the client host is found in the &conf-DebugHost; list.
See &glos-debug; glossary entry for a complete discussion.
</para>
</refsect2>
<refsect2>
<title>Flypage (<literal>flypage</literal>)</title>
<para>
Event triggered for determining the result set for the flypage.
<!-- TODO more info -->
</para>
</refsect2>
<refsect2>
<title>Credit Card Type (<literal>guess_cc_type</literal>)</title>
<para>
Event triggered at the time
of deriving credit card type, &var-MV_CREDIT_CARD_TYPE;.
&IC; already recognizes
major credit card types but local areas might require you to
write custom recognition code.
The subroutine is called with the credit card number.
A &glos-true; return value should contain the recognized credit card
type name.
A &glos-false; value indicates that the number recognition did not
suceed, and that &IC; should proceed with its built-in detection
algorithm.
</para>
</refsect2>
<refsect2>
<title>Session Creation (<literal>init_session</literal>)</title>
<para>
Event triggered at new &glos-session; creation time.
The subroutine is called with the pointer to the newly created
&glos-session; variables space. Subroutine return value is not used.
</para>
</refsect2>
<refsect2>
<title>Lockout (<literal>lockout</literal>)</title>
<para>
Event triggered for locking out a bad web spider or misbehaving
client (see &conf-RobotLimit;). The subroutine is called without
parameters and is expected to perform all the necessary custom
steps. It should exit with an appropriate return value to signal
how the rest of the process should be handled.
</para>
<para>
A &glos-true; return value indicates that no more handling is
needed. A &glos-false; value indicates that &IC; should continue
and execute the default, built-in action lockout action, which
is specified by the &conf-LockoutCommand; config directive.
<!-- TODO : Where do you read IP or something from ? -->
</para>
</refsect2>
<refsect2>
<title>Missing page (<literal>missing</literal>)</title>
<para>
Event triggered when a requested &IC; page is missing.
The subroutine is called with the name of the missing page
and is expected to perform all the necessary custom handling.
It should exit with an appropriate return value to signal
how the rest of the process should be handled.
</para><para>
The available events are:

<itemizedlist>
<listitem><para>
<literal>request_init</literal> &mdash;
event triggered on every request, right after catalog
selection and before &glos-session; assignment.
</para></listitem>
<listitem><para>
<literal>admin_init</literal> &mdash;
for users with administrator privileges, event triggered on every
request, after initialization of
embedded Perl objects. This allows &glos-catalog; subroutines to
be specified as request handlers and have properly initialized
&glos-session; variables by the time they run.
</para></listitem>
<listitem><para>
<literal>debug_qualify</literal> &mdash;
event triggered to determine whether &glos-debug; mode should be
enabled for the incoming client connection. Have in mind that simple,
host-based decision can be made by using the &conf-DebugHost;
configuration directive. The <literal>debug_qualify</literal>
specialSub is invoked only if &conf-DebugHost; is either undefined,
or the client host is found in the &conf-DebugHost; list.
See &glos-debug; glossary entry for a complete discussion.
</para></listitem>
<listitem><para>
<literal>flypage</literal> &mdash;
event triggered for determining the result set for the flypage.
<!-- TODO more info -->
</para></listitem>
<listitem><para>
<literal>guess_cc_type</literal> &mdash;
event triggered at the time
of deriving credit card type, &var-MV_CREDIT_CARD_TYPE;.
&IC; already recognizes
major credit card types but local areas might require you to
write custom recognition code.
The subroutine is called with the credit card number.
A &glos-true; return value should contain the recognized credit card
type name.
A &glos-false; value indicates that the number recognition did not
suceed, and that &IC; should proceed with its built-in detection
algorithm.
</para></listitem>
<listitem><para>
<literal>init_session</literal> &mdash;
event triggered at new &glos-session; creation time.
The subroutine is called with the pointer to the newly created
&glos-session; variables space. Subroutine return value is not used.
</para></listitem>
<listitem><para>
<literal>lockout</literal> &mdash;
event triggered for locking out a bad web spider or misbehaving
client (see &conf-RobotLimit;). The subroutine is called without
parameters and is expected to perform all the necessary custom
steps. It should exit with an appropriate return value to signal
how the rest of the process should be handled.
A &glos-true; return value indicates that no more handling is
needed. A &glos-false; value indicates that &IC; should continue
and execute the default, built-in action lockout action, which
is specified by the &conf-LockoutCommand; config directive.
<!-- TODO : Where do you read IP or something from ? -->
</para></listitem>
<listitem><para>
<literal>missing</literal> &mdash;
event triggered when a requested &IC; page is missing.
The subroutine is called with the name of the missing page
and is expected to perform all the necessary custom handling.
It should exit with an appropriate return value to signal
how the rest of the process should be handled.
A &glos-true; return
value will indicates that all actions (including the response to the client)
have been performed by your function and no more handling is needed.
You can also return an array, (1, <replaceable>PAGENAME</replaceable>), where
<replaceable>PAGENAME</replaceable> is the page to be displayed to the user.
A &glos-false; return value indicates that &IC; should continue
and execute the default, built-in action, which
is displaying a page specified by "&conf-SpecialPage;
<literal>missing</literal>".
</para></listitem>
<listitem><para>
<literal>shipping_callout</literal> &mdash;
event is triggered after shipping calculation, but before result is
A &glos-true; return
value will indicates that all actions (including the response to the client)
have been performed by your function and no more handling is needed.
You can also return an array, (1, <replaceable>PAGENAME</replaceable>), where
<replaceable>PAGENAME</replaceable> is the page to be displayed to the user.
</para><para>
A &glos-false; return value indicates that &IC; should continue
and execute the default, built-in action, which
is displaying a page specified by "&conf-SpecialPage;
<literal>missing</literal>".
</para>
</refsect2>
<refsect2>
<title>Shipping calculation (<literal>shipping_callout</literal>)</title>
<para>
Event is triggered after shipping calculation, but before result is
formatted and returned.

</para>
<para>
It's useful for
the type of customization that would require modifying too many shipping
table entries or using entirely custom shipping code, because it allows
you to build on the powerful shipping features interchange already has.
</para></listitem>
<listitem><para>
<literal>weight_callout</literal> &mdash;
event is triggered after weight is processed for shipping calculation.

</para>
</refsect2>
<refsect2>
<title>Weight calculation (<literal>weight_callout</literal>)</title>
<para>
Event is triggered after weight is processed for shipping calculation.
</para>
The subroutine is called with the weight as parameter and expects the modified weight as return value.

It does not affect other calculations, such as done by the <tag>weight</tag> usertag.
</para></listitem>
</itemizedlist>
<para>
It does not affect other calculations, such as done by the <tag>weight</tag>
usertag.
</para>
</refsect2>
__END__

__NAME__ notes
Expand Down

0 comments on commit ca7741e

Please sign in to comment.