Object(3pm)

✨ Object(3pm) ✨

okay bestie, we're doing Embperl::Object today, and honestly? it's giving architect. this is a User Contributed Perl Documentation page, and it's about building whole websites out of reusable components and objects. no cap. 🫶

---

💖 NAME 💖

Embperl::Object — Extents Embperl for building whole website with reusable components and objects

yes "Extents" is literally what it says. we don't question the ancients. 💀

---

🎀 SYNOPSIS 🎀

<Location /foo>
    EMBPERL_APPNAME     unique-name
    EMBPERL_OBJECT_BASE base.htm
    EMBPERL_URIMATCH "\.htm.?|\.epl$"
    SetHandler perl-script
    PerlHandler Embperl::Object
    Options ExecCGI
</Location>

---

🌸 DESCRIPTION 🌸

so basically, Embperl::Object lets you build object-oriented (OO) websites out of HTML components, and the inheritance happens via subdirectories. iconic behaviour. it unlocks elegant architectures and encourages code reuse, which is the whole vibe. 🦋

because of this inheritance thing, you can spec a website-wide "look and feel" in a single HTML file, and that one file becomes the template for every other page on the site. that template can include other modules, and those modules can be overridden in subdirectories — and yes, even the template itself can be overridden. no one is safe. 💅

in a nutshell: Embperl::Object makes designing large websites way more intuitive, letting object-oriented concepts be utilised to the fullest while staying inside the "rapid application development" model of Perl and HTML. main character energy, honestly.

Embperl::Object is basically a mod_perl handler — or it could be invoked offline — and it helps you build a whole page out of smaller parts. here's literally what it does:

when a request comes in, a page whose name is specified by EMBPERL_OBJECT_BASE is searched for in the same directory as the requested page. if the page isn't found, Embperl::Object walks up the directory tree until it finds that page, or until it reaches DocumentRoot or the directory specified by EMBPERL_OBJECT_STOPDIR. she's persistent. 🧚

that page is then called as a frame for building the real page. additionally, Embperl::Object sets the search path to contain all the directories it had to walk before finding that page. if EMBPERL_OBJECT_STOPDIR is set, the path contains all directories up to the one specified in EMBPERL_OBJECT_STOPDIR. ⭐

this frame page can now include other pages using the Embperl::Execute method. and because the search path is set by Embperl::Object, the included files get searched in the directories starting at the directory of the original request, walking up thru the directory that contains the base page. translation: you can keep common files like header, footer, etc. in the base directory and override them as necessary in the subdirectory. obsessed. 🎀

to include the original requested file, you need to call Execute with a '*' as the filename. to call the same file but in an upper directory, you use the special shortcut "../*". cute, right?

additionally, Embperl::Object sets up an inheritance hierarchy for you: the requested page inherits from the base page, and the base page inherits from a class which could be specified by EMBPERL_OBJECT_HANDLER_CLASS — or, if EMBPERL_OBJECT_HANDLER_CLASS is not set, from Embperl::Req. that lets you define methods in the base page and overwrite them as necessary in the original requested files. for this purpose a request object, which is blessed into the package of the requested page, is given as the first parameter to each page (in $_[0]). because this request object is a hashref, you can also use it to store additional data that should be available in all components. Embperl does not use this hash itself, so you are free to store whatever you want. slay. 💜

methods can be ordinary Perl subs (defined with [! sub foo { ... } !]) or Embperl subs (defined with [$sub foo $] .... [$endsub $]).

---

🌈 Runtime configuration 🌈

the runtime config is done by setting environment variables, in your web server's configuration file. basically the configuration is the same as for normal Embperl, and all Embperl configuration directives also apply to Embperl::Object. there are a few additional configuration directives listed below 👇

additionally you have to set the PerlHandler to Embperl::Object when running under mod_perl, or use epocgi.pl instead of embpcgi.pl when running as a CGI script. iykyk. 💅

⭐ EMBPERL_DECLINE ⭐

Perl regex — which files should be ignored by Embperl::Object.

⭐ EMBPERL_FILESMATCH ⭐

Perl regex — which files should be processed by Embperl::Object.

⭐ EMBPERL_OBJECT_BASE ⭐

Name of the base page to search for.

⭐ EMBPERL_OBJECT_STOPDIR ⭐

Directory where to stop searching for the base page.

⭐ EMBPERL_OBJECT_ADDPATH ⭐

Additional directories where to search for pages. directories are separated by ";" (on Unix ":" works also). this path is always appended to the searchpath.

⭐ EMBPERL_OBJECT_FALLBACK ⭐

if the requested file is not found, the file given by EMBPERL_OBJECT_FALLBACK is displayed instead. if EMBPERL_OBJECT_FALLBACK isn't set, a status 404, NOT_FOUND is returned as usual. if the filename given in EMBPERL_OBJECT_FALLBACK doesn't contain a path, it is searched thru the same directories as EMBPERL_OBJECT_BASE. 🍓

