view release on metacpan or  search on metacpan

docsrc/features.xml  view on Meta::CPAN

   </sect2>
 </sect1>
 <sect1><?dbhtml filename="xslt_xpathtemplate.html"?>
  <title>XSLT and HTML::Template::XPath</title>
  <para>
   PageKit Templates use HTML::Template::XPath to include Content from the XML
   files.  In addition,
   PageKit Templates themselves can be generated from the XML using XSLT
   stylesheets.  Currently the only supported XSLT processer is
   <ulink url="http://kobesearch.cpan.org/search?dist=XML-LibXSLT">XML::LibXSLT</ulink> which uses Gnome libxslt library.
  </para>
  <para>
   You should use HTML::Template::XPath when you would like to separate
   some Content from the View, but do not want to go the full route
   of using XSLT.
  </para>
  <para>
   On the other hand, if you are starting from scratch, have existing XML
   and XSLT files, or have complicated transformation needs, then XSLT
   is probably the way to go.
  </para>
  <sect2>
   <title>XSLT</title>
   <para>
    To use XSLT, you must place the Content XML files in the <filename>Content/</filename> directory,
    and the View XSLT files in the <filename>View/</filename> directory.
    You must specify the XSLT template that you would like to use using the
    <literal>xml-stylesheet</literal> processing instruction by placing
    the following on the top of your XML file:
   </para>
   <informalexample>
    <programlisting><![CDATA[
     <?xml-stylesheet type="text/xsl" href="my_xslt_file.xsl"?>]]>
    </programlisting>
   </informalexample>
   <para>
    Note that the XSLT file specified in the href attribute is relative to
    the <filename>View/<replaceable>pkit_view</replaceable>/</filename> or the <filename>View/Default/</filename> directory.
   </para>
   <para>
    All of the input request parameters are available to the XSLT file by
    using the <literal>xsl:param</literal> tag in the top level of the file.
   </para>
   <para>
    The output of XSL Transformation should be a PageKit Template or a
    HTML/XML/WML file (which is a special case of a PageKit Template file, namely one without any PageKit tags).  Note that the Data from the Model gets
    filled in after the XSL transformation.  This is done for performance
    reasons - the XSL tranformation can be cached, even if the data from
    the model is updated.
   </para>
  </sect2>
  <sect2>
   <title>HTML::Template::XPath</title>
   <para>
    Using HTML::Template::XPath is easy with PageKit, it is build into the
    PageKit Template by using
    &lt;CONTENT_VAR&gt; and &lt;CONTENT_LOOP&gt; tags, which contain
    XPath queries to the Content XML data.
   </para>
   <para>
    The Content XML file defaults to <filename>Content/<replaceable>page_id</replaceable>.xml</filename> or can be specified using XPath's <emphasis role="bold">document()</emphasis> function.
   </para>
  </sect2>
 </sect1>
 <sect1>
  <title>Language Localization</title>
   <para>
   One of the main advantages of separating out the Content
   from the View is that it
   is easy to implement multiple languages while sharing the same
   look-and-feel.  You may use the <literal>xml:lang</literal>
   to label which languages tags are in.
   </para>
   <para>
   The preferred language of the user is determined as follows.
   </para>
  <itemizedlist>
   <listitem>
    <para>
     The default language preference is set to the
     <literal>Accept-Language</literal> incoming HTTP header.
    </para>
   </listitem>
   <listitem>
    <para>
     This default value can be overridden by setting the
     <literal><link linkend="request.pkit_lang">pkit_lang</link></literal>
     request parameter.
    </para>
   </listitem>
  </itemizedlist>
  <sect2>
   <title>Applying to Content: HTML::Template::XPath</title>
   <para>
    HTML::Template::XPath supports language localization through the use of the
    <literal>xml:lang</literal> attribute.  In PageKit 1.01 and above, the
    algorithm for
    selecting the node(s) for the selected languages is as follows:
   </para>
   <itemizedlist>
    <listitem>
     <para>
      First it attempts to use the XPath function <literal>lang</literal>
      to return the node or the set of nodes whose <literal>xml:lang</literal>
      attribute(s) are the same as the preferred language.  If the node
      has no <literal>xml:lang</literal>, then the value of the
      <literal>xml:lang</literal> attribute on the nearest ancestor is used.
      If the node and the its ancestors have no <literal>xml:lang</literal>
      attribute, then the <literal><link linkend="config.global.default_lang">default_lang</link></literal>
      language is used.
     </para>
    </listitem>
    <listitem>
     <para>
      If no nodes are found in the preferred language, then
      it returns the node(s) which are in the
      <literal><link linkend="config.global.default_lang">default_lang</link></literal>
      language.
     </para>
    </listitem>
   </itemizedlist>

docsrc/features.xml  view on Meta::CPAN

  <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>
      <informalexample>
       <programlisting>
  $model->output(pkit_admin => 1);
       </programlisting>
      </informalexample>
 </sect1>
 <sect1><?dbhtml filename="errorreport.html"?>
  <title>Error Reporting</title>
  <para>
   PageKit uses Apache::ErrorReport to report errors.
   It reports warnings and fatal errors to screen or e-mail. Includes detailed information including error message, call
stack, uri, host, remote host, remote user, referrer, and Apache handler.
  </para>
  <para>
   To use, place the following in the your <filename>httpd.conf</filename> file:
  <informalexample>
   <programlisting>
  PerlModule Apache::ErrorReport
  PerlSetVar ErrorReportHandler display
   </programlisting>
  </informalexample>
  </para>
  <para>
If <literal>ErrorReportHandler</literal> is set to <emphasis role="bold">display</emphasis>, errors will be displayed on the screen for easy debugging. This should be
used in a development environment only.
  </para>
  <para>
If <literal>ErrorReportHandler</literal> is set to <emphasis role="bold">email</emphasis>, errors will be e-mailed to the site adminstrator as specified in the Apache
<literal>ServerAdmin</literal> configuration directive. This should be used on a production site.
  </para>
 </sect1>
</chapter>