A target is everything that is the result of a XSLT transformation as seen in Figure 3.3, “Recursive XSL transformations”. It is also obvious that a target can be used to create new targets. For the sake of completeness, the initial XML or XSL files that are used in transformations are called targets, too.

The Pustefix system knows different types of targets:

Some parts of the Pustefix framework are configured using Java properties. To ease this configuration Pustefix provides you with a special XML format which is read instead of the usual Java property file format. This format provides some customization mechanism to allow configuration options to depend on settings like the makemode or the machine the application is being built on.

The structure of a standard .xml property file is very easy:

  
  <properties
    xmlns="http://www.pustefix-framework.org/2008/namespace/properties-config"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.pustefix-framework.org/2008/namespace/properties-config
                        http://www.pustefix-framework.org/2008/namespace/properties-config.xsd">
    
    <prop name="a.property.name">a.property.value</prop>
    <!-- if you're using multitenancy, you can set or override properties depending on the tenant
    <prop name="a.property.name" tenant="a.tenant">a.property.value</prop> -->
  </properties>
  
        

The prop tag is the most primitive way to enter a single property. The example above would simply result in the java property a.property.name=a.property.value. Pustefix allows to customize the creation of the property files using the mechanism described in Section 4.2, “Customization tools”.

You may reference customization variables in property values using the syntax ${variableName}. For example ${fqdn} will be replaced by the fully qualified domain name of the machine.

The project.xml file contains references to all services and resources used by this project.

