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

Building

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 PerlModule or in a PerlScript

make test fails

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:

make clean perl Makefile.PL

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

and then

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)

Programming Embperl

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 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.

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

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

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)

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.

Using Embperl

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.

8 POD Errors

The following errors were encountered while parsing the POD:

Around line 24:

'=item' outside of any '=over'

Around line 33:

Non-ASCII character seen before =encoding in ' #STATIC_EXTS'. Assuming ISO8859-1

Around line 99:

You forgot a '=back' before '=head1'

Around line 101:

'=item' outside of any '=over'

Around line 132:

You forgot a '=back' before '=head1'

Around line 134:

'=item' outside of any '=over'

Around line 285:

You forgot a '=back' before '=head1'

Around line 287:

'=item' outside of any '=over'

=over without closing =back