view release on metacpan or  search on metacpan

docsrc/features.xml  view on Meta::CPAN

<chapter><?dbhtml filename="features.html"?>
<chapterinfo>
<releaseinfo role="meta">
$Id: features.xml,v 1.21 2003/11/25 10:20:24 borisz Exp $
</releaseinfo>
</chapterinfo>
<title>Overview of Features</title>
 <sect1><?dbhtml filename="mvcc.html"?>
  <title>Model/View/Content/Controller approach to design</title>
  <para>
   PageKit follows a Model/View/Content/Controller design pattern, which
   is an adaption of the Model/View/Controller pattern used in many other
   web frameworks, including Java's Webmacro and Struts.
  </para>
  <itemizedlist>
   <listitem>
    <para>
     The Model is the user provided classes, which encapsulate the
     business logic behind the web site
    </para>
   </listitem>
   <listitem>
    <para>
     View is set of PageKit Templates, or XSLT files that generate
     PageKit Templates
    </para>
   </listitem>
   <listitem>
    <para>
     Content is set of XML Files
    </para>
   </listitem>
   <listitem>
    <para>
     Controller is PageKit
    </para>
   </listitem>
  </itemizedlist>
  <para>
This approach parallels the division of the job responsibilities of a large web development team.
The programmers can focus on the Model, the designers on the View, and the content
administrators on the (you guessed it!) Content. PageKit provides the Controller which glues
everything together. 
  </para>
  <para>
This way everybody can focus on what they do best, whether it is programming, design, or
content. Since the interfaces are simple and well-defined they can easily work together without
interfering with each other. 
  </para>
  <sect2>
   <title>Model</title>
   <para>
    The Model is provided by Perl classes which implement the business logic that is custom to the
    site.  These class files should be located in the <filename>Model/</filename> directory.  Each URL is translated into a class and method automatically. 
   </para>
   <para>
It includes support for <ulink url="http://search.cpan.org/doc/MARKSTOS/Data-FormValidator-1.6/lib/Data/FormValidator.pm">Data::FormValidator</ulink>, making the tedious task of input validation easier.
To validate a form, you simply specify required fields and constraints. If there is an error, you
can return to the input form, and the invalid fields automatically get highlighted in red.
   </para>
  </sect2>
  <sect2>
   <title>View</title>
   <para>
    The View is defined by a set of PageKit Templates making up pages and their
    components located in the <filename>View/</filename> directory. These
    templates can be in HTML, WML, XML, or any text based format.
   </para>
   <para>
    Alternatively, you can provide a set of XSLT files that will generate PageKit Templates.
   </para>
   <para>
    PageKit Template is based on <ulink url="http://kobesearch.cpan.org/search?dist=HTML-Template">HTML::Template</ulink>.
There are different sets of tags, depending on
where the data is being pulled from.
   </para>
   <para>
The <link linkend="model.tags">Model Tags</link>,
&lt;MODEL_VAR&gt;, &lt;MODEL_LOOP&gt;, and &lt;MODEL_IF&gt;,
are filled with data by the Model.
   </para>
   <para>
The <link linkend="content.tags">Content Tags</link>,
&lt;CONTENT_VAR&gt; and &lt;CONTENT_LOOP&gt;, contain
XPath queries to the Content XML data.
   </para>
   <para>
The <link linkend="pagekit.tags">PageKit Tags</link> are set internally by the Controller.
   </para>
   <para>
It is easy to implement <link linkend="features.multiple.views">multiple views</link>, such as a printable version of a web page or a
co-branded site. To create a new view, simply create a directory containing template files for
the view. You only have to create templates for pages and components that you wish to
override. That is all views inherit from the default set of templates.
   </para>
  </sect2>
  <sect2>
   <title>Content</title>
   <para>
Content is stored in an XML files.  It is accessed either through XPath queries from
PageKit Template using <ulink url="http://kobesearch.cpan.org/search?dist=HTML-Template-XPath">HTML::Template::XPath</ulink> or by applying XSLT stylesheets to transform the XML into a
PageKit Template.
   </para>
   <para>
     Language localization couldn't be easier. Simply use the
     <literal>xml:lang</literal> attribute in the tags you wish
     to localize. For example, to have a title available in both English and Spanish use:
   </para>
   <informalexample>
    <programlisting><![CDATA[
  <title xml:lang="en">Title in English</title>
  <title xml:lang="es">Titulo en Español</title>]]>
    </programlisting>
   </informalexample>
  </sect2>
  <sect2>
   <title>Controller</title>
   <para>

docsrc/features.xml  view on Meta::CPAN

   To store information during a request, use the
   <literal><link linkend="model.api.pnotes">pnotes</link></literal> method.
  </para>
  <para>
   As of PageKit 1.05, there is support for associating sessions with
   authentication.  The associated session ID may be specified by the second
   argument returned my <link linkend="model.api.pkit_auth_session_key">pkit_auth_session_key</link>.  When a user logs in, their current session may be merged with the session
   stored with their user ID.  To override the default behavior, use the
    <link linkend="model.api.pkit_merge_sessions">pkit_merge_sessions</link> hook.
  </para>
  <para>
   As of PageKit 1.08, there is support for page based sessions.
  </para>
 </sect1>
 <sect1><?dbhtml filename="authentication.html"?>
  <title>Authentication</title>
  <para>
   When a user logins in, the <literal><link linkend="request.pkit_login">pkit_login</link></literal> request parameter must be set to a true value.  In addition, if you want
