view release on metacpan or  search on metacpan

lib/CIPP/Manual.pm  view on Meta::CPAN

=head2 Example

We specify an interface for two scalars and an array.

  <?INTERFACE INPUT="$firstname, $lastname"
              OPTIONAL="@id">

A HTML form which adresses this CGI program may look like this (assuming we are in a CGI::CIPP or Apache::CIPP environment).

  <?VAR MY NAME="@id" NOQUOTE>(1,2,3,4)<?/VAR>

  <?FORM ACTION="/user/save.cgi">
    <?HIDDENFIELDS PARAMS="@id">
    <P>firstname:
    <?INPUT TYPE=TEXT NAME=firstname>
    <P>lastname:
    <?INPUT TYPE=TEXT NAME=lastname>
  <?/FORM>

=head1 COMMAND <?L>

=head2 Type

Miscellaneous

=head2 Syntax

 <?l [key="value" ...] >
   Message to be translated with Locale::TextDomain,
   including placehoders: {key}
 <?/l>

=head2 IMPORTANT NOTE

This syntax is functionally functional, but currently implemented without any active translation. The message text is passed through as-is, including placeholder substitution. Translation functionality will follow, inlcuding the neccessary command li...

=head2 Description

This command uses (resp. will use) the Locale::TextDomain module to translate the text in the enclosed block, including the substitution of placeholders with actual values.

Placeholder names are written in curly brackets. The actual values are passed as options to the <?L> command. Note that the placeholder names are treated case sensitive.

You may use this command in HTML and PERL context as well. In HTML context the translated text is printed into the HTML page. In PERL context a Perl expression is generated which can be used in any expression context, e.g. a simple variable assignmen...

=head2 Examples

 Print a translated "Hello World":
 
 <?l>Hello World<?/l>

 Placeholder example:

 <?l cnt="$age">You are {age} year(s) old.<?/l>

 Use in Perl Context
 
 <?PERL>
   #-- Simple variable assignment
   my $translated = <?l age="42">You You are {age} year(s) old.<?/l>;

   #-- Assign a bold message to a variable
   my $translated_bold =
   	"<b>".
	<?l age="42">You are {age} year(s) old.<?/l>.
	"</b>";

   #-- Throw a translated error message
   die <?l>A fatal error occured<?/l>;
 <?/PERL>

=head1 COMMAND <?LOG>

=head2 Type

Exception Handling

=head2 Syntax

 <?LOG MSG=error_message
       [ TYPE=type_of_message ]
       [ FILENAME=special_logfile ]
       [ THROW=exception ] >

=head2 Description

The <?LOG> command adds a line to the project specific logfile, if no other filename is specified. In new.spirit environments the default filename of the logfile is prod/log/cipp.log. In CGI::CIPP and Apache::CIPP environments messages are written to...

Log file entries contain a timestamp, client IP adress, a message type and the message itself.

=head2 Parameter

=over 8

=item B<MSG>

This is the message.

=item B<TYPE>

You can use the TYPE parameter to speficy a special type for this message. This is simply a string. You can use this feature to ease logfile analysis.

=item B<FILENAME>

If you want to add this message to a special logfile you pass the full path of this file with FILENAME.

=item B<THROW>

With this parameter you can provide a user defined exception to be thrown on failure. The default exception thrown by this statement is log.

An exception will be thrown, if the log file is not writable or the path is not reachable.

=back

=head2 Example

If the variable $error is set a simple entry will be added to the default logfile.

  <?IF COND="$error != 0">
    <?LOG MSG="internal error: $error">
  <?/IF>

The error message "error in SQL statement" is added to the special logfile with the path /tmp/my.log. This entry is marked with the special type dberror. If this file is not writable an exception called fileio is thrown.