=head1 FAQ for HTML::Embperl

 Building
    Build a static linked Embperl with mod_perl support

 make test fails
    At loading of Embperl

 Programming Embperl
    Escaping (HTML tags disapear out of Perl code)
    while loops across [- -] segments
    disable escaping
    setting predefined variables
    Using a different character set


 Using Embperl
    Netscape ask to reload the document



=head1 Building

=item B<Build a static linked Embperl with mod_perl support>


1.) Go to your mod_perl directory, change to src/modules/perl

2.) Edit the Makefile

a.) Change the line

 #STATIC_EXTS = Apache Apache::Constants

to

 #STATIC_EXTS = Apache Apache::Constants HTML::Embperl

b.) Search the line 

 OBJS=.... 

add a definition for EPDIR and change the OBJS=... line.

After that it should look like the following:

 EPDIR=/usr/msrc/embperl
 OBJS=$(PERLSRC:.c=.o) $(EPDIR)/Embperl.o $(EPDIR)/epmain.o $(EPDIR)/epio.o $(EPDIR)/epeval.o $(EPDIR)/epcmd.o $(EPDIR)/epchar.o $(EPDIR)/eputil.o

3.) Goto the mod_perl directory and run perl Makefile.PL

4.) Goto the Embperl directory and do
 

 make clean

 perl Makefile.PL

 make

(Compile it with mod_perl support)

5.) Change again to the mod_perl directory and remake your apache by typing

 make

Now you have successfully build a httpd with static linked Embperl (If you stop here 
you have to run a make install in the Embperl directory to finish)

If you like to run the Embperl tests and/or use Embperl in offline/cgi mode, we have to do a trick:

6.) Go again to Embperl directory

7.) Backup the file  test/conf/config.pl

8.) Now again build Embperl but _without_ mod_perl support


 make clean

 perl Makefile.PL

 make

9.) Now restore your saved config.pl to test/conf/config.pl (without this step, only the offline mode would be tested)

10.) run make test for Embperl

11.) make install for Embperl

You should do it in this order, or it may not work.


NOTE: It seems to be necessary to load Embperl at server startup,
either by B<PerlModule> or in a B<PerlScript>



=head1 make test fails

=item B<At loading of Embperl>

 >
 >loading...              Can't load
 >'./blib/arch/auto/HTML/Embperl/Embperl.o' for module HTML::Embperl:
 >can't resolve undefined symbols: Inappropriate file type or format at
 >/usr/local/lib/perl5/i386-bsdos/5.00401/DynaLoader.pm line 155.
 >

Please try:

B<make clean>
B<perl Makefile.PL>

answer B<_no_> to mod_perl support. (This is important!)

and then

B<make test>

 >
 >It tests fine this way...  What's that tell us (since mod_perl compiled
 >and tested cleanly)?
 >

This is problem that your os (for example bsdos) do not resolv unknown symbols which
are defined by the binary, instead in a library. The solution for that problem is to
staticly link Embperl with apache/mod_perl. (See next question how to do this)



=head1 Programming Embperl

=item B<Escaping (HTML tags disapear out of Perl code)>


 >[..]
 >My problem is this:
 >
 >In ASP, I can use HTML within string literals in my code.
 >I don't seem to be able to do that - is that actually the case?
 >If it is, how does one do things such as the example
 >below? Is it just a case of a LOT of square brackets? :)
 
Your HTML literals are delete from the perl strings by Embperl. This is a
wanted feature to work together with WYSIWYG Editor (like MS Frontpage).
Such editors will insert random tags like FONT, COLOR etc. where they
shouldn't apear.
For you there are two solutions:

1.) Get Embperl-0.24 or above and set B<optRawInput>, then no translations of the input
takes place i.e. all your tags will stay as they are