<project-config xmlns="http://www.pustefix-framework.org/2008/namespace/project-config">
  
  <project>
    <!-- Short project name, should equal the name 
         of the project directory                  --> 
    <name>projectname</name>
    <!-- Description shown in Pustefix CMS -->
    <description>Description for this project</description>
    <!-- 
      add
    <enabled>false</enabled>
      to make disregard this project when building the
      server configuration 
    -->
    <!-- you can optionally specify which languages should be switchable at runtime -->
    <!--
    <lang default="true">en_UK</lang>
    <lang>de_DE</lang>
    -->
  </project>
  
  <!-- You can optionally configure tenants bound to specific hosts supporting different languages.-->
  <!--
  <tenant name="CA_market">
    <choose>
      <when test="$mode='prod'">
        <host>.*\.ca$</host>
      </when>
      <otherwise>
        <host>^ca\..*</host>
      </otherwise>
    </choose>
    <lang default="true">en_CA</lang>
    <lang>fr_CA</lang>
  </tenant>

  <tenant name="US_market">
    ...
  </tenant>
  -->

  <editor>
    <!-- Set this to false to make the project disappear in the Pustefix CMS 
         (can be overridden using the ServletContext init parameter 'editor.enabled') -->
    <enabled>true</enabled>
    <!-- Location of the Pustefix CMS, does not need to be changed usually 
         (can be overridden using the ServletContext init parameter 'editor.location') -->
    <location>http://cms.${fqdn}/</location>
    <!-- Authentication secret for editor communication
         (can be overridden using the ServletContext init parameter 'editor.secret') -->
    <secret>somevalue</secret>
  </editor>
  
  <xml-generator>
    <!-- Path to the configuration file of 
         the TargetGenerator for this project -->
    <config-file>docroot:/WEB-INF/depend.xml</config-file>
    <choose>
      <when test="$mode='prod'">
        <!-- Set this to false if you want to skip the check for changed stylesheets on every request.
             By default Pustefix will all dependant files for changes. -->
        <check-modtime>false</check-modtime>
        <!-- Set capacity and implementation class of the in-memory caches for includes and targets.
             Defaults (if you leave out the elements):
             <include-cache capacity="30" class="de.schlund.pfixxml.targets.LRUCache"/>
        -->
        <include-cache capacity="50"/>
        <target-cache capacity="50"/>
        <render-cache capacity="50"/>
      </when>
      <when test="$mode='prelive'">
        <!-- Enable/disable development tooling extensions (dynamic include info, console, etc.) 
             By default tooling is enabled if not in production mode. So this option is basically
             meant for non-production modes where you nevertheless want to disable tooling. 
        -->
        <tooling-extensions>false</tooling-extensions>
      </when>
    </choose>
  </xml-generator>
  
  <!-- automatically generate searchengine sitemap file sitemaps.xml 
       (according to sitemaps protocol from http://www.sitemaps.org), 
       set the attribute "type" to "mobile" to generate a mobile sitemap-->
  <searchengine-sitemap/>

  <!-- DEPRECATED - Configure tracking-mode in web.xml instead!
       Sets the session tracking strategy. Default is 'COOKIE'.
       Alternatively you can set 'URL' to force session tracking
       within the URL, even if clients support cookies. You can completely
       disable URL based session tracking by setting 'COOKIEONLY'. You can
       completely leave out this element, if you go with the default. -->
  <!-- <session-tracking-strategy>COOKIE</session-tracking-strategy> -->

  <!-- Set an initial session timeout 'value' (in seconds) used until 
       more than 'requestlimit' requests are made within a session.
       This element is optional. By default no separate timeout
       for the initial requests is used. -->
  <initial-session-timeout value="600" requestlimit="3"/>

  <application>
    
    <!-- Path that static resources will be delivered from (set i18n attribute to "true" for multitenancy/-language support)-->
    <docroot-path>docroot:/htdocs</docroot-path>
    
    <!-- URI requests to / are redirected to (optional)-->
    <default-path>/somepage</default-path>
    
    <!-- Only one context-xml-service may be specified per project -->
    <context-xml-service>
      <!-- Path to the configuration file for the service -->
      <config-file>docroot:/WEB-INF/config.conf.xml</config-file>
      <!-- Set this to true if you want to skip the last transformation and only get a
           xml document containing all needed information for an external renderer: -->
      <!-- <render-external>true</render-external> -->
      <!-- Set the maximum number of DOMs stored for reusage (default 5): -->
      <!-- <max-stored-doms>5</max-stored-doms> -->
      <!-- Set the timeout (in seconds) for removing old DOMs (default 300): -->
      <choose>
        <when test="$mode='prod'">
          <session-cleaner-timeout>20</session-cleaner-timeout>
        </when>
        <otherwise>
          <session-cleaner-timeout>600</session-cleaner-timeout>
          <!-- Allow viewing of the DOM tree model, which is enabled 
               by default in all non-production modes -->
          <!--<show-dom>true</show-dom>-->
          <!-- Maximum number of DOM trees to be displayed in DOM tree view -->
          <!-- <dom-history-size>5</dom-history-size> -->
        </otherwise>
      </choose>
    </context-xml-service>
    
    <direct-output-service>
      <!-- Path to the configuration file for the service -->
      <config-file>docroot:/WEB-INF/direct.conf.xml</config-file>
    </direct-output-service>

    <!-- Extra paths for static resources (set i18n attribute to "true" for multitenancy/-language support)-->
    <static expires="3600">
      <!-- The expires attribute and elements set the "Cache-Control: max-age" header value for static resources.
           The expires value specifies the calculation base and the number of seconds. Default base is access 
           time (default prefix "A" can be omitted). Optionally you can use the modification time by prefixing
           the value with "M" (e.g. "M3600", see Apache mod_expires for more detailed information).
      -->
      <!--
      <expires type="image/png">A3600</expires>
      <expires type="text/css">M3600</expires>
      -->
      <path>img</path>
      <path i18n="true">errorpages</path>
    </static>
   
    <!-- Exceptions thrown by the business logic or Pustefix itself can be handled on the top layer by so-called
         ExceptionProcessors, e.g. an ExceptionProcessor implementation can forward certain types of exceptions to
         error pages, log them to a file or pass them to an external tool. If you don't configure an ExceptionProcessor
         or the ExceptionProcessor doesn't create an HTTP response by itself, the default exception handling of the 
         servlet container applies. Pustefix provides a default implementation for development, which renders the
         exception together with some contextual information as HTML. But this processor should only be used in test
         mode, because it would expose system internals to the world. In production mode you should leave it out or
         register an alternative implementation.
    -->
    <choose>
      <when test="$mode='test'">
        <exception-processing>
          <process type="java.lang.Throwable" 
                   processor="de.schlund.pfixxml.exceptionprocessor.UniversalExceptionProcessor"/>
          <!-- <process type="mypackage.MyException" forward="true" page="/error.html"/> -->
        </exception-processing>
      </when>
    </choose>

    <!--  Custom Deplyment descriptor code
    <web-xml>
      <jee:web-app xmlns:jee="http://java.sun.com/xml/ns/javaee">
        <choose>
          <when test="$mode='test'">
            <jee:display-name>foo</jee:display-name>
          </when>
        </choose>
      </jee:web-app>
    </web-xml>
    -->
    
  </application>
  
  <!-- Example configuration of Spring MessageSources -->
  <messagesources>
    <messagesource type="po">
      <basename>module://my-module/i18n/messages</basename>
      <basename>module://my-module/i18n/errors</basename>
    </messagesource>
    <messagesource type="properties" basename="/WEB-INF/messages"/>
  </messagesources>

</project-config>


      

As you can see, the configuration file consists of different sections: One for information about the project, one for configuring the Pustefix CMS, one for the server configuration and one for the application itself. The application consists of services and static resources. Please note that only one context-xml-service is allowed per project.

The depend.xml is used to define the internal structure of the pages by defining, for every single page, the tree of transformations that need to be applied to certain files to get the final stylesheet (which is the representation of the page in Pustefix). For an overview over the transformation aspect of the whole framework, please go here.

To make life a little easier, you can use convenience tags that are automatically transformed by the runtime system when the file is loaded.

<make project="MyProject" lang="en" themes="ThemeA ThemeB ... default">

  <!--
    The global section allows to set default values for ALL pages defined via the
    standardpage tag (see below). It's possible to set default params, and runtime
    stylesheets (see here). It's also possible to add more runtime stylesheets or
    overwrite params in the standardpage tag for a single page.
  -->
  <global>
    <include stylesheet="path/to/AStyleSheet"/>
    <!-- Stylesheets from module jars can be directly included by setting the module attribute. -->
    <!-- <include stylesheet="path/to/AStyleSheetFromModule" module="modulename"/> -->
    <param name="AName" value="AValue"/>
    <!-- Enable compressing of inline Javascript (requires YUI compressor or Google Closure Compiler in classpath) -->
    <cus:choose>
      <cus:when test="$mode = 'prod'">
        <param name="compress-inline-javascript" value="true"/>
      </cus:when>
    </cus:choose>
    <!-- Show missing includes, i.e. display a warning image if an include doesn't exist or has no matching theme. -->
    <cus:choose>
      <cus:when test="$mode = 'prod'">
        <param name="show-missing-include" value="false"/>
      </cus:when>
      <cus:otherwise>
        <param name="show-missing-include" value="true"/>
      </cus:otherwise>
    </cus:choose>
  </global>

  <config-include file="conf/myfile.xml" section="targets" module="mymodule"/>

  <!--
    The other allowed tags are target, global, standardmaster, standardmetatags and 
    standardpage. The latter three are only convenience tags that can be expressed 
    fully in terms of target tags (Expanding those tags is one of the duties of the 
    runtime transformation of the depend.xml file mentioned above).
  -->
  <target name="a_target_name.xsl" type="[xsl|xml]">...</target>
  <target name="another_target_name.xml" type="[xsl|xml]">...</target>...
  <standardmaster name="..."/>
  <standardmetatags name="..."/>
  <standardpage name="a_name" master="..."
                metatags="..." themes="..." variant="..."
                xml="a_base_xml_file.xml">
  <auto-standardpage lookup-path="txt/pages" lookup-module="..." 
                     master="..." metatags="..." themes="..." variant="..."
                     xml="a_base_xml_file.xml">
    ...
  </standardpage>
</make>

<target name="baz.xsl" type="xsl" page="foo" variant="bar" themes="Theme_A Theme_B ... default">
  <!--
    depxml and depxsl reference other targets by their name attribute
    that serve as the XML resp. XSL input used to create this target
    via a XSL transformation. If for a given name attribute of either
    depxml or depxsl no other target definition is found, the transformation
    parent is supposed to be a leaf target and the name attribute is 
    interpreted as a path relative to the docroot.
  -->
  <depxml name="foo/xsl/bar.xsl"/>
  <depxsl name="foo/xsl/baz.xsl"/>

  <!--
    Additional dependencies
  -->
  <depaux name="foo/xsl/snarf.xsl"/>
  <depaux name="foo/xsl/fubar.xsl"/>

  <!--
    param tags supply XSL transformation parameters that are used when the target is generated.
  -->
  <param name="AName" value="AValue"/>
</target>

<depaux name="foo/xsl/fubar.xsl"/>

Standard page definition

The standardpage tag is a convenience tag that encapsulates the typical definition of a complete page in the Pustefix system.

<standardpage name="BazPage" master="AName" metatags="AName" xml="xml/FooBase.xml"
              themes="Theme_A Theme_B ... default" variant="foo">
  <!--
    Note: All the child nodes are optional (and in fact usually not needed)
  -->
  <include stylesheet="xsl/runtime.xsl"/>
  <!-- Stylesheets from module jars can be directly included by setting the module attribute. -->
  <!-- <include stylesheet="xsl/runtimeFromModule.xsl" module="modulename"/> -->
  <param name="fubar" value="bar"/>
</standardpage>

The <standardpage> tag supports the following attributes:

Table 4.3. Attributes of the <target> tag

Attribute	Mandatory?	Description
name	mandatory	The name of the page. This must be a name already defined in a page tag in the navigation tree.
xml	mandatory	The name of a xml target to use as input for the "metatags transformation". Often this is a leaf target and one of the projects structural xml files.
module	optional	The name of the module from which the xml file should be loaded.
themes	optional	This attribute is a local overwrite of the global themes attribute explained here.
variant	optional	This attribute allows you to define variants of the same page. It's only possible to define variants of pages when there's already a "root" page, in other words a standardpage definition without the variant attribute. Variants also influence the local themes (in fact the visible aspect of variants is implemented in terms of themes).
master	optional	Default is to use the default definition of the master stylesheet (standardmaster without a name attribute).
metatags	optional	Default is to use the default definition of the metatags stylesheet (standardmetatags without a name attribute).

Page auto-configuration

If you're configuration contains a lot of repeating standardpage definitions only differing in the page name, you can alternatively use <auto-standardpage>, which will automatically create standardpage definitions for all found pages. Pages are searched looking for XML files in the directory specified by the lookup-path attribute (and lookup-module if the pages are located in modules). The page name will be derived from the XML file name. Apart from the name attribute all standardpage attributes can be used. <auto-standardpage lookup-path="txt/pages" lookup-module="*" master="AName" metatags="AName"> ... </auto-standardpage>

After performing the transformation of the depend.xml on loading (automatically done by the runtime system system) this becomes

<target name="BazPage::foo.xsl" type="xsl" themes="foo Target_A Target_B ... default" page="BazPage" variant="foo">
  <!--
    For every target that is only used in the generation of one single page
    (if you look at the example given here, this is true for the generated
    targets BazPage.xml and BazPage.xsl) you must give a parameter called page
    with the name of the resulting page as the value for the standard XSLT tags
    to be able to work correctly. They need this information e.g. to create links
    to other pages and many other things. While the standardpage tag does this
    automatically for you make sure that you don't forget it for target structures
    you define yourself.

    If the master attribute is not given, the depxsl will be master.xsl
  -->
  <depxml name="BazPage::foo.xml"/>
  <depxsl name="master-AName.xsl"/>
  <param name="page" value="BazPage"/>

  <!--
    parameters given to the standardpage tag are supplied to the first of the two
    transformations. The outputencoding parameter is inserted by the build system.
    Refrain from supplying this parameter on your own, unless you really know what
    you do. Changing the encoding should be done in the project.xml file.
  -->
  <param name="fubar" value="bar"/>
  <param name="outputencoding" value="UTF-8"/>

  <!--
    All include tags given are runtime stylesheets, given to the transformation via
    the parameter stylesheets_to_include (as a space separated list if multiple
    include tags are given). Note that the needed depaux nodes are inserted automatically.
  -->
  <param name="stylesheets_to_include" value="xsl/runtime.xsl"/>
</target>

<target name="BazPage::foo.xml" type="xml" themes="foo Themes_A Themes_B ... default">

  <!--
    If the metatags attribute has not been given, the depxsl value is metatags.xsl  
  -->  
  <depxml name="xml/FooBase.xml"/>
  <depxsl name="metatags-AName.xsl"/>

  <param name="fubar" value="bar"/>
  <param name="page" value="BazPage"/>
</target>

<standardmaster name="AName">
  <!-- The name attribute is optional -->
  <include stylesheet="xsl/skin.xsl"/>
  <!-- Stylesheets from module jars can be directly included by setting the module attribute. -->
  <!-- <include stylesheet="xsl/skinFromModule.xsl" module="modulename"/> -->
  <param name="AName" value="AValue"/>
</standardmaster>

<target name="master-AName.xsl" type="xsl">
  <!--
    If the name attribute of the standardmaster tag has not been given,
    the value for the target's name attribute will be master.xsl.
  -->
  <depxml name="xsl/master.xsl" module="pustefix-core"/>
  <depxsl name="xsl/customizemaster.xsl" module="pustefix-core"/>
  <param name="AName" value="AValue"/>
  <param name="product" value="MyProject"/>
  <param name="lang" value="en"/>
</target>

<standardmetatags name="AName">
  <!-- The name attribute is optional -->
  <include stylesheet="xsl/metatags.xsl"/>
  <!-- Stylesheets from module jars can be directly included by setting the module attribute. -->
  <!-- <include stylesheet="xsl/metatagsFromModule.xsl" module="modulename"/> -->
  <param name="AName" value="AValue"/>
</standardmetatags>

<target name="metatags-AName.xsl" type="xsl">
  <!--
    If the name attribute of the standardmetatags tag has not been given,
    the value of the name attribute here becomes metatags.xsl.
  -->

  <depxml name="xsl/metatags.xsl" module="pustefix-core"/>
  <depxsl name="xsl/customizemaster.xsl" module="pustefix-core"/>
  <param name="stylesheets_to_include" value="xsl/metatags.xsl "/>
  <param name="AName" value="AValue"/>
  <param name="product" value="MyProject"/>
  <param name="lang" value="en"/>
</target>

The optional sitemap configuration file sitemap.xml can be used to define a logical page structure, e.g. for grouping pages according to a navigation or menu structure. This sitemap can be accessed during the XSL transformations using the XSL parameter $sitemap.

The sitemap can be also used to provide page name aliases. Pustefix differentiates between logcial page names and display page names. Within the sitemap you can set a display page name by setting a so-called page alias. Thus you can rename a page without having to change existing page references, i.e. internally the logical name is still used, but when Pustefix renders the page, page names in links, etc., are replaced by the display names.

In addition the sitemap allows the definition of page alternatives. Page alternatives can be used to create different representations of a page. They base on the same logical page, but can produce different content and display names, e.g. for landing pages.

Finally you can define so-called page groups, which let you group pages and add a common path prefix to their URL. Page groups can be nested arbitrarily, which will create compound path prefixes.

<sitemap>
  <!-- page elements can be arbitrarily listed/nested, the name attribute relates to the logical page name -->
  <page name="Home">
    <page name="..."/>
    <page name="..."/>
  </page>
  <!-- the 'alias' attribute can be used to provide a page alias which should be displayed instead of the logical name,
       you can optionally add the 'internal' attribute to exclude a page from the generated search engine sitemap or
       add a 'lastmod' attribute to generate an according lastmod element.
       You're also allowed to use arbitrary custom attributes -->
  <page name="Overview" alias="Summary" internal="true" lastmod="2017-06-27T18:29:39+01:00" foo="bar"/>
  <!-- using the alt element you can add page alternatives, matching is done using the mandatory key attribute -->
  <page name="Info">
    <alt key="cities" name="Cities"/>
    <alt key="nationalparks" name="NationalParks"/>
    <alt key="mountains" name="Mountains"/>
    <!-- Optionally you can set one page alternative to be the default one used when no page alternative is
         explicitly requested -->
    <!-- <alt key="mountains" name="Mountains" default="true"/> -->
  </page>
  <!-- the page-group name will appear as path prefix in the URL, setting the default attribute on a page will make it
       accessible under the group name, e.g. /mainpath/mainpage, /mainpath/subpath/ and /mainpath/subpath/subpage2 --> 
  <page-group key="main" name="mainpath">
    <page name="mainpage"/>
    <page-group key="sub" name="subpath">
      <page name="subpage1" default="true"/>
      <page name="subpage2"/>
    </page-group>
  </page-group>
  <!-- additional parts of a sitemap can be included, e.g. from modules -->
  <config-include file="conf/sitemap-fragment.xml" section="sitemap" module="*"/>
</sitemap>

Internationalizing page names can be done by creating additional language specific alias mappings. These mappings are defined in the sitemap-alias.xml configuration files.

<sitemap-aliases lang="de">
  <!-- the alias elements map page names to language specific display names -->
  <alias page="Home">Start</alias>
  <alias page="Overview">Uebersicht</alias>
  <alias page="Info">Information</alias>
  <alias page="Cities">Staedte</alias>
  <alias page="NationalParks">Nationalparks</alias>
  <alias page="Mountains">Berge</alias>
</sitemap-aliases>

The ContextXMLService handles requests for all pages (where page means some content generated by an XSL transformation). The name of the configuration file can be arbitrarily chosen and is configured in the project configuration file.

This service uses a configuration file that has a special syntax. However properties and customization in this file work nearly the same way as explained for the standard property definitions.

  <context-xml-service-config
    xmlns="http://www.pustefix-framework.org/2008/namespace/context-xml-service-config"
  >
    <global-config>
      <force-ssl>false</force-ssl>
        

force-ssl can be set to true in order to enforce a secure connection for all pages of this service. The whole node is optional and defaults to false.

      <defaultstate class="a.state.Class"/>
      <defaultihandlerstate class="another.state.Class"/>
      <!-- optional attribute for both elements: parent-bean-ref="..." -->
        

defaultstate and defaultihandlerstate are both optional. The class attribute must be given. a.state.Class should de a descendant of de.schlund.pfixcore.workflow.app.StaticState and another.state.Class should be a descendant of de.schlund.pfixcore.workflow.app.DefaultIWrapperState (unless you really know what you are doing). They are used to set the defaults for the state tag used when processing the pagerequest tag (see there for more info).

Note

As Pustefix creates a singleton-scoped Spring bean of the specified class for each page, which uses a default state, you can't inject dependencies using the Spring XML configuration. That's why Pustefix supports the referencing of parent bean definitions using the parent-bean-ref attribute. Thus it's possible to indirectly inject dependencies into the concrete instances by injecting them into the parent bean definition.

    </global-config>
    
    <context defaultpage="APageName" synchronized="true">
        

      <defaultpage>
        <variant name="VARIANTNAME">PAGENAME</variant>
        ...
        <default>PAGENAME</default>
      </defaultpage>
        

The defaultpage element can be used if you want to define multiple defaultpages for different variants. [Since: 0.13.1]

      <resource class="A_Resource">
      <!-- optional attributes: bean-name="A_Name" scope="prototype|request|session|singleton"/> -->
        

class is mandatory, can be any Java class, that can be created with a default constructor. The scope attribute is optional and defines the scope in which the Spring bean representing the resource is instantiated (session scope by default). The bean-name attribute is optional and specifies the name of the Spring bean that is created for this resource. There may be multiple resource tags given.

        <implements class="A_Interface">
        

The whole implements node is optional. class is mandatory, must be a Java interface implemented by the resource. There may be more than one implements tag for a resource, but each interface must be unique in the whole context. In other words: it's possible for a resource to implement more than one interface, but not possible for one interface to be implemented by two resources used in the same Context definition.

        </implements>
        <properties>
        

The whole node is optional.

          <prop name="A_Name">A_Value</prop>
        

prop is mandatory and can be used multiple times. It's similar to the use as a child of pagerequest/properties, but used here to create properties that are related to a context resource implementation. The resulting property looks like this: context.resourceparameter.A_Resource.A_Name=A_Value Customization tags may be used around a property to make it depend on a certain makemode or other parameters.

        </properties>
      </resource>
    </context>
    
    <global-output>
 

The whole section is optional. You can list an arbitrary number of resources here. The node attribute value has to be unique within this section and the output section of all pagerequest elements.

        <resource node="AName" bean-ref="aBeanName"/>
        

    </global-output>

    <interceptors>
      <start>
        <interceptor class="mypackage.MyInterceptor"/>
        <interceptor bean-ref="myInterceptor"/>
      </start>
      <end> ... </end>
      <postrender> ... <postrender>
    </interceptors>
        

Within the interceptors section you can configure ContextInterceptors grouped by the according interception points (for details see Section 6.6, “ContextInterceptors”).

    <scriptedflow name="AName" file="path/to/scriptfile.xml"/>
        

There may be an arbitrary number of scriptedflow tags, but each one must have a unique name. Scripted flows are a special method to control a session and do automatic requests based on initial user input.

    <role name="A_ROLE"/>
    <condition id="A_CONDITION"/>
    <authconstraint id="AN_AUTHCONSTRAINT"/>
        

You can define an arbitrary number of roles, conditions and authconstraints here, for details see Section 7.6, “Authentication and authorization”.

    <preserve-params>
      <param name="myparam"/>
      <!-- <config-include file="path/to/config-fragments.xml" section="preserve-params"/> -->
    </preserve-params>
         

Sometimes request parameters should be preserved when redirecting after a request has been processed, e.g. for passing tracking information. Here you can configure a global list of such parameters.

    <disable-pageflow-passthrough/>
         

Pustefix by default passes through the name of the last pageflow using the __lf URL parameter, thus indicating the preferred pageflow when a page is part of multiple flows. You can get rid of this parameter (e.g. for SEO reasons) by disabling the passthrough, which lets Pustefix store the name of the last flow in the session instead. You should be aware that disabling the passthrough can result in a different pageflow chosen under certain conditions (search for PAGEFLOW_PASSTHROUGH_DIFF in pustefix-servlet.log to find out these cases before disabling the passthrough).

    <pageflow name="AName" final="APageName" stopnext="true|false">
         

There may be multiple pageflow tags defined, but you need at least one (which must be referenced by the defaultflow attribute above). We only describe the normal case without using variants. See here for more information on how to handle variants of pageflows.

      <flowstep name="AnotherPageName" stophere="true|false">
        

        <oncontinue applyall="true|false">
        

This tag (which is optional) starts a sequence of test/action pairs. The tests are XPath expressions which work on the DOM tree as produced by the flowstep's associated state (note that the navigation is not inserted into the DOM tree at this stage, and the /formresult/formvalues and /formresult/formerrors paths are also not present). The pageflow system calls the tests whenever a state returns a ResultDocument (before it continues with other stuff e.g. a pageflow run). The applyall attribute is optional. If given and true, all actions with matching conditions are executed, if not given or false (the default) only the first action with a matching condition is executed.

          <when test="A_XPath_Expression">
        

The when tag contains the XPath expression to try in it's test attribute. If this attribute is omitted, the whole condition is considered to be true.

            <action type="jumpto" page="APage" pageflow="APageFlow">
        

The action tag denotes the FlowStepAction to execute. The type attribute is mandatory and defines the special action to use. The string jumpto denotes the special FlowStepAction de.schlund.pfixcore.workflow.FlowStepJumpToAction which is used to set the jumptopage (defined via the page attribute) and/or the jumptopageflow (defined via the pageflow attribute).

            </action>
          </when>
          <when test="A_XPath_Expression">
            <action type="A_FlowStepAction" somekey="somevalue">
        

If the type attribute is not jumpto, the value is interpreted as a class of type de.schlund.pfixcore.workflow.FlowStepAction. There can be an arbitrary number of additional attributes (somekey in this example) which are supplied as named parameters to the special FlowStepAction.

            </action>
          </when>
        </oncontinue>
      </flowstep>
    </pageflow>
    
    <pagerequest name="APageName" copyfrom="APageName">
        

      <defaultflow flow="FlowName"/>
        

This node is optional. If a page is part of multiple pageflows, here you can set the default pageflow, which should be chosen if no other pageflow is specified.

      <force-ssl>true|false</force-ssl>
        

The node is optional. If given, and the content is set to true, the page will only run under SSL when jumped to via a link or a submit of form data. If the session currently does not run under SSL, the system will make sure to redirect to a secure session prior to handling the request. After a session is running under SSL, there is no way back (so all other pages will run securely regardless if they have a ssl node or not). You can wrap this tag within a customization element to force use of SSL only in certain modes (e.g. prod mode).

	Note
	You can force the servlet as a whole to run only under SSL by specifying the ssl subnode of the servletinfo node.

  <state class="AClassName"/>
  <!-- Alternative usage forms:
    <state class="..." bean-name="..." scope="..."/>
    <state class="..." parent-bean-ref="..."/>
    <state bean-ref="..."/> 
  -->
        

The whole node is optional. If given, the class attribute must be the name of a java class implementing the de.schlund.pfixcore.workflow.ConfigurableState interface. The used State is determined as follows:

You can use the scope attribute to specify the scope in which the Spring bean created for this page will be instantiated. You may specify the bean-name attribute to use a fixed name for the automatically created bean. You can use any BSF-supported scripting language for writing your State-implementation, too. Use script:path/to/script for the class attribute. Alternatively you can use an existing Spring bean that implements the de.schlund.workflow.State interface. Use the bean-ref attribute to specify the name of the bean. However the pagerequest may not contain any configuration if you are using a Spring bean.

Note

If you're referencing a custom Spring bean using bean-ref, Pustefix can't automatically inject the configuration. So if you're bean is extending the DefaultIWrapperState or StaticState it might not work as you expected (or not at all) due to the lack of configuration. That's why Pustefix supports the referencing of parent bean definitions using the parent-bean-ref attribute. Thus it's possible to indirectly inject dependencies into the concrete instances by injecting them into the parent bean definition. So, despite the fact, that the beans are automatically created by Pustefix, you're able to inject your own dependencies using the Spring XML configuration.

      <input premvc="false|true" policy="ANY|ALL|NONE">
        

The whole node is optional. It may only be given for a State that is either de.schlund.pfixcore.workflow.app.DefaultIWrapperState or a descendent of it!

The attribute premvc is optional (default is false). It specifies if the IHandlers should be executed before a matching RequestMapping method is called (RequestMapping is called first by default).

The attribute policy is optional (default is ANY). The policy decides when a whole page is considered to be accessible:

If one of the associated handlers returns false on calling prerequisitesMet(), the page is of course still inaccessible.

        <wrapper prefix="AName" class="AClassName" checkactive="true|false" tenant="aTenant"/>
        

	Caution
	Note: The tag name wrapper can also be called interface with the same allowed attributes for backwards compatibility reasons. This ambiguity may be removed in some future version.

There can be many wrapper nodes for a page. Each one references an "atomic" functional entity consisting of an IWrapper java class (usually autogenerated from a .iwrp xml file that defines the type and names of the parameters passed between the UI and the functional entity and an associated IHandler java class that uses the IWrapper to retrieve the passed parameters via typed getter methods. There may be an optional scope attribute, which specifies the scope in which the handler associated with the wrapper will be instantiated.

Attribute	Description
prefix	Mandatory. The prefix defines a name for the IWrapper and in effect a namespace for the IWrapper's parameters. If the prefix "bar" is defined for an IWrapper that contains a parameter called "Foo", the submitted HTTP parameter must be called bar.Foo.
class	Mandatory. Must be the name of a java class implementing de.schlund.pfixcore.generator.IWrapper. This implicitly defines a de.schlund.pfixcore.generator.IHandler, as every IWrapper knows it's associated IHandler and can be queried for it.
checkactive	Optional, default is true. The IHandler method isActive() is NOT called on handlers with checkactive set to false. In other words: the handler is ignored when the system tries to find out if the page is accessible or not. See also the comment for the policy attribute above. Caution Replaces the activeignore attribute since version 0.13.1. You should be aware that setting activeignore to true now complies with setting checkactive to false. Support for the activeignore attribute will be removed in future versions.
tenant	Optional. Can be used to specify IWrappers for a certain tenant only.

      </input>
        

      <process>
        

The process node holds a list of actions, which can be referenced from the UI when submitting forms or using GET requests to transmitt data. These actions group IWrappers into two groups: those that should have their handleSubmittedData() method called, and those that should have their retrieveCurrentStatus() method called when a submit has been handled sucessfully (and the same page is redisplayed). The idea beind the latter is, that sometimes you want to update the submitted form data to some canonical form (e.g. adresses or similar), so you don't want to see the exact same input in the form elements as you have submitted it, but some changed values. In other cases, submitting data to one wrapper may change the values of the form elements of another wrapper - in this case the second wrapper needs to be listed under the <retrieve> node.

        <action name="a_name">
          <submit>
            <wrapper ref="a_prefix_1"/>
            <wrapper ref="a_prefix_2"/>
            ...
          </submit>
          <retrieve>
            <wrapper ref="a_prefix_1"/>
            <wrapper ref="a_prefix_X"/>
            ...
          </retrieve>
        </action>
        <action name="another_name">
        ...
        </action>
      </process>
      
      <output>
        

The whole node is optional. Every page using a State that is itself or a descendant of de.schlund.pfixcore.workflow.app.StaticState can use this. You can have as many resource childnodes as you like.

        <resource node="AName" class="AClassName"/>
        

      </output>
      
      <properties>
        

The whole node is optional.

        <prop name="APropertyKey">AValue</prop>
        

The node is mandatory and can be used multiple times. It will be transformed into a java property that is associated to the page. There are some props that are already defined for de.schlund.pfixcore.workflow.app.StaticState and descendants. These are listed below

      </properties>
    </pagerequest>
    
    <config-include file="conf/myfile.xml" section="pagerequests" module="mymodule"/>
        

Includes a part of a config fragments file at this location. See Section 4.3.8, “Configuration Fragments” for details on how to define config fragments.

One and only one of the section, refid or xpath attribute has to be specified for each config-include.

    <properties>
      <prop name="AProperty">AValue</prop>
        

You can also specify properties here that are understood by the AbstractPustefixRequestHandler and AbstractPustefixXMLRequestHandler classes.

    </properties>
  </context-xml-service-config>
        

Occasionally you don't want to generate output with an XSLT Transformation, but e.g. deliver binary content directly to the output stream instead. In this case you can use the DirectOutputService. The name of the configuration file can be arbitrarily chosen and is configured in the project configuration file.

The service knows about one or many directoutputpagerequests. For the XML/XSLT side of things, they look like normal pages (in fact, the value of the directoutputpagerequest's name attribute must be a page defined in the navigation section of depened.xml. Of course, no target definition has to be given, only the page in the navigation structure must exist). But other than the usual pagerequest, a directoutputpagerequest has an associated directoutputstate whose class attribute is a java class implementing de.schlund.pfixcore.workflow.app.DirectOutputState.

  <direct-output-service-config
    xmlns="http://pustefix.sourceforge.net/2004/properties"
  >    
    <global-config>
      <force-ssl>false</force-ssl>
        

See the comment for the global-config node in Section 4.3.5, “ContextXMLService configuration file”.

    </global-config>
    
    <authconstraint ref="AN_AUTHCONSTRAINT"/>
         

You can reference an authconstraint from the context configuration, which has to be fulfilled to access a page. This default authconstraint can be overridden for single pages. If no default authconstraint is set here, the context's default authconstraint will be used. If no authconstraint is set at all, a page requires no authentication.

    <config-include file="conf/myfile.xml" section="directoutputpagerequests" module="mymodule"/>
         

Includes a part of a config-fragments at this location. See Section 4.3.8, “Configuration Fragments” for details on how to define config fragments.

One and only one of the section, refid or xpath attribute has to be specified for each config-include.

    <directoutputpagerequest name="APageName">
      <directoutputstate class="AClassName"/>
        

The class specified for the directoutputstate must implement the de.schlund.pfixcore.workflow.DirectOutputState interface. The tag may have an optional scope attribute which specifies the scope in which the corresponding state should be instantiated. There may also be an optional bean-name which, if present, will be used as the name of the Spring bean created for this direct output state. Instead of the class attribute, you may specify a bean-ref attribute which has to reference a Spring bean defined in the spring.xml file for this project. In this case, no Spring bean will be created but the existing bean will be used instead.

      <authconstraint ref="AN_AUTHCONSTRAINT"/>
        

You can optionally reference an authconstraint from the context configuration to override the default authconstraint.

      <properties>
        

The whole properties node is optional.

        <prop name="APropertyKey">AValue</prop>
        

The node is mandatory and can be used multiple times. It will be transformed into a java property that is associated to the page. The java property that is constructed will look like this: pagerequest.APpageName.APropertyKey=AValue where APageName is the value of the name attribute.

      </properties>
    </directoutputpagerequest>
  </direct-output-service-config>
        

The configuration of AJAX / webservices is described in the corresponding section.

Configuration fragments files contain aggregated configuration directives that are intended to be reused in different configuration files.

<fr:config-fragments
  xmlns:fr="http://pustefix.sourceforge.net/configfragments200609"
  xmlns:c="http://www.pustefix-framework.org/2008/namespace/context-xml-service-config"
  xmlns:d="http://www.pustefix-framework.org/2008/namespace/direct-output-service-config"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://pustefix.sourceforge.net/configfragments200609
                      http://pustefix.sourceforge.net/configfragments200609.xsd">
  
  <fr:navigation id="nav1">
      

All sections have an optional id that can be used to identifiy the section when more than one section fo the same type is present in one file. The value of the id attribute has to be unique within the whole file.

    <page name="MyPage"/>
      

The structure here is the same as within the navigation tag of the depend.xml file.

  </fr:navigation>
  <fr:targets>
    <standardpage name="MyPage" xml="xml/mymaster.xml"/>
      

The tags allowed here are the same that are allowed for standardpage or target definitions in the depend.xml file.

  </fr:targets>
  <fr:resources>
    <c:resource class="com.example.MyResourceImpl">
      <pr:implements class="com.example.MyResource"/>
    </c:resource>
      

The tags allowed here are the same that are allowed for the definition of context resources within the context tag of the ContextXMLServlet configuration.

  </fr:resources>
  <fr:interceptors>
    <c:interceptor class="com.example.MyInterceptor"/>
      

The tags allowed here are the same that are allowed within the start, end and postrender interceptor tags of the ContextXMLServlet configuration (for details also see Section 6.6, “ContextInterceptors”).

  </c:interceptors>
  <fr:scriptedflows>
    <c:scriptedflow name="myscript" file="myproject/conf/scriptedflows/myscript.script.xml"/>
      

The tags allowed here are the same that are allowed within the scriptedflows tag of the ContextXMLServlet configuration.

  </fr:scriptedflows>
  <fr:roles>
    <c:role name="MY_ROLE">
      <c:pageaccess names="mypage*"/>
    </c:role>
      

The tags allowed here are the same that are used for role definition in the ContextXMLServlet configuration.

  </fr:roles>
  <fr:pageflows>
    <c:pageflow name="MyFlow">
      <c:flowstep name="MyFirstPage"/>
      <c:flowstep name="MySecondPage"/>
    </c:pageflow>
      

The tags allowed here are the same that are used for the definition of pageflows in the ContextXMLServlet configuration.

  </fr:pageflows>
  <fr:pagerequests>
    <c:pagerequest name="MyPage"/>
      

The tags allowed here are the same that are used for the definition of pagerequets in the ContextXMLServlet configuration.

  </fr:pagerequests>
  <fr:properties>
    <pr:prop name="myproperty">myvalue</pr:prop>
      

The tags allowed here are the same that are allowed within the properties tag of the ContextXMLServlet configuration.

  </fr:properties>
  <fr:directoutputpagerequests>
    <d:directoutputpagerequest name="foo">...</d:directoutputpagerequest>
      

Direct output pagerequests can be defined here. See Section 4.3.6, “DirectOutputService configuration file” for details on this.

  </fr:directoutputpagerequests>
</fr:config-fragments>
        

Spring supports the externalization of property values from Spring XML configuration files into separate standard Java property files. Pustefix extends this mechanism by adding support for the Pustefix XML property file format, which let's you use the choose/when-customization known from other Pustefix configuration files, like factory.xml, for Spring properties too.

Therefor Pustefix by default registers a Spring PropertyPlaceholderConfigurer, which looks for a Pustefix XML property file under WEB-INF/spring-properties.xml and a PropertyOverrideConfigurer, which looks under WEB-INF/spring-properties-override.xml.

The following example shows the two ways you can externalize property values:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans">

  <bean id="mybean1" class="mypackage.MyBeanClass">
    <property name="text" value="${default.text}"/>
  </bean>

  <bean id="mybean2" class="mypackage.MyBeanClass">
    <property name="text" value="This is the default text"/>
  </bean>

</beans>

The first bean uses a property placeholder, the second bean already supplies a default value, which should be overwritten by an externalized value.

The following spring-properties.xml file configures the value for the first bean using the Pustefix customization mechanism to provide a mode-dependent value for the property placeholder:

<?xml version="1.0" encoding="UTF-8"?>
<properties xmlns="http://www.pustefix-framework.org/2008/namespace/properties-config" 
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://www.pustefix-framework.org/2008/namespace/properties-config 
                                http://www.pustefix-framework.org/schema/properties-config.xsd">    
    <choose>
      <when test="$mode='prod'">
        <property name="default.text">I'm in production mode</property>
      </when>
      <otherwise>
        <property name="default.text">I'm in development mode</property>
      </otherwise>
    </choose>

</properties>

The following spring-properties-override.xml file overrides the value for the second bean by using the format beanName.property as property name. It also shows how you can use the available environment properties (like fqdn or mode) within a property value:

<?xml version="1.0" encoding="UTF-8"?>
<properties xmlns="http://www.pustefix-framework.org/2008/namespace/properties-config" 
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://www.pustefix-framework.org/2008/namespace/properties-config 
                                http://www.pustefix-framework.org/schema/properties-config.xsd">
    
    <property name="mybean2.text">I'm in ${mode} mode</property>

</properties>

If you want to register your own PropertyPlaceholderConfigurer or PropertyOverrideConfigurer capable of the Pustefix XML property format, e.g. for tests or child ApplicationContexts, you can do so by creating a PustefixPropertiesPersister bean and referencing it from the configurer's propertiesPersister property.

Pustefix provides a special PropertyPlaceholderConfigurer implementation which can be used to organize properties in own files for each environment, e.g. based on the mode value. You can enable it by adding an according bean definition to the Spring configuration.

<bean id="propConfig" class="org.pustefixframework.container.spring.util.EnvironmentPropertyPlaceholderConfigurer"/>

By default properties will be loaded from WEB-INF/spring.properties and WEB-INF/spring-[MODE].properties, whereas [MODE] will be replaced by the current value of the according context init parameter and mode specific properties will override the general ones.

Here's an example of a more complex non-default configuration, where properties are loaded from multiple locations using multiple context init parameters as discriminator:

<bean id="propConfig" class="org.pustefixframework.container.spring.util.EnvironmentPropertyPlaceholderConfigurer">
  <!-- optional property, default: WEB-INF/spring.properties -->
  <property name="locations">
    <list>
      <value>classpath*:spring.properties</value>
      <value>WEB-INF/spring.properties</value>
    </list>    
  </property>
  <!-- optional property, default: mode -->
  <property name="parameters">
    <list>
      <value>mode</value>
      <value>locale</value>
    </list>
  </property>
</bean>

If the mode param value will be test and locale will be set to en_US, the properties will be loaded from the following locations (same properties in files loaded later will override already read properties, i.e. have higher precedence).

Pustefix by default activates a Spring profile for the current execution environment mode (using the mode name as profile name). Thus you can easily use bean definition profiles or @Profile Java configuration without having to take care of the profile activation.

<beans xmlns="http://www.springframework.org/schema/beans">
   
   <bean name="mybean" class="mypackage.MyBean"/>

   <beans profile="prod">
      <bean name="mybean" class="mypackage.MyBeanAlternative"/>
   </beans>

</beans>

Some Spring beans created by the core framework are intended for usage by the application, i.e. are registered with fixed/reserved bean names, which can be referred to inject them into application beans. The following table shows those beans with their associated names and aliases.

For a html delivering page without frames:

<pfx:document xmlns:pfx="http://www.schlund.de/pustefix/core">
  <html>
    <!--
      Any content valid for an html document
    -->
  </html>
</pfx:document>

If you don't want to deliver html, just omit the <html> tag. The following could be used to implement a CSS stylesheet.

<pfx:document>.foo { color: #ffff00; font-family: Helvetica; }</pfx:document>

The rule of thumb is: Whatever you put between <pfx:document> is up to you and will be delivered just as you write it there. Just remember that the <html> is not automatically inserted for you, you have to write it yourself.

There are only subtle differences. A document is a Type 2 doc by definition whenever there is a <pfx:frameset> and possibly a <head> node as the only direct children of <pfx:document>.

<pfx:document xmlns:pfx="http://www.schlund.de/pustefix/core">
  <head>
    <!--
      Again, put anything you want to appear in the head of the _top frame! This means
      page title, script stuff or stylesheets.
    -->
  </head>
  <pfx:frameset rows="20,*">
    <pfx:frame name="navi">
      <html>
        <head>...</head>
        <body>
          <!-- Any HTML content -->
        </body>
      </html>
    </pfx:frame>
    <pfx:frame name="main">
      <html>
        <body>
          <!-- Any HTML content -->
        </body>
      </html>
    </pfx:frame>
  </pfx:frameset>
</pfx:document>

As you can see there is NO <html> tag just below <pfx:document>. This is the one important difference between Type 1) and Type 2). As a rule you could say that you only have to insert the <html> yourself wherever the "real" content is. In a Type 1) doc this is the whole content of the <pfx:document> tag, so we need to set it there. But for a Type 2) doc, the "real" content is the content of the <pfx:frame> tags, so you need to set it there.