⭐ EMBPERL_OBJECT_HANDLER_CLASS ⭐

if you specify this, the template base and the requested page inherit all methods from this class. this class must contain Embperl::Req in its @ISA array. no exceptions bestie.

⭐ EMBPERL_OBJECT_APP ⭐

filename of the application object. the file should contain the Perl code for the application object. there must be no package name given (as the package is set by Embperl::Object), but the @ISA should point to Embperl::App. if set, this file is searched through the same search path as any content file. after a successful load, the init method is called with the Embperl request object as parameter. the init method can change the parameters inside the request object to influence the current request. 👑

the init method should return zero or a valid HTTP status code (e.g. return 302 and set the location header in %http_headers_out).

---

🦋 Execute 🦋

you can use Embperl::Object offline too. do it by calling the function Embperl::Object::Execute. Execute takes a hashref as argument, which can contain the same parameters as the Embperl::Execute function. additionally you may specify the following parameters:

💫 object_base 💫

same as $ENV{EMBPERL_OBJECT_BASE}

💫 object_addpath 💫

same as $ENV{EMBPERL_OBJECT_ADDPATH}

💫 object_stopdir 💫

same as $ENV{EMBPERL_OBJECT_STOPDIR}

💫 object_fallback 💫

same as $ENV{EMBPERL_OBJECT_FALLBACK}

💫 object_handler_class 💫

same as $ENV{EMBPERL_OBJECT_HANDLER_CLASS}

see also the "object" and "isa" parameters in Embperl's Execute function, on how to setup additional inheritance and how to create Perl objects out of Embperl pages. ✨

---

🌸 Basic Example 🌸

with the following setup:

<Location /foo>
   PerlSetEnv EMBPERL_OBJECT_BASE base.htm
   PerlSetEnv EMBPERL_FILESMATCH "\.htm.?|\.epl$"
   SetHandler perl-script
   PerlHandler Embperl::Object
   Options ExecCGI
</Location>

directory layout:

/foo/base.htm
/foo/head.htm
/foo/foot.htm
/foo/page1.htm
/foo/sub/head.htm
/foo/sub/page2.htm

/foo/base.htm:

<html>
<head>
<title>Example</title>
</head>
<body>
[- Execute ('head.htm') -]
[- Execute ('*') -]
[- Execute ('foot.htm') -]
</body>
</html>

/foo/head.htm:

<h1>head from foo</h1>

/foo/sub/head.htm:

<h1>another head from sub</h1>

/foo/foot.htm:

<hr> Footer <hr>

/foo/page1.htm:

PAGE 1

/foo/sub/page2.htm:

PAGE 2

/foo/sub/index.htm:

Index of /foo/sub

if you now request http://host/foo/page1.htm you will get the following page:

<html>
<head>
<title>Example</title>
</head>
<body>
<h1>head from foo</h1>
PAGE 1
<hr> Footer <hr>
</body>
</html>

if you now request http://host/foo/sub/page2.htm you will get the following page:

<html>
<head>
<title>Example</title>
</head>
<body>
<h1>another head from sub</h1>
PAGE 2
<hr> Footer <hr>
</body>
</html>

if you now request http://host/foo/sub/ you will get the following page:

<html>
<head>
<title>Example</title>
</head>
<body>
<h1>another head from sub</h1>
Index of /foo/sub
<hr> Footer <hr>
</body>
</html>

see how the sub one just took over? that's inheritance doing its thing. 💅

---

🎀 Example for using method calls 🎀

(everything not given here is the same as in the example above)

/foo/base.htm:

[!

sub new
   {
   my $self = shift ;

   # here we attach some data to the request object
   $self -> {fontsize} = 3 ;
   }

# Here we give a default title
sub title { 'Title not given' } ;

!]

[-

# get the request object of the current request
$req = shift ;

# here we call the method new
$req -> new ;

-]

<html>
<head>
<title>[+ $req -> title +]</title>
</head>
<body>
[- Execute ('head.htm') -]
[- Execute ('*') -]
[- Execute ('foot.htm') -]
</body>
</html>

/foo/head.htm:

[#
   here we use the fontsize
   Note that
     $foo = $_[0]
   is the same as writing
     $foo = shift
#]

<font size=[+ $_[0] -> {fontsize} +]>header</font>

/foo/sub/page2.htm:

[!

sub new
   {
   my $self = shift ;

   # here we overwrite the new method form base.htm
   $self -> {fontsize} = 5 ;
   }

# Here we overwrite the default title
sub title { 'Title form page 2' } ;

!]

PAGE 2

---

💜 Author 💜

G. Richter (richter at embperl dot org)

---

⭐ See Also ⭐

perl(1), Embperl, mod_perl, Apache httpd

---

and that's the whole page bestie!! 🫶 this was perl v5.34.0, dated 2022-02-06, and yes it's the Object(3pm) page — go build something iconic with it. bye!! 💖✨🎀🦋