view release on metacpan or  search on metacpan

Embperl.pod  view on Meta::CPAN

the result in an array.  You may provide as many columns as you need.
It is also possible to call a 'fetch' subroutine in each table row.


=item B<DIR>, B<MENU>, B<OL>, B<UL>, B<DL>, B<SELECT>, B</DIR>, B</MENU>,
B</OL>, B</UL>, B</DL>, B</SELECT>

Lists and dropdowns or list boxes are treated exactly as one-
dimensional tables.  Only L<"$row">, L<"$maxrow">, L<"$col">, L<"$maxcol"> and L<"$tabmode">
are honored.  $col and $maxcol are ignored.  See eg/x/lists.htm for an
example.

=item B<OPTION>

Embperl checks if there is a value from the form data for a specific
option in a menu.  If so, this option will be pre-selected.

Example:

<FORM METHOD="POST">
  <P>Select Tag</P>

  If you request this document with list.htm?SEL1=x
  you can specify that the element which has a value
  of x is initially selected

  <P><SELECT NAME="SEL1">
     <OPTION VALUE="[+ $v[$row] +]">
        [+ $k[$row] +]
     </OPTION>
  </SELECT></P>
</FORM>


=item B<INPUT>

The INPUT tag interacts with the hashes C<%idat> and C<%fdat>.  If the
input tag has no value and a key exists with the same text as the
NAME attribute of the input tag, Embperl will generate a VALUE
attribute with the corresponding value of the hash key.
All values of <INPUT> tags are stored in the hash C<%idat>, with NAME
as the hash key and VALUE as the hash value.  Special processing is
done for TYPE=RADIO and TYPE=CHECKBOX.  If the VALUE attribute
contains the same text as the value of the hash the CHECKED attribute
is inserted, else it is removed.

So, if you specify, as the ACTION URL,
the file which contains the form itself, the form will be redisplayed
with same values as entered the first time. (See eg/x/neu.htm for an
example.)

=item B<TEXTAREA>, B</TEXTAREA>

The C<TEXTAREA> tag is treated exactly like other input fields.


=item B<META HTTP-EQUIV=>

<meta http-equiv= ... > will over-ride the corresponding http header.
This keeps Netscape from asking the user to reload the document
when the content-type differs between the http header and the
meta http-equiv.

This can also be used to set http headers. When running under mod_perl
http-headers can also be set by the function B<header_out>

    Example of how to set a http header:

    <META HTTP-EQUIV="Language" CONTENT="DE">

    This is the same as using the Apache function

    [- $req_rec -> header_out("Language" => "DE"); -]


=item B<A>, B<EMBED>, B<IMG>, B<IFRAME>, B<FRAME>, B<LAYER>

The output of perl blocks inside the C<HREF> attribute of the C<A> Tags and the
C<SRC> attribute of the other Tags are URL escaped instead of HTML escaped.
(see also L<$escmode>). Also, when inside such a URL, I<Embperl> expands array and hash references
to URL parameter syntax. Example:

  [-
  $A = { A => 1, B => 2 } ;  # Hashreference
  @A = (X, 9, Y, 8, Z, 7)
  -]

  <A HREF="http://localhost/tests?[+ $A  +]">  
  <A HREF="http://localhost/tests?[+ \@A +]">

is expanded by I<Embperl> to

  <A HREF="http://localhost/tests?A=1&amp;B=2">
  <A HREF="http://localhost/tests?X=9&amp;Y=8&Z=7">

=back


=head1 Variable scope and cleanup

The scope of a variable declared with B<my> or B<local> ends at the
end of the enclosing [+/- ... -/+] block; the [+/- ... -/+] blocks act
much like Perl's { ... } in that regard.

Global variables (everything not declared with B<my> or B<local>) will
be undef'ed at the end of each request, so you don't need to worry
about any old variables laying around and causing suspicious results.
This is only done for variables in the package the code is eval'ed in --
every variable that does not have an explicit package name.  All
variables with an explicit package name (i.e., in modules you use)
will stay valid until the httpd child process dies.  Embperl will
change the current package to a unique name for every document, so the
influence between different documents is kept to a minimum.  You can
set the name of the package with B<EMBPERL_PACKAGE>. (See also 
L<"(Safe-)Namespaces and opcode restrictions">.)

