.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "IntroEmbperlObject 3pm"
.TH IntroEmbperlObject 3pm "2020-11-09" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Embperl::IntroEmbperlObject \- Introduction to EmbperlObject
.SH "Contents"
.IX Header "Contents"
.IP "Introduction" 4
.IX Item "Introduction"
.PD 0
.IP "Getting Started" 4
.IX Item "Getting Started"
.IP "Hello World" 4
.IX Item "Hello World"
.IP "Website-Global Variables" 4
.IX Item "Website-Global Variables"
.IP "Modular Files" 4
.IX Item "Modular Files"
.IP "Modular File Inheritance" 4
.IX Item "Modular File Inheritance"
.IP "Subroutines in EmbperlObject" 4
.IX Item "Subroutines in EmbperlObject"
.IP "Conclusions" 4
.IX Item "Conclusions"
.PD
.SH "Introduction"
.IX Header "Introduction"
This tutorial is intended as a complement to the Embperl
documentation, not a replacement. We assume a basic familiarity with
Apache, mod_perl, and Perl, and the Embperl documentation. No prior
experience with EmbperlObject is assumed. The real purpose here is to
give a clearer idea of how EmbperlObject can help you to build large
websites. We give example code which could serve as a starting
template for your own projects, and hints about best practices which
have come out of real experience using the toolkit. As always, there
is more than one way to do it!
.PP
Since EmbperlObject is an evolving tool, it is likely that these
design patterns will evolve over time, and it is recommended that the
reader check back on the Embperl website for new versions from time to
time.
.SS "Motivation: Constructing Modular Websites"
.IX Subsection "Motivation: Constructing Modular Websites"
Embperl is a tool which allows you to embed Perl code in your \s-1HTML\s0
documents. As such, it could by itself handle just about everything
you need to do with your website. So what is the point of
EmbperlObject? What does it give us that we don't already get with
basic Embperl?
.PP
As often seems to be the case with Perl, the answer has to do with
laziness. We would all like the task of building websites to be as
simple as possible. Anyone who has had to build a non-trivial site
using pure \s-1HTML\s0 will have quickly experienced the irritation of having
to copy-and-paste common code between documents \- stuff like
navigation bars and table formats. We have probably all wished for an
\&\*(L"include\*(R" \s-1HTML\s0 tag. EmbperlObject goes a long way toward solving this
problem, without requiring the developer to resort to a lot of
customized Perl code.
.PP
In a nutshell, EmbperlObject extends Embperl by enabling the
construction of websites in a modular, or object-oriented, fashion. I
am using the term \*(L"object-oriented\*(R" (\s-1OO\s0) loosely here in the context
of inheritance and overloading, but you don't really need to know
anything about the \s-1OO\s0 paradigm to benefit from EmbperlObject. As you
will see from this short tutorial, it is possible to benefit from
using EmbperlObject with even a minimal knowledge of Perl. With just a
little instruction, in fact, pure \s-1HTML\s0 coders could use it to improve
their website architecture. Having said that, however, EmbperlObject
also provides for more advanced \s-1OO\s0 functionality, as we'll see later.
.SH "Getting Started"
.IX Header "Getting Started"
We'll assume here that you've successfully installed the latest
Apache, mod_perl and Embperl on your system. That should all be
relatively painless \- problems normally occur when mixing older
versions of one tool with later versions of another. If you can, try
to download the latest versions of everything.
.PP
Having done all that, you might want to get going with configuring a
website. The first thing you need to do is set up the Apache config
file, usually called \fIhttpd.conf\fR.
.SS "Configuring \fIhttpd.conf\fP"
.IX Subsection "Configuring httpd.conf"
The following is an example configuration for a single virtual host to
use EmbperlObject. There are, as usual, different ways to do this; but
if you are starting from scratch then it may be useful as a
template. It works with the later versions of Apache (1.3.6 and
up). Obviously, substitute your own \s-1IP\s0 address and domain name.
.PP
.Vb 1
\& NameVirtualHost 10.1.1.3:80
\&
\&
\& [\- Execute (\*(Aq*\*(Aq) \-] \& \& .Ve .PP \&\fI/hello.html\fR .PP .Vb 1 \& Hello world! .Ve .PP Now, if the file http://www.yoursite.com/hello.html is requested, then \&\fIbase.epl\fR is what will actually get executed initially. So where does the file \fIhello.html\fR get into the picture? Well, the key is the \&'*' parameter in the call to \fBExecute()\fR. '*' is a special filename, only used in \fIbase.epl\fR. It means, literally, \*(L"the filename which was actually requested\*(R". .PP What you will see if you try this example is something like this: .PP .Vb 1 \& Joe\*(Aqs Website \& \& Hello world! .Ve .PP As you can see here, the text \*(L"Joe's Website\*(R" is from \fIbase.epl\fR and the \*(L"Hello world!\*(R" is from \fIhello.html\fR. .PP This architecture also means that only \fIbase.epl\fR has to have the boilerplate code which every \s-1HTML\s0 file normally needs to contain \- namely the <\s-1HTML\s0> <\s-1BODY\s0>,