the user to be redirected to another page, set the <literal><link linkend="request.pkit_done">pkit_done</link></literal> parameter.  To do this, place
the following hidden fields in your login form page:
  <informalexample>
   <programlisting>
    &lt;!-- Login Page --&gt;
    #  will get set by pagekit to the page the user is requesting
    &lt;input type="hidden" name="pkit_done"&gt;
    &lt;input type="hidden" name="pkit_login" value="1"&gt;
   </programlisting>
  </informalexample>
  </para>
  <para>
   If <literal><link linkend="request.pkit_login">pkit_login</link></literal> is set to a true value, then PageKit calls <literal><link linkend="model.api.pkit_auth_credential">pkit_auth_credential</link></literal> method.  If this method returns a s...
by <literal><link linkend="request.pkit_done">pkit_done</link></literal>,
setting the cookie <literal>pkit_id</literal> to the session_key.
  </para>
  <para>
   While the user is logged in, PageKit checks the session_key by using
   the <literal><link linkend="model.api.pkit_auth_session_key">pkit_auth_session_key</link></literal> method.  If the <literal><link linkend="request.pkit_logout">pkit_logout</link></literal> request parameter is set, then the user is
logged out.
  </para>
  <para>
PageKit access to pages based on the <literal><link linkend="config.page.require_login">require_login</link></literal> attribute.
If <literal><link linkend="config.page.require_login">require_login</link></literal>
is set to <emphasis>recent</emphasis>, then PageKit requires that session is currently active in the last
<literal><link linkend="config.global.recent_login_timeout">recent_login_timeout</link></literal>
seconds.
  </para>
  <para>
  Note, that the pages <literal><link linkend="config.global.default_page">default_page</link></literal>,
  <literal><link linkend="config.global.verify_page">verify_page</link></literal> and
  <literal><link linkend="config.global.login_page">login_page</link></literal> can not be protected in any way.
  </para>
 </sect1>
 <sect1><?dbhtml filename="validation.html"?>
  <title>Form Validation</title>
   <para>
  PageKit uses <ulink url="http://search.cpan.org/doc/MARKSTOS/Data-FormValidator-1.5/lib/Data/FormValidator.pm">Data::FormValidator</ulink> to provide easy form validation.  Highlights
fields in red that user filled incorrectly by using the
<link linkend="pkit.errorfont">PKIT_ERRORFONT</link> tag.  In addition,
error message(s) are displayed using the <link linkend="pkit.messages">PKIT_MESSAGES</link> tag.
To use, pass an input profile to the
<literal><link linkend="model.api.pkit_validate_input">pkit_validate_input</link></literal> method.
  </para>
  <para>
   In addition, you may implement your own custom error handling by using <literal><link linkend="model.api.pkit_set_errorfont">pkit_set_errorfont</link></literal> to set the <link linkend="pkit.errorfont">PKIT_ERRORFONT</link> tags.
  </para>
 </sect1>
 <sect1><?dbhtml filename="fillinform.html"?>
  <title>Sticky HTML Forms</title>
  <para>
   PageKit uses <ulink url="http://kobesearch.cpan.org/search?dist=HTML-FillInForm">HTML::FillInForm</ulink> to fill in HTML Forms with the request parameters.  You
   can turn this feature off by setting <literal><link linkend="config.page.fill_in_form">fill_in_form</link></literal> to <emphasis>no</emphasis>.
  </para>
  <para>
   One useful application is if you have set up error handling and if an user
   submits an HTML form without filling out
   a required field, PageKit will re-display the HTML form with all the form 
   elements containing the submitted info.
  </para>
  <para>
   In additon to filling in request parameters, you may fill in the HTML
   fields from the model by using the <literal><link linkend="model.api.fillinform">fillinform</link></literal> method.
  </para>
 </sect1>
 <sect1 id="features.multiple.views"><?dbhtml filename="multipleview.html"?>
  <title>Multiple Views</title>
  <para>
   Any page can have multiple views, by using the <literal><link linkend="request.pkit_view">pkit_view</link></literal> request parameter.
One example is Printable pages.  Another
is having the same web site branded differently for different companies.
Another is having different Media outputs such as HTML, XML and WML, by
using the <link linked="config.global.content_type">content_type</link>
configuration options.
  </para>
  <para>
   To create a new view, create a <filename>View/<replaceable>pkit_view</replaceable></filename> directory and place the PageKit Templates and XSLT files for
the pages and components that you wish to apply the view to.  Note that if
PageKit doesn't find a template or XSLT file in the <filename>View/<replaceable>pkit_view</replaceable></filename> directory it looks in the
<filename>View/Default</filename> directory.  That is, the files <filename>View/<replaceable>pkit_view</replaceable></filename> "override" the files
in <filename>View/Default</filename> directory.
  </para>
  <para>
   To association a media output such as XML, WML, or PDF with a view, use
   the View <link linkend="config.view.content_type">content_type</link> attribute.
   Note that in order for PDF output to work, you must install the Apache XML
   FOP processor, available from
   <ulink url="http://xml.apache.org/fop/">http://xml.apache.org/fop/</ulink>, and
   configure <link linkend="config.global.fop_command">fop_command</link> to point
   to the FOP processor.
  </para>
  <para>
   You may set the <literal><link linkend="request.pkit_view">pkit_view</link></literal> request parameter in the request URI or by using
   <literal>$model->input(pkit_view => <replaceable>pkit_view</replaceable>);</literal> in your model code.
  </para>
 </sect1>
 <sect1 id="features.editing"><?dbhtml filename="editing.html"?>
  <title>On-line Editing tools</title>
  <para>
   PageKit supports a set of simple on-line editing tools.  To enable,
   set <literal><link linkend="config.server.can_edit">can_edit</link></literal> in your
   server config.  You will also need to call in your Model code:
  </para>