The <pfx:button> tag is responsible for generating links to other pages inside the pustefix environment. In fact, it not always creates a link, but depending on the fact if the target page is accessible ("invisible") or not, or if the target page is the same as the current page ("active", aka "the target page is already active") it can display completely different content, and only when the target page is accessible and is different from the current page, a <a href="...">...</a> is put around it.

The template takes care of constructing the correct url with session information embedded and builds up valid, url encoded query strings.

<pfx:button page="APage" pageflow="AFlow" jumptopage="APage" jumptopageflow="AFlow" 
            forcestop="true|false|step" startwithflow="true|false" altkey="pageAlternativeKey" path="sub/path">
  <!-- Control the submit commands -->
  <pfx:command page="APage" name="SUBWRP">prefix</pfx:command>

  <!-- Supply additional parameters -->
  <pfx:argument name="AName">AValue</pfx:argument>
  
  <pfx:anchor frame="AFrame">AnAnchor</pfx:anchor>
  
  <!-- Select a page at runtime -->
  <pfx:page>pageName</pfx:page>

  <!-- Select a page alternative by key --> 
  <pfx:altkey>pageAlternativeKey</pfx:altkey>

  <!-- Set page-relative URL sub path (suffixing the display page name). Segments are URI-encoded automatically. -->
  <pfx:path>sub/path</pfx:path>
  <pfx:path>
    <pfx:segment>sub</pfx:segment>
    <pfx:segment>path</pfx:segment/>
  </pfx:path>

  <!--
    These three optional child nodes can be used to display different
    content depending on the situation:
  -->
  <pfx:invisible>
    <!-- Displayed when link is not accessible -->
  </pfx:invisible>
  <pfx:normal>
    <!-- Displayed when link is accessible -->
  </pfx:normal>
  <pfx:active>
    <!-- Displayed when current page == link target -->
  </pfx:active>
  <!--
    Displayed link content
  -->
