The Labs.Com Programmer HTML ProgrammerHTML Handler

The Labs - Design & Functionality For The Net

ProgrammerHTML: ModPerl Handler

Here the setup instructions to use ProgrammerHTML as content-handler with Apache-HTTPD and ModPerl

1. Setup
2. Details
3. Examples
4. Considerations

Apache Module

Unpack and install ProgrammerHTML.pm:  tar zxf ProgrammerHTML.tar.gz   cd ProgrammerHTML   perl Makefile.PL   make   make install

httpd.conf

<VirtualHost test>       ServerAdmin webmaster@host.some_domain.com       DocumentRoot /home/www/yourpath/       <Location />           SetHandler perl-script           PerlHandler Apache::ProgrammerHTML           # PerlSetVar PHTMLHeader off           # PerlSetVar PHTMLHeader text/html           # PerlSetVar PHTMLHeader whatever           PerlSendHeader On           Options -Indexes       </Location>       ServerName test.org       ErrorLog logs/test-error_log       CustomLog logs/test-access_log common   </VirtualHost>  PerlSetVar PHTMLHeader you can define the Content-type, by default 'text/html' is set. PerlSetVar PHTMLHeader off within the file (e.g. .html) you define the actual content-type: out "Content-type: text/html\n\n";. This is specially interesting when you want create dynamic GIF via ProgrammerHTML (e.g. using Perl, or PostScript). PerlSetVar PHTMLHeader text/html you define the direct content-type. PerlSetVar PHTMLHeader whatever ... If a file (.html) is executable (chmod +x file), then the file provides its own content-type; this simplifies to port CGIs which deliver non-html content. Hints: to avoid unneccesary load you can disable the handler for directories which do not contain any phtml-files (.html):  <Location /css>       SetHandler default-handler   </Location>   <Location /images>       SetHandler default-handler   </Location>   etc.

phtmlrc

Define all new tags in phtmlrc (it will be reloaded whenever it changes). Advise: Do not define new tags with .html files, only in phtmlrc

ProgrammerHTML Handler 2. Details

This usage is fairly new, and under heavy development, so things might change again.

• %ENV variables are available
• %arg variables contain tag parameters
• $arg{body} contains the body string between start- and end-tag
• %in contains possible CGI parameters
• out() should be used for output (not print)
• phtmlrc in DocumentRoot is (re)loaded at start, or when it is changed (no need to restart httpd)
• structure-file is not yet supported

So, if you are experienced using phtml as preprocessor you will appreciate it as content-handler.

Note: In def-tag language=modperl is considered as default when running as content-handler. When used as preprocessor then language=perl unless overridden.

ProgrammerHTML Handler 3. Examples

Here some examples for new tags (for phtmlrc):

Inline Perl

<def name=perl plugin=inline>   eval($arg{body});   </def>  Simple and powerful :-)  <perl>   # here comes your code   </perl>

Script

The script tag is already existant, yet with ProgrammerHTML you can extend it (override):  <def name=script plugin=inline>   if(lc $arg{language} eq 'perl') {      eval($arg{body}); # execute it   } elsif(lc $arg{language} eq 'javascript') {      out "<script language=javascript>\n";      out $arg{body};   # (some) browsers understand javascript      out "</script>\n";   } elsif(lc $arg{language} eq 'c') {      # ...   } elsif(lc $arg{language} eq 'postscript') {      # run ghostscript to render gif ...      # ...   }   </def>  So, whenever <script language=some-language> appears, ProgrammerHTML takes over the control (when you use it as content-handler), and you simply can embedd everykind of language you like:  <script language=perl>   # your perl stuff   </script>      <script language=javascript>   // your javascript code here   </script>      <script language=postscript>   % here your postscript code   </script>      <script language=pascript>   # here your picart-script   </script>      etc.  We later provide an enriched <script> tag here (as phtmlrc-extension).

ProgrammerHTML Handler 4. Considerations

ProgrammerHTML pages with mod_perl aren't that fast, remember the page is parsed fully: aprx. 10-20KB/s on an Athlon 700. This means, large text-files should not be processed as .html files, but rather pulled out of a database.

In general, keep those .html files as small as possible (e.g. under 10KB); the resulting page seen by the user doesn't matter of 10KB or 1MB. Remove any redundancy and structure things well. The shorter the .html files are, the faster and efficient is your overall design.

General advise: Keep the .html which are parsed & interpreted by ProgrammerHTML small as possible.

Consider InlinePerlPages (IPP), a lightweight embedded-perl, which parses much faster and provides inline perl in .html-pages, yet you don't have dedicated tags like with ProgrammerHTML.

                                                                                                                                   

The DEF Tag

Programmer HTML

Cookbook