\chapter{Site Object API}
\label{chap:site}

Gantry.pm and its engines provide a rich API client apps can rely on.
This chapter provides highlights of the API.  Full details are left
to Gantry.pm and the engines themselves.

After the API section, is a short section explaining the basic
requirements for writing your own engine.  As bonus, there is also a
section on using and writing template engines (which are much simpler).

\section{The API}

Here is a table of many useful methods you can call on your site object.
Keep in mind that these are only highlights of the most important methods.
Full details are reserved to the docs within Gantry.pm and each engine.
Look for the engines in the Gantry::Engine:: namespace.

Note that most methods do not receive arguments beyond the invocant.

\begin{tabular}{l|l|l}
General Methods    & Receives & Returns \\
\hline
\verb+apache_param_hash+ & & Returns form param hashes                  \\
\verb+base_server+       & & host name of server                        \\
\verb+current_url+       & & Full url of current page including http:   \\
\verb+dispatch_location+ & & concatenates the current uri and location  \\
\verb+fish_config+       & param name & value of requested config param \\
\verb+get_cookies+       & optional name & get one or all cookies (hashref) \\
\verb+r+                 & & Apache request object \verb+mod_perl+ only \\
\verb+set_cookies+       & options & set one or more cookies, see docs  \\
\hline
Disk Path Methods    & & Returns \\
\hline
\verb+root+      & & absolute disk path to templates \\
\verb+css_root+  & & absolute disk path to css files \\
\verb+img_root+  & & absolute disk path to images    \\
\hline
URL Path Methods    & & Returns \\
\hline
\verb+app_rootp+ & & URL path from DocumentRoot to app's base location \\
\verb+css_rootp+ & & URL path from DocumentRoot to style sheets        \\
\verb+img_rootp+ & & URL path from DocumentRoot to images              \\
\verb+web_rootp+ & & URL path from DocumentRoot to app's web content   \\
\hline
Template Control Methods    & & Returns \\
\hline
\verb+template+          & & template file for current page usually a setter \\
\verb+template_default+  & & default if no template is defined               \\
\verb+template_wrapper+  & & TT WRAPPER                                      \\
\hline
Apache Request Methods    & & Returns \\
\hline
\verb+uri+            & & works like calling uri on the request object      \\
\verb+location+       & & works like calling location on the request object \\
\verb+path_info+      & & works like calling \verb+path_info+ on the        \\
                      & & request object                                    \\
\verb+content_type+   & & works like calling uri on the request object      \\
\verb+content_length+ & & works like calling uri on the request object      \\
\end{tabular}

Note that engines may choose to export additional methods if they choose, but
callers using them risk incompatability by using them.

Remember that all the engines provide all the methods above.  So, even
in CGI you can call methods like \verb+apache_params_hash+.  The CGI
engine spoofs the \verb+mod_perl+ behavior.

\section{Implementing an Engine}

Gantry engines are mixins which provide a bridge between the rather abstract
way Gantry handles requests and the particulars of your server.  Currently
Gantry ships with engines for \verb+mod_perl+ 1 or 2 and CGI.  Though somewhat
tedious, it is not particularly difficult to implement your own engine.
This section explains how.

The namespace for engines is prescribed.  It must be Gantry::Engine::.
This is because engines are loaded by the import method of Gantry.pm.  It
looks for them in only one namespace.  While Gantry could look elsewhere,
sticking to one namespace makes the modules' purpose obvious.

Fundamentally, engines are mixins.  This means they must export methods into
the user's namespace.  Since Gantry.pm is the user of the modules, their
methods are put into the site object's package.  This allows everyone
to use them: Gantry.pm itself, its helpers, and app specific modules.

Thus, the basic form of an engine is like this:

\begin{verbatim}
package Gantry::Engine::YourEngine;
use strict;

use base 'Exporter';

our @EXPORT = qw(
    # mixin methods here
);
\end{verbatim}

A list of the methods and what they must do is in the first section of
this chapter.  But, there are still a few other things that you will need
in your preamble.  Chief among these is:

\begin{verbatim}
use Gantry::Utils::DBConnHelper::YourEngine;
\end{verbatim}

This implies that your have implemented
Gantry::Utils::DBConnHelper::YourEngine, which must provide database
connection information by fishing it out of the configuration parameters.