</pfx:button>

The <pfx:button> tag supports the following attributes:

Link contents

The pfx:button template allows you to change the link content depending on the status of the target page.

• Content of pfx:invisible will be only displayed when the target page is not accessible.

• Content of pfx:active will be only displayed when the target page is the current page.

• Content of pfx:normal will be only displayed when the target page is different from the current page and when it's accessible.

Content outside of these tags will be used in any case. If you only want to have different content for the invisible case, just put the content for the active and normal case inside pfx:normal, and add a pfx:invisible child with the differing content. The content of a pfx:normal node serves as the fallback for the other two cases.

	Note
	Note that only in the normal (regardless if the content comes from a dedicated pfx:normal child node or not) a link is put around the generated content.

Note also, that for differences between the three cases that can be expressed with CSS, you don't need to use these special child nodes. The system makes sure to use the three associated classes explained above to allow styling.

It is also possible to change to content, depending on whether a page has already been visited or not.

• Content of pfx:visited will be only displayed when the link has been already visited at least once in this session.

• Content of pfx:visited will be only displayed when the link has not been visited in this session.

The two tags above may also be put inside pfx:normal and pfx:invisible tags to express different content for accessible (or inaccessible) pages depending on the fact if they have been visited at least once already.

This makes of course not much sense with pfx:active, because a page where this applies is always the current page and by that is always visited.

