Apache-PageKit

 view release on metacpan or  search on metacpan

docsrc/reference.xml  view on Meta::CPAN

filename
computeroutput
constant
literal
replaceable
varname

informalexample
programlisting
-->

<chapter><?dbhtml filename="reference.html"?>
<chapterinfo>
<releaseinfo role="meta">
$Id: reference.xml,v 1.68 2004/04/06 09:18:30 borisz Exp $
</releaseinfo>
</chapterinfo>
<title>Reference</title>
 <sect1>
  <title>Configuration Options</title>
  <sect2>
   <title>Global Attributes</title>
   <para>
    These settings are global in the sense that they apply over all servers, views, and pages.
    They are attributes of the &lt;GLOBAL&gt; tag in <filename>Config/Config.xml</filename>.
   </para>
   <variablelist>
    <varlistentry id="config.global.cache_dir">
     <term>cache_dir</term>
     <listitem>
      <para>
       Specifies the directory where the PageKit Template cache files are stored.
       Defaults to <filename>View/pkit_cache</filename>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry id="config.global.cookies_not_set_page">
     <term>cookies_not_set_page</term>
     <listitem>
      <para>
This is the page that gets displayed if the user attempts to log in,
but their cookies are not enabled.  Defaults to <literal><link linkend="config.global.login_page">login_page</link></literal>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="config.global.default_errorstr">
     <term>default_errorstr</term>
     <listitem>
      <para>
        Default errorstr, that PageKit use for <link linkend="pkit.errorstr">PKIT_ERRORSTR</link>,
	<link linkend="model.api.pkit_set_errorspan">pkit_set_errorspan</link> and the obsolete
	<link linkend="model.api.pkit_set_errorfont">pkit_set_errorfont</link>.
      </para>
      <para>
	Defaults to <emphasis>#ff0000</emphasis>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry id="config.global.default_input_charset">
     <term>default_input_charset</term>
     <listitem>
      <para>
        Default charset that PageKit Templates and Model output are encoded in.
	Defaults to
       <emphasis>ISO-8859-1</emphasis>.  PageKit uses this to convert the
        PageKit templates and output from <link linkend="model.api.output_convert">output_convert</link> to UTF-8.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry id="config.global.default_output_charset">
     <term>default_output_charset</term>
     <listitem>
      <para>
        Default charset that PageKit templates compiled to.
	Defaults to
       <emphasis>ISO-8859-1</emphasis>.  This should be the charset that
       supports your <link linkend="config.global.default_input_charset">default_input_charset</link> and has good support among the client's browsers.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry id="config.global.default_lang">
     <term>default_lang</term>
     <listitem>
      <para>
       Default language outputed when no language is specified
       or request language is not available.  Defaults to
       <emphasis>en</emphasis>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry id="config.global.default_page">
     <term>default_page</term>
     <listitem>
      <para>
       Default page user gets when no page is specified.  Defaults to
       <emphasis>index</emphasis>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="config.global.errorspan_begin_tag">
     <term>errorspan_begin_tag</term>
     <listitem>
      <para>
       Specifies the start tag for &lt;PKIT_ERRORSPAN ... &gt; and &lt;PKIT_ERRORFONT ... &gt;.
       Defaults to <emphasis>&lt;font color="&lt;PKIT_ERRORCOLOR&gt;"&gt;</emphasis>.
       <informalexample>
       <programlisting>
	errorspan_begin_tag = "&amp;lt;span class=error&amp;gt;"
        errorspan_end_tag = "&amp;lt;/span&amp;gt;"
       </programlisting>
      </informalexample>
      </para>
      <para>
      See also <literal><link linkend="config.global.errorspan_end_tag">errorspan_end_tag</link></literal>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="config.global.errorspan_end_tag">
     <term>errorspan_end_tag</term>
     <listitem>
      <para>
       Specifies the end tag for &lt;PKIT_ERRORSPAN ... &gt; and &lt;PKIT_ERRORFONT ... &gt;.
       Defaults to <emphasis>&lt;/font&gt;</emphasis>.
      </para>
      <para>
      See also <literal><link linkend="config.global.errorspan_begin_tag">errorspan_begin_tag</link></literal>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry id="config.global.fop_command">
     <term>fop_command</term>
     <listitem>
      <para>
       Command line that should be used to run Apache XML FOP to generate
       PDF output.  PageKit will append FO file and PDF file arguments at end.