There are six methods in any connection helper.  Three are for auth
connections, three are for regular connections.  For example, this allows
apps to look up auth in a central database while having their own app
specific database for other tables.  Normally, helpers return the regular
information if no auth information is available.

As a courtesy, helpers should try to fish the connection information via
Gantry::Conf, before falling back on other approaches.  If you don't do
that, Gantry::Conf users will not be pleased.

Here are the methods in tabular form:

\begin{tabular}{l|l|l}
Method & Receives & Returns \\
\hline
\verb+get_dbh+            &       & the regular dbh                \\
\verb+set_dbh+            & a dbh &                                \\
\verb+get_conn_info+      &       & a hash ref with these keys:    \\
                          &       & \verb+dbconn+, \verb+dbuser+,
                                    \verb+dbpass+                  \\
\hline
\verb+get_auth_dbh+       &       & the auth dbh                   \\
\verb+set_auth_dbh+       & a dbh &                                \\
\verb+get_auth_conn_info+ &       & a hash ref with these keys:    \\
                          &       & \verb+auth_dbconn+,
                                    \verb+auth_dbuser+,
                                    \verb+auth_dbpass+             \\
\end{tabular}

Some helpers choose to provide set accessors for their connection info.
This is particularly helpful for scripts which might want to just plug
in data from the command line.

You probably also need to include things morally equivalent to
Apache::Constants and Apache::Request.

Please also use Gantry::Conf.  Though not required, it is nice to be
able to seemlessly deploy apps via Gantry::Conf, but this requires all
engines to use it as their first choice for obtaining conf info.

\section{Template Engine API}

There are four methods in the Gantry template API as you can see from this
table:

\begin{tabular}{l|l}
Method & Purpose \\
\hline
\verb+do_action+       & called on to perform a \verb+do_+ method and store  \\
                       & its returned output                                 \\
\verb+do_error+        & often does nothing, but could log                   \\
\verb+do_process+      & using only the Gantry site object, returns formated \\
                       & output                                              \\
\verb+template_engine+ & returns the name of the template package            \\
\end{tabular}

You need to implement \verb+do_error+, but you don't need to do anything in
it.  Gantry will log errors through the web server in whatever is the
normal plan.  You could implement your own template engine, based on an
existing one, just for the purpose of diverting logging information in
this method.

When Gantry's single handler figures out what \verb+do_*+ method to call, 
it actually calls \verb+do_process+, which is provided by the template
engine.  Normally, \verb+do_process+ calls the action method and stores
the result in the \verb+stash+.

After the \verb+do_*+ method returns, if there were no errors, Gantry's
handler calls \verb+do_process+ on the template engine.  It is responsible
for feeding the data, collected from the \verb+do_*+ method during
\verb+do_action+, to the template engine.  The returned result needs to
be presentable to the browser.

Implementing a template engine is as easy as implementing the methods just
described and exporting those methods by default from a module in the
Gantry::Template::* namespace.

\subsection*{Unorthodox Template Processing}

Most Gantry \verb+do_*+ methods set the \verb+template+ attribute
on the Gantry site object and return a data structure which that
template understands.  Sometimes that does not provide enough flexibility.
Suppose, for example, that you need to return a JSON response to an
AJAX request.  You need to turn off templating temporarily.  Here's how.

In you controller, you may turn off your templating engine by setting
the \verb+template_disable+ attribute to a true value:

\begin{verbatim}
    $self->template_disable( 1 );
\end{verbatim}

Then whatever you return will be given directly to the browser.

But, what if you want to form part of the AJAX response with templates?
Or, perhaps you want to build template data with templates (like JSON
constructing templates).  At any point in a \verb+do_*+ method, you may
call \verb+do_process+.  If you don't want your return value to be
sent through the template engine after you return it, set the
\verb+template_disable+ attribute as shown above.  But, don't set
it until after you use \verb+do_process+.  That method always bails out
if the flag is set.  In that case, it just returns what ever is in the
\verb+stash->controller->data+ attribute of the site object.  (In fact,
it is that bail out you are triggering whenever you set the
\verb+template_disable+ flag.)

In this chapter we have seen some highlights of the site object API
including the template API, which is mixed in to the site.  My emphasis
here is on common features rather than completeness.  Gantry.pm, the
engines, and the template engines have complete docs.  Refer to those
for more exotic methods.