This tag takes mostly the same attributes as <pfx:button>, but it only creates the URL and does not build up any content or generate a whole link. You can use this template if you just need the pure URL string.

When creating links to external URLs care must be taken to ensure that no sensitive data (especially the session ID) leaks into log files of remote servers via the referer header. To make sure that this can't happen, all links to external sites must be propagated via a special servlet, the de.schlund.pfixxml.DerefServer.

Every Pustefix project has this servlet configured to be accessible under the path /deref. To make the handling of external URLs easier, there also exists a special tag <pfx:elink> that automates the creation of the correct link.

<pfx:elink href="http://some.host/location" target="_popup|SomeName">
  <!--
    Optional, use the <pfx:host> child instead of the href attribute whenever you
    need to construct the URL with additional code (e.g. from data only available
    at runtime)
  -->
  <pfx:host>...</pfx:host>

  <!--
    Optional, use as many of <pfx:argument> tags as you need to supply the
    parameters for the query string.
  -->
  <pfx:argument name="SomeName">...</pfx:argument>

  <!--
    Place content of the link here
  -->
</pfx:elink>

Include parts contain the content that is displayed on your pages. The parts are organized into include files. Every part has the same structure:

The children of the part tag are theme tags (at least one). The name attribute of the theme tag is the name of a theme as it is defined in the projects depend.xml.in file. Often these themes are just the project name or "default", which is used as the fallback when no more specific theme name matches (see here on how to define themes in the depend.xml.in file).

	Note
	Earlier versions of Pustefix had no special themeing, the only thing that was used was the project name itself and "default" as the fallback. Still today, the default value for the "themes" attribute in the root node of the depend.xml.in file (when not given explicitely) is just "<ProjectName> default", which makes the new system behave exactly as the old one did.

The resolution of the matching theme is done at the time the part is included (see below). Every page "knows" which themes are defined for it, and therefore it is possible to decide which product branch to use on generation time. The language on the other hand can be changed dynamically while the user clicks through the application, so the selection of the right language subtree (if more than one is present) is done at runtime.

<include_parts>
  <part name="Foo">
    <theme name="default">
      <pfx:langselect>
        <pfx:lang name="default">
          <!--
            The default content of part Foo goes here...
          -->
        </pfx:lang>
        <pfx:lang name="en_GB">
          <!--
            Default content in british english goes here...
          -->
        </pfx:lang>
        <pfx:lang name="en_*">
          <!--
            Default content in any other english language goes here...
          -->
        </pfx:lang>
      </pfx:langselect>
    </theme>
    <theme name="Theme_A">
      <!--
        The default content for theme Theme_A goes here...
      -->
    </theme>
  </part>

  <part name="Baz">
    <!-- Other parts -->
  </part>
</include_parts>

A part is referenced with two attributes: The filename of the include file that contains it, and the name of the part. The filename can be omitted, if you're referencing a part within the same file.

<pfx:include href="MyProject/txt/MyIncludefile" part="Foo" noerror="true|false" noedit="true|false"/>

Using this tag results in the matching product branch of the include part to be inserted in place of the tag.

If you're deferring an include until runtime using level="runtime", you can also defer the creation of the href and part values until runtime using the pfx:href and pfx:part tags instead of the according attributes. The following example shows how to use values coming from the DOM result tree:

<pfx:include level="runtime">
  <pfx:href><ixsl:value-of select="/formresult/mypartinfo/@myhref"/></pfx:href>
  <pfx:part><ixsl:value-of select="/formresult/mypartinfo/@mypartname"/></pfx:part> 
</pfx:include>

	Note
	You should be aware that parts included at runtime aren't transformed with the master.xsl stylesheet, i.e. if the included part contains Pustefix tags (forms, buttons, etc.) they won't work. So the runtime inclusion is primarily intended for including simple text/HTML content.

Looking at the example naturally leads to the question how it is possible to generate different pages with only a small number of structural xml files and always the same XSLT stylesheets. The answer is that at least one of the include parts isn't included via the pfx:include tag (which only handles static attribute values) but instead the filename of the include part is auto generated from the name of the page that is to be produced.

Looking at this page, one can see that the two transformations which produce BazPage.xml resp. BazPage.xsl have the page name supplied through the use of an XSLT transformation parameter. Using this parameter, the tag pfx:maincontent constructs an include request depending on the page name.

<pfx:maincontent part="content" path="MyProject/txt/pages" prefix="main_"/>

For the page "home" this is equivalent to <pfx:include href="MyProject/txt/pages/main_home.xml" part="content"/> and of course similar for every other page.

Starting with this page specific include, the content of the page can be included from many different include parts.

HTML <img> tags are usually not written directly, instead they are generated by using the <pfx:image> tag. Using this tag makes sure that the used image is registered in the runtime system as a dependency of the current target that's being generated.

One important feature of the <pfx:image> tag is that it inserts the natural height and width of the requested image unless they are explicitely given (as attributes width and height of course).

<pfx:image src="some/path/to/img.gif" themed-path="some/path" themed-img="img.gif"/>

If you're including an image at runtime using level="runtime", you can also defer the creation of the src, alt, themed-path and themed-img values until runtime using the pfx:src, pfx:alt, pfx:themed-path and pfx:themed-img tags instead of the according attributes. The following example shows how to use values coming from the DOM result tree:

<pfx:image level="runtime">
  <pfx:src><ixsl:value-of select="/formresult/myimginfo/@mysrc"/></pfx:src>
  <pfx:alt><ixsl:value-of select="/formresult/myimginfo/@myalt"/></pfx:alt> 
</pfx:image>

Include parts can be also rendered standalone and included at runtime/rendering time on the last transformation level. Thus you can include parts dynamically, e.g. you can include a part based on information from the result tree, which isn't available on the former transformation levels. This can also help to keep your stylesheets small, but it also has some drawbacks: standalone rendering of a part costs more time than doing a regular include and the XML source context node can only be relative if the part is rendered within the main transformation, and not standalone, e.g. triggered by an AJAX call.

Render includes are done using the <pfx:render> tag. Its syntax is similar to <pfx:include>. But referenced parts additionally have to be marked as render parts using the render attribute. You can optionally specify in which variants a render part should be available. All this is necessary to know which parts can be invoked dynamically when pre-generating all pages for production environments. Setting the contextual attribute to true you can specify that a part is context-dependent, meaning that the initial context node for the transformation will be set to the current context node of the main transformation.

<include_parts>
  <part name="Foo" render="true" render-variants="foo foo:bar:baz" contextual="true">
    <theme name="default">
      ...
    </theme>
  </part>
</include_parts>

A part is referenced with at least a part attribute. The path to the include file can be omitted if you're referencing a part within the same file. Using module and/or search you can reference parts from modules or do dynamic lookups.

<pfx:render href="txt/common.xml" part="Foo"/>

Render include parts not just can be rendered as part of another page within the main transformation, but they can be also rendered standalone. Therefor Pustefix provides a Javascript API which lets you easily request a part via AJAX.