docsrc/reference.xml  view on Meta::CPAN

     <term>reload</term>
     <listitem>
      <para>
If set to <emphasis>yes</emphasis>, check for new view, content and config xml files
on each request.  Should be set to <emphasis>no</emphasis> on production servers.
Default is <emphasis>no</emphasis>.
      </para>
      <para>
      If you change this from <emphasis>no</emphasis> to <emphasis>yes</emphasis> it is
      certainly that the server must be restarted to notice the change.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </sect2>
  <sect2>
   <title>User Attributes</title>
   <para>
    These options are like the &lt;GLOBAL&gt; tag. With the difference, that you can store any information here that you like.
    The are located in the &lt;USER&gt; tag of <filename>Config/Config.xml</filename>.
   </para>
   <para>
   You can retrieve this information with the
   <link linkend="model.api.pkit_get_config_attr">pkit_get_config_attr</link> function.
   </para>
  </sect2>
  <sect2>
   <title>View Attributes</title>
   <para>
    These options are local to each view, but are global across servers and pages.  Currently only the output media can be set, but there are plans to have a <literal>parent_view</literal>, so that there can be multiple levels of
derived views.
   </para>
   <variablelist>
    <varlistentry id="config.view.content_type">
     <term>content_type</term>
     <listitem>
      <para>
Sets the content type of the output sent to the client.  
Content types are strings like "text/plain", "text/html" or "application/xml".
This corresponds to the "Content-Type" header in the HTTP protocol. 
The following content types have default views and/or special handing
associated with them:
      </para>
      <informaltable frame="all">
       <tgroup cols="4">
        <tbody>
         <row rowsep="1" role="attrheader">
	  <entry role="th"><para><emphasis role="bold">content_type</emphasis></para></entry>
	  <entry role="th"><para><emphasis role="bold">Description</emphasis></para></entry>
	  <entry role="th"><para><emphasis role="bold">Default Views</emphasis></para></entry>
	  <entry role="th"><para><emphasis role="bold">Special Handing</emphasis></para></entry>
	 </row>
         <row>
	  <entry>text/html</entry>
	  <entry>
 	   HTML output.  This is for traditional screen browsers such as
           Netscape and Internet Explorer.
          </entry>
	  <entry>This is the default content_type for all views except for
             those listed below</entry>
	  <entry>PageKit translates sets the charset in the Content-Type headers and translates the output according
             to the <literal>Accept-Charset</literal> header.</entry>
         </row>
         <row>
	  <entry>application/pdf</entry>
	  <entry>
	   PDF Output, for display in Acrobat Reader.  Uses Apache XML FOP
          </entry>
	  <entry>pdf</entry>
	  <entry>PageKit uses Apache XML FOP to generate the PDF, if
            <link linkend="config.global.fop_command">fop_command</link>
            is set.</entry>
         </row>
         <row>
	  <entry>text/vnd.wap.wml</entry>
	  <entry>
 	   WML output.  This is for WAP handhelds such as Palmpilots
	   and cellphones.
          </entry>
	  <entry>wml</entry>
	  <entry><emphasis>None</emphasis></entry>
         </row>
         <row>
	  <entry>application/xml</entry>
	  <entry>
	   XML output, for Internet Explorer 5.0 and above.
          </entry>
	  <entry>xml</entry>
	  <entry><emphasis>None</emphasis></entry>
         </row>
        </tbody>
       </tgroup>
      </informaltable>
     </listitem>
    </varlistentry>
   </variablelist>
  </sect2>
  <sect2>
   <title>Page Attributes</title>
   <para>
    These options are local to each page on the site, but are global across each server and all views.
    The are located in the &lt;PAGES&gt; tag of <filename>Config/Config.xml</filename>.
   </para>
    <varlistentry id="config.page.browser_cache">
     <term>browser_cache</term>
     <listitem>
      <para>
