First Site

Note that the Paloose system is a subset of Cocoon so almost all of the features in Paloose are directly derived from Cocoon so it is useful but not essential to know about Cocoon. In order to see how it works let us build that archetypal beginner's site: "Hello World".

  1. Create a base folder to hold your site where your Apache server will see it. In this case we will create a folder 'HelloWorld' in the root directory that we created during the install.

    ${ROOT_DIR} hsfr$ mkdir HelloWorld ${ROOT_DIR} hsfr$ cd HelloWorld ${ROOT_DIR}/HelloWorld hsfr$
  2. Create the folders 'resources/transforms' and 'resources/syles'.

    ${ROOT_DIR}/HelloWorld hsfr$ mkdir -p resources/transforms ${ROOT_DIR}/HelloWorld hsfr$ mkdir -p resources/styles ${ROOT_DIR}/HelloWorld hsfr$ mkdir -p content ${ROOT_DIR}/HelloWorld hsfr$
  3. Create a 'content/page.xml' file which is the content of the page. Note that there is no style information here at all — we are only describing what the individual parts of the page are. The file should contain the following XML code:

    <?xml version="1.0" encoding="UTF-8"?> <page> <heading>Hello World</heading> <p>My first page using Paloose.</p> </page>
  4. Now we need a transformation to take that and turn it into something that the browser will understand. Create a file 'resources/transforms/page2html.xsl' containing the following:

    <?xml version="1.0"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <!-- -*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-* --> <xsl:template match="/"> <xsl:element name="html"> <xsl:call-template name="htmlHead"/> <xsl:call-template name="htmlBody"/> </xsl:element> </xsl:template> <xsl:template name="htmlHead"> <xsl:element name="head"> <xsl:element name="title"> <xsl:value-of select="//heading"/> </xsl:element> </xsl:element> </xsl:template> <xsl:template name="htmlBody"> <xsl:element name="body"> <xsl:apply-templates mode="inline-text"/> </xsl:element> </xsl:template> <!-- -*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*- --> <xsl:template match="heading" mode="inline-text"> <xsl:element name="div"> <xsl:attribute name="class">heading</xsl:attribute> <xsl:apply-templates mode="inline-text"/> </xsl:element> </xsl:template> <xsl:template match="p" mode="inline-text"> <xsl:element name="div"> <xsl:attribute name="class">normalPara</xsl:attribute> <xsl:apply-templates mode="inline-text"/> </xsl:element> </xsl:template> </xsl:stylesheet>

    This is a fairly crude transformation and real ones will be considerably more complex that this.

  5. Note that the code that this produces is based on divs. The final style is not put in until we add a style file. So create a file:

    body { background-color: #d2cab5; color: #66766d; margin: 20px 0px 0px 20px; } .normalPara { font-family: Verdana, Arial, Helvetica, sans-serif; margin: 10px 0px 0px 0px; } .heading { font-size: 18px; font-family: Georgia, "Times New Roman", Times, serif; font-style: italic; color: #56554a; }

    It is worth noting here that we have three separate (and hopefully orthogonal) files that make up our simple site. The content (heading and paras), the layout structure (text blocks) and the layout style (fonts, colours etc). All should be able to be manipulated with minimal interference with each other.

  6. We need to tie them all together so that a request for http://hostname/HelloWorld/page.html will produce the page that we require. The control of this is within the sitemap.xmap file. It follows standard Cocoon practice with only minor differences in the component definitions. First of all we define the components that we are going to use. Note that to those wo are more used to Cocoon the 'src' attribute normally defines a Java package, in Paloose it is the name of a PHP file. So paloose://lib/generation/FileGenerator' defines a file '${ROOT_DIR}/paloose/lib/generation/FileGenerator.php'. This means that you can define your own components fairly easily and place them where you want (there is an example component given in the distribution).

    <?xml version="1.0" encoding="UTF-8"?> <map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0"> <map:components> <map:generators default="file"> <map:generator name="file" src="resource://lib/generation/FileGenerator"/> </map:generators> <map:transformers default="xslt"> <map:transformer name="xslt" src="resource://lib/transforming/TRAXTransformer"/> </map:transformers> <map:serializers default="html"> <map:serializer name="html" mime-type="text/html" src="resource://lib/serialization/HTMLSerializer"/> </map:serializers> <map:matchers default="wildcard"> <map:matcher name="wildcard" src="resource://lib/matching/WildcardURIMatcher"/> </map:matchers> </map:components>

    The components that are defined above are the default ones and support almost all of what you might require. The HTML serializer needs some more work but the current version should suffice most people's needs at present. Next we use these components to build pipelines (in the same fashion as Cocoon) to handle requests.

    <map:pipelines> <map:pipeline> <map:match pattern="**.html"> <map:generate src="context://content/{1}.xml"/> <map:transform src="context://resources/transforms/page2html.xsl"/> <map:serialize/> </map:match> </map:pipeline> </map:pipelines> </map:sitemap>
  7. Having done the sitemap we must now tell the Apache server what to do to use Paloose. This is done using the .htaccess file (note the leading period in the name). The key is to use the Rewrite facility of the Apache server. So place the .htaccess file in the home directory of your site with the following:

    RewriteEngine On RewriteRule (.+)\.html paloose.php?url=$1.html [L,qsappend]

    This tells Apache that all requests for files in the HelloWorld directory (in which the .htaccess file sits) should obey the rule above. So a request for 'http://host-name/HelloWorld/page.html' would be translated to 'http://host-name/HelloWorld/paloose.php?url=page.html'.

    Warning

    If you see the following error (or similar)

    "Parse error: syntax error, unexpected '=', expecting '(' in ....../paloose/lib/Paloose.php on line 88"

    when you try and run the simple site, it is almost certain that you are running PHP4. You will need to speak to your ISP to find out how to direct all Paloose code to use PHP5 (assuming that they have this as an option).

  8. The final part of the puzzle is what to do with the rewritten request above. We need a file paloose.php in the HelloWorld folder. This contains all the necessary user defined information and the link to start Paloose running. There is an example file in the Paloose distribution to help you get started in ${ROOT_DIR}/paloose/resources/templates/paloose.php.dist.

    The interesting parts of the paloose.php file that you may want to change, are detailed below. Change the PALOOSE_DIRECTORY address here to indicate where you have put the main Paloose folder. It can be relative to your application site folder.

    define( 'PALOOSE_DIRECTORY', '../paloose' );

    The next lines define where the main log4php logger configuration file is kept. You can use pseudo-protocols here. You also define the path to the Log4PHP distribution (LOG4PHP_DIR). This is a change since version 1.1.2b1. If you are using versions earlier than this then the logging library is included within Paloose and this line (LOG4PHP_DIR) is not necessary.

    define( 'LOGGER_CONFIG', 'context://configs/Paloose.xml' ); define( 'LOG4PHP_DIR', '../log4php' ); define( 'TIME_ZONE', 'Europe/London' );

    Normally should not have to change the root sitemap if you use the standard Cocoon names. The directory is always the top level user directory.

    define( 'ROOT_SITEMAP', 'sitemap.xmap' );

    The error page to give back for User errors (errors in sitemap etc). If you override these to your area make sure that you use an absolute directory path — you can use the 'context' pseudo-protocol here.

    define( 'USER_EXCEPTION_PAGE', 'resource://resources/errorHandling/userError.html' ); define( 'USER_EXCEPTION_TRANSFORM', 'resource://resources/transforms/errorPage2html.xsl' );

    Be careful of the path here — although it is relative it looks as an absolute one. It is in fact relative to the Apache root document directory. Must always have a leading path separator.

    define( 'USER_EXCEPTION_STYLE', '/paloose/resources/styles/userError.css' );

    The file that contains the index for each level of the gallery. For this simple example it can be ignored. Indeed 99% of the time it could be left as this. The ImageMagick bin path is rarely needed if your server has the various binaries of the ImageMagick package on the Path. It is commented out in the paloose.php.dist file.

    define( 'GALLERY_INDEX', 'gallery.xml' ); define( 'IMAGEMAGICK_BIN', '' );

    The error page to return to the user for internal programming errors. These should not need to be overridden unless you want to use your own.

    define( 'INTERNAL_EXCEPTION_PAGE', 'resource://resources/errorHandling/internalError.html' ); define( 'INTERNAL_EXCEPTION_TRANSFORM', 'resource://resources/transforms/errorPage2html.xsl' );

    Again, be careful of the path here — it is relative to the Apache root document directory. Must always have a leading path separator.

    define( 'INTERNAL_EXCEPTION_STYLE', '/paloose/resources/styles/internalError.css' );
  9. Last remaining thing is to open a browser and go to the address http://[host-name]/HelloWorld/page.html. If all is well you should see the following

Copyright 2006 – 2023 Hugh Field-Richards. All Rights Reserved.