<script type="text/javascript" src="{$__contextpath}/modules/pustefix-core/script/httpRequest.js"></script>
<script type="text/javascript" src="{$__contextpath}/modules/pustefix-core/script/render.js"></script>

<script type="text/javascript">

   function callback(result) {
      document.getElementById("result").innerHTML = result;
   }

   function errorCallback(res) {
      if(res.status == 403) {
         window.location.reload();  
      } else {
	 //do something else
      }
   }

   function test() {
      // Remotely renders an include part and passes the output to a callback function.
      // Arguments can be passed as list (deprecated) or as single JSON object argument:
      //   href          - path to include file
      //   part          - include part name
      //   module        - module name (optional)
      //   search        - search type (optional)
      //   callback      - callback function (optional)
      //   context       - callback object scope (optional)
      //   requestId     - request/response assignment id (optional)
      //   params        - additional request parameters (optional)
      //   requestPath   - alternative request URL path (optional)
      //   errorCallback - callback function for HTTP errors (optional)
      // Deprecated version:
      //   pfx.render("txt/common.xml", "Foo", "", "", callback, null, "1", null, null, errorCallback);
      // Recommended version:
      var args = { "href": "txt/common.xml",
                   "part": "Foo", 
                   "callback": callback, 
                   "requestId": "1", 
		   "errorCallback": errorCallback };
      pfx.render(args);

      // you can alternatively set a global error function which is called
      // for all HTTP request errors in the abscence of a specific funtion:
      pfx.net.HTTPRequest.errorCallback = function(res) { alert(JSON.stringify(res)); };
   }
</script>

The <pfx:checkinclude> and <pfx:checknoinclude> tags can be used to display content depending on the existence of an include part.

<pfx:checkinclude part="foo" href="txt/afile.xml">
  Display if part exists
</pfx:checkinclude>

<pfx:checknoinclude part="bar" href="txt/afile.xml">
  Display if part not exists
</pfx:checknoinclude

<pfx:checkinclude href="txt/afile.xml" module="amodule" search="dynamic" level="runtime">
  <pfx:part><ixsl:value-of select="/formresult/displaypart/@name"/></pfx:part>
  Display if part exists
</pfx:checkinclude>

Supported attributes and usage comply with the <pfx:include> element (see Section 5.3.1, “Include parts (<pfx:include>)”).

When including a part using <pfx:include>, you can pass parameters, which will be available within the templates applied during the current XSL transformation.

An include parameter can be passed by adding an according <pfx:includeparam> child element to the <pfx:include> element. The syntax is similar to XSL template parameters.

<pfx:include part="foo">
  <pfx:includeparam name="myparam">myvalue</pfx:includeparam>
  <pfx:includeparam name="another" select="/xpath/expression"/>
  <pfx:includeparam name="xmlparam" tunnel="yes">
     <item id="foo"/>
     <item id="bar"/>
  </pfx:include>
</pfx:include>

Include parameter values can be simple strings, nodesets or evaluation results of XPath expressions. Include parameters can be tunneled, i.e. you can pass parameters to nested includes without having to newly declare the parameter on each include level.

Within the included part you can access passed include parameters by declaring them at the top of the part. Like with XSL parameters, you can just declare empty parameters, set default values or mark a parameter as tunneled (without marking it, it will be overlaid).

<part name="hey">
  <theme name="default">
    <pfx:includeparam name="myparam"/>
    <pfx:includeparam name="another">default</pfx:include-param>
    <pfx:includeparam name="xmlparam" tunnel="yes"/>

Having declared an include parameter, you can use one of Pustefix's builtin templates to operate on this parameter, e.g. write its value, iterate over its value or check a condition against it. You can not only reference the parameter itself, but write complex XPath expressions.

<pfx:value-of select="$myparam"/>
<pfx:value-of select="concat($myparam,'xyz')"/>

<pfx:for-each select="$xmlparam/item">
  <pfx:value-of select="@id"/>
</pfx:for-each>

<pfx:if test="$another='...'">...</pfx:if>

<pfx:choose>
  <pfx:when test="$another='...'">...</pfx:when
  <pfx:otherwise>...</pfx:otherwise>
</pfx:choose>

Basically these tags are working similar to the according XSLT base tags, i.e. the templates matching these tags, are internally calling the suitable XSLT statements. But you have to be aware that there's a difference between applying templates on XML tags and directly executing XSLT statements. Here's the list of all supported tags:

Besides these special templates some of Pustefix's core templates also have support for include parameters, i.e. the according elements provide attributes which support include parameters or XPath expressions. Usually these attributes are prefixed with select-.

<pfx:include select-href="$myparam" select-part="concat($anotherparam,'xyz')"/>

<pfx:checkinclude select-part="$myparam" select-href="..."/> 

<pfx:checknoinclude select-part="$myparam" select-href="..."/> 

<pfx:image select-src="$myparam" select-alt="..."/>

Messages can be displayed using the <pfx:message> tag. You need to specify a key referencing the message ID (or property key in terms of property files).

<pfx:message key="my.message.key"/>

Messages can have arguments which are passed using <pfx:arg> tags. Pustefix automatically fills them in at the specified position (denoted by the message string placeholders {0}, {1}, etc.).

<pfx:message key="my.message.key">
   <pfx:arg>my argument</pfx:arg>
   <pfx:arg>another argument</pfx:arg>
</pfx:message>

If the message string contains markup or you're passing markup as argument, you have to set the attribute disable-output-escaping to yes, if you want to render the markup without escaping it:

<pfx:message key="my.message.key" disable-output-escaping="yes">
   <pfx:arg><pfx:button page="test">testlink</pfx:button></pfx:arg>
</pfx:message>

Besides the message arguments, the message key itself can be set at runtime, e.g. for dynamically including messages based on values from the DOM tree:

<pfx:message>
   <pfx:key><ixsl:value-of select="/formresult/path/to/@messageid"/></pfx:key>
</pfx:message>

Using the <pfx:checkmessage> and <pfx:checknomessage> tags you can check if a message is existing or not:

<pfx:checkmessage key="my.message.key">
   <!-- Apply if message exists -->
</pfx:checkmessage>
<pfx:checknomessage key="my.message.key">
   <!-- Apply if message not exists -->
</pfx:checknomessage>
<pfx:checkmessage key="my.message.key">
   <pfx:checkpassed>
      <!-- Apply if message exists -->
   </pfx:checkpassed
   <pfx:checkfailed>
      <!-- Apply if message not exists -->
   </pfx:checkfailed>
</pfx:checkmessage>

The MessageSource can either be configured using Spring means, or, as recommended, within the Pustefix project configuration (which makes it available during pre-generation of the pages too).

You can specify one or more MessageSources (the latter ones will serve as parent MessageSource for the former ones). For each MessageSource you have to specify its type (po or properties) and one or more basenames.

<messagesources>
   <messagesource type="po">
      <basename>module://common-module/i18n/messages</basename>
      <basename>module://common-module/i18n/errors</basename>
   </messagesource>
   <messagesource type="properties" basename="/WEB-INF/messages"/>
</messagesources>

According to the specified type and selected locale Pustefix will look up the messages in all matching files, e.g. for the locale en_UK starting with messages_en_UK.po, messages_en.po and messages.po, whereas messages in previous files (previous basename or MessageSources) override later ones.

Messages in property or po files should conform to the Java java.text.MessageFormat standard, see the following examples:

#Sample property file
my.message.key=My message text
another.key=Message text with arguments {0} and {1}

#Sample po file
msgid "my.message.key"
msgstr "My message text"
msgid "another.key"
msgstr "Message text with arguments {0} and {1}"

The creation of a html form is done with the help of the tag <pfx:forminput>. Most often you don't need to set any attributes, the defaults should work just fine.

<pfx:forminput send-to-page="APage" send-to-pageflow="APageFlow" frame="AFrameName" target="ATargetName" type="auth|data">
  <!-- place form elements here -->
</pfx:forminput>

Pustefix usually by default generates some hidden fields which are placed directly under the HTML form tag, but you can explicitely control where Pustefix should place the fields using the <pfx:hiddenfields/> element.

<pfx:forminput>
  <div>
    <pfx:hiddenfields/>
  </div>
</pfx:forminput>

Make sure that all the other form related tags detailed below are contained inside a pfx:forminput block.

The form can be submitted by clicking on submit controls which can be realized in two ways: The simple html submit button is made with the tag <pfx:xinp type="submit">, while using an image as the submit control is done with <pfx:xinp type="image">.

A very useful ability of both submit controls is that it's possible to attach additional form parameters to them, that are only transmitted when that exact submit control is pressed. This way it's possible for a form to have two or more submit controls, each with different additional data attached and submitted, depending on which submit control the user clicks on.

<pfx:xinp type="submit|image" pageflow="APageFlow" jumptopage="APage" jumptopageflow="APageFlow" forcestop="true|false|step">
  <!--
    Attach additional information to the controls
  -->
  <pfx:command page="APage" name="SUBWRP">prefix</pfx:command>
  <pfx:argument name="AName">AValue</pfx:argument>
  <pfx:anchor frame="AFrame">AnAnchor</pfx:anchor>
</pfx:xinp>

When setting the type to image, you may also specify the attributes src, themed-path, themed-img, search and module. These attributes work exactly as described in Section 5.3.3, “Displaying images (<pfx:image>)”.

You can alternatively use the pfx:submitbutton tag to produce a button element instead of an input element. The button elements are more flexible than the traditional input elements, but are not supported by some old browsers.

<pfx:submitbutton pageflow="APageFlow" jumptopage="APage" jumptopageflow="APageFlow" forcestop="true|false|step">
      <!-- you can put additional stuff here as described above, but in contrast to the traditional
           submit element you can also have content (like text or images) here -->
</pfx:submitbutton>

Command controls (like described in Section 5.5.2, “Submitting forms”) and links (like described in Section 5.2.1, “pfx:button”) can contain child tags that are used to pass additional data when the link or button is clicked.

<pfx:anchor frame="AFrame">AnAnchor</pfx:anchor>

<pfx:argument name="AName">AValue</pfx:argument>

<pfx:argument name="foo"><ixsl:value-of select="/formresult/bar"/><pfx:argument>

Commands

The <pfx:command> tag can be used to explicitly select the wrappers on a page, which should be used for handling the submitted data or retrieving the updated data after a successful submit.

 <pfx:command page="APage" name="SUBWRP|RETWRP">prefix</pfx:command>

The content gives the prefix of the wrapper to select as defined on the target page.

Note

If you don't give any selected wrappers for submit handling (SUBWRP), all wrappers defined on the target page become selected for submit handling. If you don't give any selected wrappers for retrieving data after successful submits (RETWRP), no wrappers are selected for retrieving data. It's recommended to use actions instead of commands. Actions let you define the selected wrappers within the configuration, which is a much cleaner approach.

Table 5.11. Attributes of pfx:command

Attribute name	Mandatory?	Description
name	mandatory	The name of the command. Currently, the supported commands are SUBWRP, RETWRP and the deprecated SELWRP, which is an equivalent of SUBWRP and only supported for backwards compatibility. All commands select a wrapper with the matching prefix on the page that is designated by the page attribute (or the current page, when empty). SUBWRP selects a wrapper that should be used for handling the data that is submitted. RETWRP selects a wrapper whose data should be retrieved/updated after a successfull submit. You can use more than one pfx:command to select as many wrappers as you want. Note: As the recommended way to select wrappers for submitting/retrieving data is the action mechanism, it is possible that the whole pfx:command stuff will go away in future releases.
page	optional	Most often empty. This should be set to the page the request is directed at if it's not the current page.

