view release on metacpan or  search on metacpan

docsrc/features.xml  view on Meta::CPAN

              |           MyPageKit::Common           |                Specialized
              | Model code that is particular to the  |       <------- For Site, common
              | site, but common across all pages     |                across site
              +---------------------------------------+
                      /           |           \
  +----------------------------+     +----------------------------+
  | MyPageKit::YourClass1      |     | MyPageKit::YourClassN      |    Specialized
  | Model code that is for a   | ... | Model code that is for a   | <- for set of
  | group of pages on the site |     | group of pages on the site |    Pages on site
  +----------------------------+     +----------------------------+
     </programlisting>
    </informalexample>
   </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>