Since a CGI script is always a process of its own, you don't need to
worry about that when you use Embperl as a CGI script.

If you need to declare variables which need to live longer than just one 
HTTP request (for example, a database handle), you must either put it's

Embperl.pod  view on Meta::CPAN

    # and gettext is defined as
    sub gettext 
	{
	my ($key) = @_ ;

	return "translated text" ;
	}


	

    1 ;


Just load this package and set EMBPERL_APP_HANDLER_CLASS to My::App, then 
Embperl will call the init method on the start of the request.

If you are using Embperl::Object, you may instead save it as a file in your
document hiearchie make the filename know to Embperl::Object with the 
EMBPERL_OBJECT_APP directive and Embperl::Object will retrieve the correct
application file, just in the same way it retrieves other files.

NOTE: When using with Embperl::Object, don't make a package declaration at
the top of your application object, Embperl::Object assign it's own namespace
to the application object.

In case you need to retrieve a text inside your Perl code, you can do this
with $r -> gettext('bar')

=head1 Encoding/UTF-8

Requires Embperl 2.1.0 and up.

I<Embperl> tries to do the right thing to handle ISO-8859-1 and UTF-8
out of the box. There are three places where encoding comes into places:

=over 4

=item Posted form data

=item Output escaping

=item Source code

=back

While the first two things are handled by Embperl itself, the third item is
currently left to handle by Perl.

Perl carries for each string value a flag that tells if the string
is UTF-8 or not. Embperl uses this flag.

Posted form data is examined. If a string contains valid UTF-8 
characters Perl's internal UTF-8 flag is set. You can disable
setting the UTF-8 flag by setting C<optFormDataNoUtf8> in C<EMBPERL_OPTIONS>.

Output escaping is done based on the UTF-8 flag. In case the UTF-8
flags is set characters above 127 are not escaped. To get the
correct appearance in your browser you also have to specify the
encoding as UTF-8 in your content-type http header.

If the UTF-8 flag is not set the output escaping is done based on the
setting of C<EMBPERL_OUTPUT_ESC_CHARSET>, which defaults to
ISO-8859-1 (latin1). ISO-8859-2 (latin2) is also selectable.

If you wish to have your Perl source code in UTF-8, you have to
add a C<use utf8;> at the top of each page.

Please note that not all modules sets Perl's internal UTF-8 flag
correctly. At the time of this writing for example
DBI and Net::LDAP does not set this flag. You have to correct
it manualy, for example by using C<Encode::_utf8_on>.
 


=head1 Error trapping

When an error occurs inside an Embperl page, Embperl will display an error page,
containing the error message.

Sometimes you want to have a different behaviour. One possibility is to let
Apache display a custom error page (of course only when you run under mod_perl).

To get this working you need to set the option C<optReturnError> (262144)
in your httpd.conf in the C<EMBPERL_OPTIONS> directive.

With this option set, Embperl sends no output in case of an error.
It returns the error back to Apache or the calling program. When running
under mod_perl this gives you the chance to use the Apache I<ErrorDocument>
directive to show a custom error-document. Inside the ErrorDocument
you can retrieve the error messages with

  $errors = $req_rec -> prev -> pnotes('EMBPERL_ERRORS') ;

where C<$errors> is a array reference.

If you want to trap exceptions in a Embperl document, that you call via Execute,
you can do this by passing an array to Execute, which receives all error/warning 
messages and/or all error objects.

    [-
    Execute ({inputfile => 'foo.epl', errors => \@errors}) ;
    -]
    
    [$if @errors$]
        The following errors had occurred:<br>
        [$foreach $err (@errors)$]
            [+ $err +]<br>         
        [$endforeach$]
    [$endif$]


In case you call C<die> inside the executed page and pass an object (or a reference) 
to C<die> instead of a string this will also show up in @errors. The last object 
passed to C<die> is also available via C<$epreq -> errobj>.

C<$epreq -> error> can be used to test if an error occurred so far during the
current request. You can also set C<$epreq -> error> to false to reset Embperl's
internal error condition.