Using these form element tags ensures that values, that are supplied by the backend application are used as values for the generated html form elements. This is done dynamically by generating the necessary ixsl: statements that will check the DOM tree for matching values and adding them as value attributes (text, password and hidden input fields) or content (text areas) or selecting them according to their value (check boxes, radio boxes, option menus).

Another thing these tags do is to automatically check if the runtime DOM tree contains an error attached to their name. In this case, the resulting html input field is augmented with special CSS classes to help with styling these fields depending on the state they have (error/no error).

Typically the CSS used when no attached error is detected is just the value of a class attribute given to the pustefix input tag. On the other hand, if an error is attached, the class attribute looks like this:

[@class] PfxError PfxInputTextError [PfxErrorLevel_$level]

where @class is the user supplied class attribute mentioned above (if it's there at all) and $level is an optional attribute of the error element in the runtime DOM tree. The example works the same for other input fields of the form <input type="...">, by replacing "Text" with "Password", "Check" or "Radio" (Hidden input fields are not visible anyway. Select menus and text areas don't need a special class as they can be easily selected via CSS rules. For the last two, the error CSS looks like this:

[@class] PfxError [PfxErrorLevel_$level])

<pfx:xinp type="text" name="AName" default="AValue" position="1|..|n" class="ACssClass">
  <!--
    name and default can also be set at runtime
  -->
  <pfx:default>
    <ixsl:value-of select="/some/runtime/value"/>
  </pfx:default>
  <pfx:name>
    <ixsl:value-of select="/some/runtime/name"/>
  </pfx:name>
 </pfx:xinp>

<pfx:xinp type="radio|check" name="AName" value="AValue" default="true|false" class="ACssClass">
  <pfx:name>
    <ixsl:value-of select="/some/runtime/name"/>
  </pfx:name>
  <pfx:value>
    <ixsl:value-of select="/some/runtime/value"/>
  </pfx:value>
  <pfx:default>
    <ixsl:value-of select="/runtime/true/or/false"/>
  </pfx:default>
</pfx:xinp>

<pfx:xinp type="select" name="AName" class="ACssClass" multiple="true|false">
  <pfx:name>
    <ixsl:value-of select="/some/runtime/name"/>
  </pfx:name>

  <!--
    One option tag per option that is available in the menu
  -->
  <pfx:option value="AValue" default="true|false">
    <pfx:value>
      <ixsl:value-of select="/some/runtime/value"/>
    </pfx:value>
    <pfx:default>
      <ixsl:value-of select="/runtime/true/or/false"/>
    </pfx:default>
  </pfx:option>
</pfx:xinp>

Errors in Pustefix come in two variants:

<pfx:checkerror level="ALevel" prefix="APrefix" name="APrefixedName" trigger="direct|flow|submit">
  <!--
    Content to be displayed when any error with the matching level, prefix or name attribute is present in the
    runtime DOM tree. All attributes are optional, without restricting attributes, any error will trigger
    the display of the content of the pfx:checkerror tag. If a trigger attribute is set, the content will be only
    displayed if the trigger causing the DOM creation matches the attribute value.
  -->
</pfx:checkerror>

<pfx:checknoerror level="ALevel" prefix="APrefix" name="APrefixedName" trigger="direct|flow|submit">
  <!-- 
    Inverted semantics as pfx:checkerror: content is displayed if no errors (matching the optional conditions) are found.
  -->
</pfx:checknoerror>

<pfx:checkfield name="prefix.Name">
  <pfx:error>
    <!--
      Content that's displayed when an error associated to the form field referenced
      in the name attribute is present in the runtime DOM tree.
    -->
  </pfx:error>
  <pfx:normal>
    <!--
      Content that's displayed when no error associated to the form field referenced
      in the name attribute is present in the runtime DOM tree.
    -->
  </pfx:normal>
  <!--
    Content outside of the two child nodes is displayed in both cases.
  -->
</pfx:checkfield>

<tr>
  <pfx:checkfield name="addr.Street">
    <td class="{$pfx_class}">Street:</td>
  </pfx:checkfield>
  <td><pfx:xinp type="text" name="addr.Street"/></td>
</tr> 
<pfx:checkfield name="addr.Street">
  <pfx:error>
    <tr>
      <td colspan="2" class="{$pfx_class}">
        <ixsl:apply-templates select="$pfx_scode"/>
      </td>
    </tr>
  </pfx:error>
</pfx:checkfield>

<pfx:checkmessage level="AString">
  <!--
    Content to be displayed when any page message with the matching level attribute is
    present in the runtime DOM tree. The level attribute is optional, when it's missing,
    any page message will trigger the display of the content of the pfx:checkmessage tag.
  -->
<pfx:checkmessage>

<pfx:checkmessage level="AString">
  <pfx:messageloop>
    <!--
      This content is repeated for all the page messages that match the restrictions imposed by
      the parent's level attribute (or all page messages, if the attribute isn not given).
    -->
  </pfx:messageloop>.
</pfx:checkmessage>

You may face situations where you want to prevent, that the same form is submitted multiple times (e.g. by double-click, back button) or that a form, opened in a new window/tab, but already opened in another window/tab, can still be submitted from the old window/tab.