2.) Escape them with a \ (Note when inside a "  " you must use \\, since
perl will remove the first \ e.g. '\<tr>'  or "\\<tr>"

Look also at the code below, where there will be no need for html tag in
perl code


 >[-
 >use DBI;
 >
 >my $dbh =
 >DBI->connect("DBI:mysql:database:localhost","Username","Password") ||
 >die($!);
 >
 >$hstmt = $dbh->prepare("select ID, Heading from Shops order by Heading");
 >$hstmt->execute();
 >$output = "<table border=1>";
 >while(@row = $hstmt->fetchrow_array())
 >{
 >        $output .= "<tr><td>".join("</td><td>",@row)."</td></tr>";
 >}
 >$output .= "</table>";
 >
 >$hstmt->finish();
 >$dbh->disconnect();
 >-]
 >
 >[+ $output +]
 >
 >Produces:
 >9British Museum12Museum of London5National Gallery6National Portrait
 >Gallery4National Postal Museum10National Science Museum7Natural History Museum1Ray's
 >Jazz Shop3Tate Gallery11Victoria &amp; Albert Museum8Virgin Megastore
 >

You can take advantage of Embperl dynamic tables and write it as following:

 [-
 use DBI;

 my $dbh =
 DBI->connect("DBI:mysql:database:localhost","Username","Password") ||
 die($!);
 
 $hstmt = $dbh->prepare("select ID, Heading from Shops order by Heading");
 $hstmt->execute();
 $dat = $hstmt->fetchall_arrayref() ;
 $hstmt->finish();
 $dbh->disconnect();
 -]
 <table border=1>
         <tr><td>[+ $$dat[$row][$col] +]</td></tr>
 </table>


The html code above will display the content of the whole array. It should
be also possible to put the dbi fetch into the dynamic table, but I didn't
try it out yet.


=item B<while loops across [- -] segments>

 >I found that when I try splitting a while() across two [--] segments,
 >it isn't happy, so that isn't the solution.

You can use the [$while$] metacommand for that

=item B<disable escaping>

 >Now '<'s, '>'s '"'s in f.x. $artikel{rubrik} are translated to &lt;, &gt;
 >and so on.
 >
 >Is there an option to avoid this? My toolbox does very often output some
 >html codes (and all my code are 'html aware' now), so it would be nice to
 >be able to turn it on and off.. (or just completely off :-) )

The variable $escmode is what you want.

[- $escmode = 0; -]  will disable the escaping behavior.


EMBPERL_ESCMODE can be used to change the initial value


=item B<setting predefined variables>

  >How can I change the value of $escmode from my Toolbox module?

$HTML::Embperl::escmode = 0 ;

The $escmode of the packages in which your document runs is only an alias
for $HTML::Embperl::escmode (This is true for other predifined variables as
well)



=item B<Using a different character set>


 >I have found that from the ouput of Embperl some characters with ascii
 >value >128 are displayed as question mark "?" by my browser. There are
 >many such characters in czech language so I have unreadable output HTML pages.
 >What can I do?
 

This caused by the translation of charcters to html escapes. Embperl translates
them to escapes which are not understand by the national browser, which displays
a "?" instead, because it uses the wrong character set.

>I have tried to overcome this problem by using [- $escmode = 0; -]
>and it works!

Yes, this will disable escaping of output at all.

If you like to use the escaping feature of Embperl you have to adapt the file
epchar.c to your character set. This file contains three tables:

Char2Html []    Convert characters to html escapes 

Char2Url  []    Convert characters to url escapes (do not change this one) 

Html2Char []    Convert html escapes to characters

You have to change the first and the last.
Please make sure Char2Html contains one entry for every 256 ascii codes in the right order
and Html2Char is sorted by html escape.

If somebody generates new tables for national characters sets, please send a copy to the
author, so it can included it in further versions of Embperl.


=head1 Using Embperl

=item B<Netscape ask to reload the document>

I found

  <META HTTP-EQUIV="content-type" CONTENT="text/html;charset=iso-8859-1">

in your source. I had get into trouble with such a line with netscape
browsers when posting formdata and the dbgEarlyHttpHeader is on.

Netscape seem to have a problem in such a case, because http header is only
content-type text/html, while the META HTTP-EQUIV has an addition charset
specified. My netscape versions, has asked me to reload the page, when they
encounterd such a situation. With dbgEarlyHttpHeader off, Embperl will
automatily setup the http header to the same as the META HTTP-EQUIV.