If set to <emphasis>no</emphasis>, sends an Expires = -1 header to disable client-side
caching on the browser.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry id="config.page.content_type">
     <term>content_type</term>
     <listitem>
      <para>
Sets the content type for output.  Overrides the View
<link linkend="config.view.content_type">content_type</link>
configuration option.
      </para>
     </listitem>

docsrc/reference.xml  view on Meta::CPAN

     <refname>pkit_dbi_connect</refname>
     <refpurpose>
      Should generate and return DBI database handler, <varname>$dbh</varname>,
      which can be accessed by rest of Model using the
      <literal><link linkend="model.api.dbh">dbh</link></literal> method.
     </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
     <synopsis>
      sub pkit_dbi_connect {
       return DBI->connect("DBI:mysql:db","user","passwd");
      }
     </synopsis>
    </refsynopsisdiv>
    <refsect1>
     <title>Description</title>
     <para>
      This method will probably be replaced when request-based sessions
      are implemented.
     </para>
    </refsect1>
   </refentry>
      <refentry id="model.api.pkit_on_error">
    <refnamediv>
     <refname>pkit_on_error</refname>
     <refpurpose>
      Can be used to catch any fatal error condition.
     </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
     <synopsis>

  ## inside your Common.pm, maybe also in your Modelclass to overwrite the one in Common.pm

  sub pkit_on_error {
    my ( $model, $err ) = @_;
    my $page_id = $model->pkit_get_page_id;

    if ( $err =~ /DBI/ ) {
      # prevent endless loop if the error happened on our errorpage.
      return $err if ( $page_id =~ /db_error_page$/ );
      $model->pkit_redirect('db_error_page');
      return;
    }

    $model->pkit_message( $err );
    my $default_page = $model->pkit_get_default_page;
    return $err if ( $page_id =~ /^$default_page$/ );
    $model->pkit_redirect($default_page);
    return;
  }

     </synopsis>
    </refsynopsisdiv>
    <refsect1>
     <title>Description</title>
     <para>

pkit_on_error main purpose is to catch errors for some reason. Maybe you can not
 get a database connection or your page can not be delivered in a special
 charset or anywhere inside your modelcode an uncatched die "for unknown
 reason"; is executed.
</para>
<para>
If nowhere else in your code this error is handled, pkit_on_error is called
 with the error message as second parameter and model as the first. This is
 your chance to deliver a working page. At best with pkit_redirect or pkit_send.
</para>
<para>
If an error happened inside pkit_on_error it is passed thru Apache and you get the internal server
 error as before. pkit_on_error returns the error_msg that is logged. So you
 can change the messsage if you like. If the returned error_msg is '' or undef
 nothing is logged and pkit assumes, that the error is repaired. If you like
 to log anyway add a warn $error_msg"; inside your pkit_on_error routine.
</para>
<para>
Also pkit_on_error is no replacement for Apache::ErrorReport. pkit_on_error
 is more a runtime error catcher for most cases. A::E reports errors more
 clear with stacktrace and so on. Both can happy live together.
</para>
<para>
Another advantage is that you need only pkit_on_error to catch the error even
 if your application has millions of cases where it could fail. There is no
 need to catch them all.
</para>
<para>
If pkit_on_error is not defined in your modelclass or Common.pm, it is not used.
</para>
<para>
pkit_on_error catch only fatal errors (die) NOT warnings.
</para>
<para>
If your code likes to throw an error let it die.
     </para>
    </refsect1>
   </refentry>

   <refentry id="model.api.pkit_session_setup">
    <refnamediv>
     <refname>pkit_session_setup</refname>
     <refpurpose>
      Returns Session setup arguments.
     </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
     <synopsis>
  # here a MySQL example:
  sub pkit_session_setup {
    my $model = shift;
    my $dbh = $model->dbh;
    return {
	session_lock_class => 'MySQL',
	session_store_class => 'MySQL',
	session_args => {
			Handle => $dbh,
			LockHandle => $dbh,
			},
	};
  }

  # this one is if you prefer PostgreSQL

docsrc/reference.xml  view on Meta::CPAN

     <title>Description</title>
     <para>