Using the <pfx:token> tag a hidden field with a random token is included into its parent form. The token is stored in the Context, keyed by a customizable name (by default pagename#elementid, which can be overwritten/replaced using the name attribute). After the form is submitted, the token is invalidated and submitting the form again causes the setting of a page message. Via the errorpage attribute you can optionally jump to an error page.

<pfx:forminput>
  <pfx:token errorpage="multisubmiterror"/>
  <!-- place form elements here -->
</pfx:forminput>

You should be aware that this mechanism depends on the caching behaviour of the used browser, e.g. for browsers, which don't cache but reload pages accessed via the back button, it can't prevent the repeated form submission, because the form in fact is a new instance and we can't detect or decide that the submit is illegal.

This mechanism by default only prevents forms with illegal tokens from being processed. If you want to ensure that form submits including no token will fail too, you can force this behaviour by setting the requirestoken attribute at the pagerequest's input element to true. This will force tokens for every form that's submitted to this page.

<contextxmlserver>
  <!--
    servlet config options
  -->
  <pagerequest name="...">
    <input requirestoken="true">
      <interface prefix="..." class="..."/>
    </input>
  </pagerequest>
</contextxmlserver>

The <pfx:checkactive> and <pfx:checknotactive> allow you to check from the XSL-stylesheet, whether a specific IHandler currently is active or not.

<pfx:checkactive page="APageName" prefix="AHandlerName">
  <!--
    Content to be displayed, if the handler is active
  -->
</pfx:checkactive>

The selection mechanism of <pfx:langselect> allows to select matching content anywhere inside a include part depending on the current language that is set in the running session. The <pfx:lang name="default"> tag is acting as the fallback for all languages that don't have a better, more specific named <pfx:lang> node.

<pfx:langselect>
  <pfx:lang name="en_*">...</pfx:lang>
  <pfx:lang name="en_GB">...</pfx:lang>
  <pfx:lang name="default">...</pfx:lang>
</pfx:langselect>

The system doesn't enforce but expects languages to be of the standard form of ISO language codes. In this case, a <pfx:lang> node with a name attribute ending in an asterisk (*) can be used to create a fallback for a whole "family" of languages. In the example above, the en_* node will serve as a fallback for all language codes starting with en_ except en_GB (which has a more specific node below).

The selection mechanism of <pfx:themeselect> allows to select matching content anywhere inside a include part depending on the same selection mechanism that is used to select the include part the first hand as described in Section 5.3.1, “Include parts (<pfx:include>)”

<pfx:themeselect>
  <pfx:theme name="ATheme">...</pfx:theme>
  <pfx:theme name="default">...</pfx:theme>
</pfx:themeselect>

Of course this makes most sense, when the containing include part uses a general theme, so there are specialized themes in the theme fallback queues to select from.

	Note
	This tag is only to be used in very special situations. Normally you would like to use different themes for the include part to register itself correctly with the runtime system.

Pustefix provides an edit-console and webservice-console that are helpful during debugging.

Those consoles can be included in your pages using the <pfx:editconsole> and <pfx:webserviceconsole> tags. The webservice-console may also be included within the editconsole using the following form: <pfx:editconsole webserviceconsole="true">.

In addition to the standard XPath functions supplied by the XSLT/XPath implementation Pustefix provides some additional framework specific XPath functions in the xmlns:pfx="http://www.schlund.de/pustefix/core" namespace:

Example:

<ixsl:if test="pfx:isVisible('mypage')=1">
  Display if page 'mypage' is accessible 
</ixsl:test>

Page functions

Function: number pfx:isVisible(string)

The pfx:isVisible function checks if a page is accessible. The page name is passed as argument. The function returns:

• 1, if the page is accessible
• 0, if the page isn't accessible
• -1, if the page doesn't exist

Function: number pfx:isVisited(string)

The pfx:isVisited function checks if a page has already been visited within the session. The page name is passed as argument. The function returns:

• 1, if the page has already been visited
• 0, if the page hasn't been visited yet
• -1, if the page isn't configured

	Note
	You should be aware that doing a boolean check on results of type number, 1 and -1 both are evaluated as true, 0 as false.

Function: string pfx:getDisplayPageName()

The pfx:getDisplayPageName function returns the display name of the current page.

<!-- iterates over the names of all parts from a file and includes the parts -->
<pfx:for-each select="pfx:getIncludeInfo('path/to/file.xml','amodule')/part">
   <pfx:include select-part="@name" href="path/to/file.xml" module="amodule"/>
</pfx:for-each>

<ixsl:value-of select="pfx:format-date(/formresult/path/to/@time)"/>
<ixsl:value-of select="pfx:format-date(/formresult/path/to/@time, '', 'Europe/Berlin')"/>
<ixsl:value-of select="pfx:format-date(/formresult/path/to/@time, 'EEE, d MMM yyyy HH:mm:ss Z', 'Europe/Berlin', 'de-DE')"/>

<xsl:param name="date-format">EEE, d MMM yyyy HH:mm:ss Z</xsl:param>
<xsl:param name="date-timezone">Europe/Berlin</xsl:param>
<xsl:param name="date-locale">de-DE</xsl:param>

The syntax of all arguments is conforming to the Java standard, see the class java.text.SimpleDateFormat for reference.

<ixsl:value-of xmlns:my="java:mypackage.MyClass" select="my:myMethod(pfx:getBean('myname'),'arg1','arg2')"/>

In addition to the standard XSL elements Pustefix provides some useful XSL extension elements. They can be used by declaring the namespace http://pustefixframework.org/org.pustefixframework.xslt.ExtensionElements, using the prefix pxsl and adding the prefix to the extension-element-prefixes attribute of the stylesheet:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
                xmlns:pxsl="http://pustefixframework.org/org.pustefixframework.xslt.ExtensionElements"
                extension-element-prefixes="pxsl" version="1.1">

There are some extension elements providing extended logging functionality. They work similar to the <xsl:message/> instruction, but additionally support different log levels and can optionally write to a Log4J logger instead of standard output.

<pxsl:log level="DEBUG|INFO|WARN|ERROR"
              logger="SOME_LOG4J_LOGGER"> 
  <!-- content -->
</pxsl:log>
    
<!-- shortcuts for specific log levels -->
<pxsl:debug> <!-- content --> </pxsl:debug>
<pxsl:info> <!-- content --> </pxsl:info>
<pxsl:warn> <!-- content --> </pxsl:warn>
<pxsl:error> <!-- content --> </pxsl:error>

If you don't specify a logger, the content will be written to standard output. But the log levels are bound to the application mode by default, i.e. the log messages will be filtered. Here's which messages are displayed in which mode:

The <pxsl:fail-safe/> extension element catches an exception thrown during the processing of its child elements and outputs its stacktrace instead of the content. This element shouldn't be used on normal pages. It's intended for tooling and debugging purposes only.

<xsl:variable name="result">
   <pxsl:fail-safe>
      <xsl:value-of select="call:someExtensionFunction()"/>
   </pxsl:fail-safe>
</xsl:variable>

Figure 6.1, “Pustefix HTTP request handlers” shows some of the HttpRequestHandlers that are already provided by the core framework and should be sufficient for most of your needs when building a web application with Pustefix.

Figure 6.1. Pustefix HTTP request handlers

The PustefixContextXMLRequestHandler does most of the request handling in an object called the "context". The interface Context provides the applications view on this object. From the applications view the context mainly is:

The context provides a de.schlund.pfixxml.SPDocument to the servlet. This class is a small wrapper around a org.w3c.Document and supplies the XML input document for the final transformation which produces the HTML output. Besides the DOM tree it contains the information the system needs to choose the right stylesheet for the desired page that is to be shown plus some other stuff like XSLT parameters that should be set for the transformation process. The Context doesn't produce the SPDocument itself but delegates this to the State's getDocument() method.

For the PageFlow interface there is currently only one implementation, and at the time of this writing it's not yet possible to change this implementation by supplying your own, although this is planned for the near future. The current implementation is called DataDrivenPageFlow, and it will be explained in more detail below. For the discussion presented here, it is sufficient to know the general PageFlow interface.

public interface PageFlow {
    String getName();
    String getRootName();
    boolean containsPage(String pagename);
    String findNextPage(PageFlowContext context, String currentpagename, boolean stopatcurrentpage,
                        boolean stopatnextaftercurrentpage) throws PustefixApplicationException;    
    boolean precedingFlowNeedsData(PageFlowContext context, String currentpagename) throws PustefixApplicationException;
    boolean hasHookAfterRequest(String currentpagename);
    void hookAfterRequest(Context context, ResultDocument resdoc) throws PustefixApplicationException, PustefixCoreException;
    void addPageFlowInfo(String currentpagename, Element root);
}
      

Both getName() and getRootName() return the name of the pageflow, the difference being that getName() contains the full qualified name (the root name together with any variant name, if present) while get RootName() only returns the root name.

containsPage(String pagename) must return true if the given page name is part of the page flow.

findNextPage(...) is more interesting. It implements the main duty of a page flow: To supply some sort of "next" page, given the context (in the form of a PageFlowContext which is just a stripped down version of the Context interface to only support getting information, but no changing the inner state of the context object), the information what the current page name is (currentpagename), and two flags:

The rest of the methods will be explained in more detail below.

The situation is different for States; Pustefix supplies implementations to cover most of the needs one may have in a normal application, however there are always situations where it is needed or at least much easier to write a specialized State instead of trying to re- or misuse one of the two "standard" implementations supplied with the framework.

These two implementations are StaticState and DefaultIWrapperState. The first is used for all static pages, i.e. pages that don't need to process any input parameters, but merely display more or less static content. The only dynamic thing this state can do is to include information from context resources into it's output DOM tree. The second one implements the concept of wrappers and handlers, which is the standard way in pustefix to handle input data.

Both of these states inherit from the abstract class StateImpl, a class that implements a bunch of helper methods useful for basically every conceivable state implementation. So it is strongly suggested to use this (or one of the two described states) as the base class for your own implementations.

While both of these states will be explained in detail below, it is important to note that the context only knows about states, not a special implementation of it. So on this level it makes no difference if a request supplies data to be processed, or if it only request the display of a certain page. So the only thing we need to know for this chapter is the interface all states have to implement:

public interface State {
    boolean        isAccessible(Context context, PfixServletRequest preq) throws Exception;
    boolean        needsData(Context context, PfixServletRequest preq) throws Exception;
    ResultDocument getDocument(Context context, PfixServletRequest preq) throws Exception;
}
      

These three methods are quite easy to explain. isAccessible(...) is used to check if a page is accessible (the exact wording would be "the associated State of the page", but we use page/state interchangeable here, as there is a n:1 association of pages to states anyway, i.e. every page has exactly one associated state, but most of the time many pages share the same state. States are singletons, so they don't store any data themselves. This allows to share them between many pages). getDocument(...) is the method that does all the work. Here we produce the result DOM tree that is used to render the final HTML page with. needsData(...) is (or better: can be) used only during page flow processing to determine what the next page is that needs to be shown. This method will be explained when we describe the PageFlow and it's default implementation in greater detail below.

During the request-response cycle, the Context maintains a set of variables that influence the processing of the request. These are listed in the following table. Use these as a reference to see how they can be set and changed, either by specifying values for them in the request (directly, or by referencing an action that sets them) or by calling a method of Context somewhere from Java code during the processing of the request.

The currentpageflow variable needs some more explanation, as in many cases, it is not given explicitly neither by submitting an action that specifies the page flow nor directly from the request parameter __pageflow. If this is the case, the Context tries to find a matching page flow by using the following algorithm.

In this section we want to explain the way the request cycle is handled in Pustefix by the Context and its peer objects (State, PageFlow) used during processing.

After the variables have been initialized, we have two different ways to go on. Either startwithflow is set to true, or not. The first case will be explained below in more detail, for now we assume that the value of startwithflow is false. We also do neglect some other aspects, that have to be taken care of during request processing: Role based authentication isn't mentioned here and also the fact that each State will always be asked if it is accessible before calling one of the other two methods won't be mentioned explicitly for the remainder of this explanation.

Despite all the explanation about States, most of the time one doesn't write States directly, but rather uses one of two predefined States (or trivial descendants of them).

IWrappers are used to store the request data that is used as input for corresponding IHandler classes. IWrappers are not explicitly written by the developer, but are generated from .iwrp files which contain a high level XML description of the parameter types and certain checks that should be applied to them. Each .iwrp file is translated into a .java file with the same name during the build process, and a java class is created. In the corresponding IHandler, you use the IWrapper to access or store data by calling the IWrapper's get and set methods.

The syntax of the .iwrp file is given below.

<interface xmlns="http://www.pustefix-framework.org/2008/namespace/iwrapper"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.pustefix-framework.org/2008/namespace/iwrapper 
                      http://www.pustefix-framework.org/2008/namespace/iwrapper.xsd"
  extends="mypackage.MyIWrapperClass">
  <!--
    The class attribute references the associated IHandler class. Alternatively you can
    reference an existing Spring bean using the bean-ref attribute.
    The ihandler node is optional, but if it is left out, the generated
    IWrapper will be abstract and cannot be used directly, unless an extends attribute
    has been given to the interface node. Normally you will want to specify an ihandler
    class here.
  -->
  <ihandler class="mypackage.MyIHandlerClass"/>
  <!-- or <ihandler bean-ref="aBean"/> -->
  <!--
    This node can (and usually will) occur multiple times, one for every parameter that
    should be part of the interface
  -->
  <param name="AName" type="some.java.Type" occurrence="optional|mandatory|indexed" frequency="single|multiple"
         missingscode="some.defined.statuscode">
    <!--
      The whole node is optional. It allows to specify a default value (or multiple) for
      a parameter to use, when no value is supplied via the request. Note that this makes
      the destinction between optional and mandatory parameters nonsensical.
    -->
    <default>
      <value>a_default_value</value>
      <value>an_other_default_value</value>
    </default>
      
    <!--
      To test if a param value conforms to the rules, you can specify Check-Classes here
      whose check method will be called to test if the param value makes sense.
      The Check-Classes must implement de.schlund.pfixcore.generator.IWrapperParamPreCheck
      (the interface defines the check(...) method).
    -->
    <precheck class="a.prechecker.class">
      <cparam name="APreCheckerParamName" value="APreCheckerParamValue"></cparam>
    </precheck>
      
    <!--
      Each parameter must be casted from a String to the specific type (unless the type is java.lang.String itself,
      in this case, no caster need to be supplied). This is done by means of a class implementing 
      de.schlund.pfixcore.generator.IWrapperParamCaster. For the usual simple types you can use a caster from the
      package de.schlund.pfixcore.generator.casters.
    -->
    <caster class="de.caster.class">
      <cparam name="ACasterParamName" value="ACasterParamValue"></cparam>
    </caster>

    <postcheck class="a.postchecker.class">
      <cparam name="APostCheckerParamName" value="APostCheckerParamValue"></cparam>
    </postcheck>
  </param>
</interface>

public class MyWrapper {
    Bar  getFoo();
    void setFoo(Bar value);
    void setStringValFoo(String str_value);
    void addSCodeFoo(de.schlund.util.statuscode.StatusCode scode);
    void addSCodeWithArgsFoo(de.schlund.util.statuscode.StatusCode scode, String[] args);
}

public class MyWrapper {
    Bar[] getFoo();
    void  setFoo(Bar[] value);
    void  setStringValFoo(String[] str_value);
    void  addSCodeFoo(de.schlund.util.statuscode.StatusCode scode);
    void  addSCodeWithArgsFoo(de.schlund.util.statuscode.StatusCode scode, String[] args);
}

public class MyWrapper {
    Bar  getFoo(String index);
    void setFoo(Bar value, String index);
    void setStringValFoo(String str_value, String index);
    void addSCodeFoo(de.schlund.util.statuscode.StatusCode scode, String index);
    void addSCodeWithArgsFoo(de.schlund.util.statuscode.StatusCode scode, String[] args, String index);
}

public class MyWrapper {
    Bar[] getFoo(String index);
    void  setFoo(Bar[] value, String index);
    void  setStringValFoo(String[] str_value, String index);
    void  addSCodeFoo(de.schlund.util.statuscode.StatusCode scode, String index);
    void  addSCodeWithArgsFoo(de.schlund.util.statuscode.StatusCode scode, String[] args, String index);
}

The InputHandler interface is the replacement for the deprecated IHandler interface. Its advantages are: you get rid of casting because it's generic, and the methods don't declare to throw Exception, which forces sensible exception handling.

public interface InputHandler<T extends IWrapper> {
    void    handleSubmittedData(T wrapper);
    void    retrieveCurrentStatus(T wrapper);
    boolean prerequisitesMet();
    boolean isActive();
    boolean needsData();
}

The IHandler interface is deprecated. Use InputHandler instead.

public interface IHandler {
    void    handleSubmittedData(Context context, IWrapper wrapper) throws Exception;
    void    retrieveCurrentStatus(Context context, IWrapper wrapper) throws Exception;
    boolean prerequisitesMet(Context context) throws Exception;
    boolean isActive(Context context) throws Exception;
    boolean needsData(Context context) throws Exception;
}