Used with <ulink uri="http://kobesearch.cpan.org/search?dist=HTML-FillInForm">HTML::FillInForm</ulink> to fill in HTML forms.  Useful for example
when you want to fill an edit form with data from the database.
     </para>
    </refsect1>
   </refentry>
   
   <refentry id="model.api.ignore_fillinform_fields">
    <refnamediv>
     <refname>ignore_fillinform_fields</refname>
     <refpurpose>
      Fills in HTML Forms
     </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
     <synopsis>
  $model->ignore_fillinform_fields( qw/email name/ );
     </synopsis>
    </refsynopsisdiv>
    <refsect1>
     <title>Description</title>
     <para>
     All fields named in this call are NOT changed by fillinform.
    </para>
    </refsect1>
   </refentry>

   <refentry id="model.api.pnotes">
    <refnamediv>
     <refname>pnotes</refname>
     <refpurpose>
      Pass values from one method/handler to another
     </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
     <synopsis>
sub pkit_auth_credential {
  # ...
  $model->pnotes(user_id => $user_id);
  # ...
}
     </synopsis>
    </refsynopsisdiv>
    <refsect1>
     <title>Description</title>
     <para>
Wrapper to mod_perl's <literal>pnotes</literal> method, used to pass values from
one handler to another.
     </para>
     <para>
In the example above the <literal>user_id</literal> is set when the user
gets authenticated.
     </para>
    </refsect1>
   </refentry>
   <refentry id="model.api.output_convert">
    <refnamediv>
     <refname>output_convert</refname>
     <refpurpose>
      Outputs data for display, converting charset.
     </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
     <synopsis>
      $model->output_convert(output => {foo => $utf8_text},
			     input_charset => 'UTF-8');
     </synopsis>
    </refsynopsisdiv>
    <refsect1>
     <title>Description</title>
     <para>
      This is a wrapper to the <link linkend="model.api.output">output</link>
      method.  It converts the output from the character set specified by
      the charset argument to <link linkend="config.global.default_output_charset">default_output_charset</link>.  If the character set is not specified, then
      <link linkend="config.global.default_input_charset">default_input_charset</link> is used.
     </para>
    </refsect1>
    <refsect1>
     <title>Examples</title>
     <informalexample>
      <programlisting>
      # converts from UTF-8
      $model->output_convert(output => { key => $utf8_text },
			     charset => 'UTF-8');
      # converts from default_input_charset
      $model->output_convert(key => $text)
      </programlisting>
     </informalexample>
    </refsect1>
   </refentry>
   <refentry id="model.api.output">
    <refnamediv>
     <refname>output</refname>
     <refpurpose>
      Outputs data for display.
     </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
     <synopsis>
      $model->output(NAME => "John Doe");
     </synopsis>
    </refsynopsisdiv>
    <refsect1>
     <title>Description</title>
     <para>
      This is similar to the <ulink uri="http://kobesearch.cpan.org/search?dist=HTML-Template">HTML::Template</ulink> <literal>param</literal> method.  It is
      used to set the <link linkend="model.tags">model tags</link> in the
      PageKit templates..
     </para>
    </refsect1>
    <refsect1>
     <title>Examples</title>
     <informalexample>
      <programlisting>
  # set multiple paramaters
  $model->output(firstname => $firstname,
               lastname => $lastname);

  # set multiple paramaters with hash ref
  $model->output({firstname => $firstname,
               lastname => $lastname});

  # sets &lt;MODEL_LOOP NAME="foo"&gt;
  #       &lt;MODEL_VAR NAME="bar"/&gt;
  #       &lt;MODEL_VAR NAME="baz"/&gt;
  #      &lt;/MODEL_LOOP&gt;
  $model->output(foo => [
			 {bar => $bar1, baz => $baz1},
			 {bar => $bar2, baz => $baz2},
			]);
      </programlisting>
     </informalexample>
    </refsect1>
   </refentry>
   <refentry id="model.api.pkit_query">
    <refmeta>
     <refentrytitle>pkit_query</refentrytitle>
    </refmeta>
    <refnamediv>
     <refname>pkit_query</refname>
     <refpurpose>
      Wrapper to HTML::Template::query
     </refpurpose>
    </refnamediv>
    <refsynopsisdiv>