Developers guide Toolbox PSC - Joinup · 2017. 10. 3. · base war. In addition to this mechanism there is an additional pointer which tells Cocoon where to retrieve the extensions

•••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

Developers guide Toolbox PSC

Developing and customising

Author(s) Stephanie Solingen, Enrico Cervato,Version 1.4Status FinalThe Hague, 11-01-10

Developers guide Toolbox PSC 2/32

•••••••••••••••••••••••••••••••••••••••••••••••

Document information

ColophonAuthor(s) Status

Stephanie Solingen, Enrico Cervato, Minze Tolsma, NathalieLooijmans, Jochem Knoops, Barry van de Graaf and PaulSchooneman

Final

Project Date

Toolbox PSC 11-01-10Organisation Classification

Title Location

Developers guide Toolbox PSC The HagueVersion

1.4

HistoryDate Version Changes Status Processed by

17-09-09 0.1 Initial document draft Stephanie22-09-09 0.2 Amendments processed draft Stephanie02-10-09 0.3 Message box addition draft Nathalie08-10-09 0.4 PSC Message box authentication draft Jochem21-10-09 0.5 Paragraphs 29 +29 added draft Nathalie22-10-09 0.6 Further amendments draft Barry26-10-09 0.7 Further amendments draft Enrico28-10-09 1.0 Further amendments Final Barry20-11-09 1.1 Further amendments draft Enrico24-11-09 1.2 Added information about

adjusting the authentication provider

Final Paul

11/01/10 1.4 Further amendments Final Barry

Distribution listDate Distribution Presentation Version

22-09-09 Barry van de Graaf draft 0.1

ApprovalDate Name Version


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••

Preface

This document describes how to customise parts of the Website, CMS, the Cooperating Catalogues Export Tool (CCET) and the Message Box.

In order to get a full understanding of this document it is beneficial for the reader to be experienced with the following technologies:•Hippo 6 CMS1

•Apache Cocoon 2.1 Java framework2

•Apache Maven 2.0.9

Hippo 6 CMS is the Content Management System chosen as back end for the product. It can be used to create, edit, manage, search and publish various kinds of content in a user friendly way so that the authors will not need particular technical skills to be able to fill in information. The content is stored in a slide repository, which will be used by the website for retrieving the documents and show them to video with criteria depending on the meta data of the documents themselves.

Both Hippo 6 CMS and the Website are using Cocoon 2.1 as a Java framework, therefore the user will be able to modify both the CMS and the Website code working always with the same technology.

Maven 2 is the project management tool used to set up the product. It permits to handle the configuration, build, release and a number of other common tasks in an intuitive and well organized way.

If the reader has a good understanding of the above mentioned software tools, this document should give him enough information to enable him to understand the functioning of the products and perform the most common custom modifications.

1http://wiki.onehippo.com/display/CMS/Hippo+CMS+6+Home2http://cocoon.apache.org/2.1/


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••

Table of contents

1 Basic configuration 61.1 Customisation of properties files 61.2 Filters.properties – CMS 71.3 Filters properties for the Website 81.4 Common filters properties 81.4.1 Domain and hosts settings 81.4.2 Cargo Configuration 91.4.3 JMS Configuration and JMS Settings 91.4.4 DB Slide settings 91.4.5 Repository settings 91.4.6 Logging flags 91.5 Cocoon patching mechanism 101.6 Lucene index configuration 101.7 Hippo CMS tools 101.7.1 Dav2disk tool 101.7.2 PublishAll tool 111.7.3 Touch tool 11

2 The PSC website 122.1 General structure 122.1.1 Sitemaps and pipelines 132.1.2 A simple sitemap example 142.1.3 DASL queries 152.2 How to perform basics graphical changes 152.3 How to adjust the URL-space 152.4 How to add web statistics 162.4.1 How to add tracking for external links 18

3 The CMS 203.1 How to configure the dashboard 203.1.1 Dashboard tabs 203.1.2 Dashboard menus 213.2 How to add a document type to the New Document Wizard 213.3 How to translate or add labels in the Website 223.4 How to adjust the export file 233.5 How to make an export file 233.6 Updating the zipcodes file 23

4 The Cooperating Catalogues Export Tool 254.1 XSD 254.2 I18N 254.3 CSS 254.4 Administrator account 25


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••

4.5 Domain configuration grietje 26

5 The PSC Message Box 275.1 Look and feel 275.2 Language switching mechanism 275.2.1 Change the default language to your own language 275.2.2 I18N language files 285.2.3 Create your own i18n file for notification messages 285.2.4 Fine tuning details (optional) 285.2.5 Define the categories for the authorities 285.3 Rebuild the application 295.4 The PSC Message Box Authentication 295.4.1 Adjusting the PSC Authentication Provider 30


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••

1 Basic configurationAs already mentioned in the preface of this document, both the CMS, the repository and the Website are structured with Maven 2. This will permit to handle common operations like building, releasing, testing and customising in a lean way.

1.1 Customisation of properties files

As mentioned in the preface a good knowledge of Maven 2 is required in order to get a good understanding of the products structure. For an expert Maven user the way the products are set up should be clear straight away. Everything possible was done to keep the structure of the projects as simple as possible via the 'convention over configuration' Maven approach.

It is anyway good to spend a couple of words about the properties files because it will be necessary to modify them in order to adapt the system to your needs.

In both CMS and Website and repository modules we have defined some properties files that are considered by Maven when building the projects. A number of place holders are defined around the code and the values for these will be picked up at compile time from the properties files. This should permit you to modify the properties only there and have Maven to do the rest when building your project.

When structuring a project with Maven, the pom.xml file is where all the relevant information is stored. If you are willing to modify both the Website or the CMS we strongly recommend to go through the pom.xml to get a good understanding about how the projects are structured. As for the properties files in the pom.xml of the Website we find the following XML snippet:

<filters><filter>src/main/filters/filters.properties.${env}</filter>

</filters>

This means that at compiling time the user will be able to define the properties file to refer to via the env variable. In the beginning you will find in the modules two properties files: filters.properties.devbox2 and another filter. The first is supposed to be used for the developer environment while the second is supposed to be used to store the production configuration.

In order to compile the products for the dev environment go to the root folder and launch the following Maven command:

mvn clean package -Denv=devbox2

In order to compile the products for the production environment go to the root folder and launch the following maven command:


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••

mvn clean package -Denv=<production filter name>

If no environment is specified, the devbox2 configuration will be picked up as default.

Should you need some more configurations options to cover the DTAP street you can define your own properties file filters.properties.mine and compile the projects with the following command:

mvn clean package -Denv=mine

In the following paragraphs certain properties contained in the properties files will be highlighted; it is important for you to check if these properties are correct, or else certain functionalities will not work.

In the website module a set of JUnit tests are defined in order to check if the XSLTs are well defined and for the unit testing of some features of the website. When packaging the product these tests will be executed right before creating the war's. In order to avoid performing the tests just specify in the command the parameter -Dmaven.test.skip=true It is always recommended to perform the tests.

1.2 Filters.properties – CMS

In the properties file for the CMS we have a property called cms.extensions which deserves some words, because it is particularly important, also to understand a little bit more about how the CMS project is built up by Maven.

If you look into the pom.xml file for the CMS you will notice that the first dependency is the following:

<dependency><artifactId>hippo-cms</artifactId><groupId>nl.ictu</groupId><type>war</type><version>...</version>

</dependency>

When building a war, if a dependency of type war is present, Maven executes a war overlaying. This means that it will download the nl.ictu.hippo-cms war from the Maven repository and use it as a base for the new war to be produced. Then the result of the built of the project will be added to the base war. In addition to this mechanism there is an additional pointer which tells Cocoon where to retrieve the extensions for the CMS from. This is defined in the cms.extensions property. When deploying to production we suggest to set this parameter as here below; so that it will point to the extensions inside the war.


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••

cms.extensions=../hippo-cms-extensions/When developing changes for the CMS, it is much more convenient to have Cocoon to point to the files in your workspace, so that when modifying them you will not need to the rebuild the module and deploy it in tomcat to see the effects of the changes. If the cms.extensions is pointing to your workspace, you will see the effects of the changes right away, just refreshing the pages involved in your browser. In this case set the cms.extensions like the following:

cms.extensions=/home/ubuntu/workspace/toolbox/trunk/a4b-cms/src/main/site/

1.3 Filters properties for the Website

A few words should be spent about the property pom.webapp.sitemap. This is where the cocoon framework expects to find the sitemap to map the incoming pipelines. The concept will be explained later in this document, but let's simply say that in this location the framework looks for matches when a new http request is sent to the Website.

When going to production simply keep the pom.webapp.sitemap commented, or simply delete it from the configuration file. In this case cocoon will point to the default folder which is inside the war produced by Maven built.

When working on changes for the website, it is more convenient to have Cocoon to point to the source files in your workspace. This way you do not need to build the project and deploy it in your web server to see the changes result. You simply save your files and refreshing the page you will see the effects right away. In order to do that just refer to your workspace directory; the property will therefore look like the following:

pom.webapp.sitemap=/home/ubuntu/workspace/toolbox/trunk/a4b-site/src/main/site/

1.4 Common filters properties

Besides the above mentioned properties a number of other properties are contained in the properties file for the CMS and the Website. Going extensively through all of them would result extremely verbose. As they are divided in logical groups we will go through the principal logical groups so that at least the reader will get an overview of all the possible customisations.

1.4.1 Domain and hosts settings

These settings contain the host names and ports to be used for the CMS and the Website themselves and to define where they expect to find each other, the slide repository and the LDAP service.

As mentioned before the Hippo CMS 6 uses a repository based on Apache Slide for the storage of XML documents.


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••

As for the LDAP, this is not part of the basic configuration. Hippo CMS 6 has its own internal users management and stores the information concerning the user in its own slide repository, the same one used for the documents. If an LDAP server is already present in the organisation for the management of users, setting up authentication against that LDAP is definitely an option. In that case you have to keep in mind that the interaction will be on read-only mode and it will not be possible to create, modify or delete users in the LDAP server from the users management console of the CMS.

1.4.2 Cargo Configuration

Cargo is a Maven plugin which permits the automatic deployment of the wars produced by the built to a certain instance of a tomcat server. For the reader willing to go deeper in the subject it is possible to find comprehensive information in the official Cargo website.

These settings define where Maven 2 is expecting to find the tomcat server when deploying the wars.

1.4.3 JMS Configuration and JMS Settings

For the CMS, the repository and the Website to communicate among them it is necessary to have a JMS provider to exchange messages. This is where the settings for the JMS instance should be defined.

1.4.4 DB Slide settings

As mentioned before the CMS uses a slide repository to store the contents. The slide repository requires a database and here is where the database settings should be defined.

1.4.5 Repository settings

Here are the to be defined settings used in the set up of the Slide repository.

1.4.6 Logging flags

Here is the list of the log levels used by Cocoon for logging. When a higher or lower logging detail is required, here is where the changes should be made.

1.5 Cocoon patching mechanism

When Maven builds the the Website and the CMS a sort of patching mechanism is executed in order to inject into the Cocoon framework additional settings. The mechanism considers all the files put in


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••

the folder /src/config of the CMS and the Website and use them as patches for the various Cocoon configuration files depending on their extension:

•*.xconf – applied as patches to cocoon.xconf•*.xmap – applied as patches to the root sitemap.xmap•*.xlog – applied as patches to the logging configuration

1.6 Lucene index configuration

Currently the application is configured for Dutch text analysis. To switch to another text analysis language one should modify the following file:a4b-repo/scr/main/webapp/WEB-INF/dasl-indexer.xml and update all references to org.apache.lucene.analysis.nl.DutchAnalyzer to match an analyzer suitable for your language. A Maven rebuild is required along with a restart of your tomcat container.

Consult the Apache Lucene docs for an overview of available analyzers.

Lucene is storing the indexes in files which will be created in the folder defined in the parameter repo.data in the filters.properties file. In order to have Lucene to re-index all the documents from scratch simply delete this data folder and restart the repository web application. Doing this Lucene will re-index all the documents, at start up. Another possible approach is to use the Hippo Touch Tool to touch a part or all the documents. When using this approach it is not necessary to shut down the application.

1.7 Hippo CMS tools

Operations involving a high number of documents might result in a very time consuming task if the user was obliged to perform them one document at the time from the CMS console. That is why Hippo provides some tools permitting to perform these operations from command line in a faster way.

These tools can be downloaded from the Hippo official website and built. In order to make life of the user easy we provide some already built in ; in the module a4b-repo-init.

1.7.1 Dav2disk tool

This tool is to be found in the folder hippo-plugin-dav2disk in the a4b-repo-init module. It permits to download documents from the repository producing XML files.

Before launching the command the user should go and modify the config/dav2disk.properties. This is were all the parameters should be defined in order for the tool to be able to find and contact the repository. The user should also specify what location of the repository is to be downloaded in the parameter repository.path.


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••

In order to run the tool simply launch the download.sh. This will load the config/dav2disk.properties and download recursively all the documents contained in the specified folder and its sub folders to the file system.

With the same mechanism the tool permit to upload documents from the file system into the repository.

1.7.2 PublishAll tool

This tool is to be found in the folder hippo-plugin-publishall in the a4b-repo-init module. It permits to publish recursively all the documents contained in a specified folder in the repository.

Before launching the command the user should go and modify the publishall.properties. This is were all the parameters should be defined in order for the tool to be able to find and contact the repository.

In order to run the tool, the following command is to be launched:

java -jar wdbp-publish-all-1.01.00-uber.jar publishall.properties

The tool will publish all the documents defined in the location contained in the parameter location.path from the preview website to the live website.

1.7.3 Touch tool

This tool is to be found in the folder hippo-plugin-touch in the a4b-repo-init module. It permits to touch recursively all the documents contained in a specified folder in the repository. Doing this will cause Lucene to re-index every single document.Before launching the command the user should go and modify the touch.properties. This is were all the parameters should be defined in order for the tool to be able to find and contact the repository. Besides those properties we have the location.path property, which is supposed to contain the folder where the documents should be recursively saved (touched).

In order to run the tool, the following command is to be launched:

java -jar wdbp-touch-1.01.04-dev-uber.jar touch.properties

After launching the command above you should see in the console the output of the tool going recursively through the documents and saving them.


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••

2 The PSC websiteIn the following chapters certain elements of the website that you must or can customise will be described.

2.1 General structure

The Website is structured with DIV's so that table less HTML code is produced and the way it is finally displayed is easily manageable via the use of CSS files.

There are two main page layouts. The layout for the homepage and the layout for the displaying of contents. If we have a close look to the HTML produced for the homepage for example we will find the following DIV's:

1 header (logo and search) 2 navigation (black bar) 3 content box: 3.1 branch 3.2 scalable box 3.2.1 main column: 3.2.1.1 content 3.2.1.2 related pane 3.2.1.3 navigation pane

The main column represents the visible structure of the homepage, which looks like follows:


Date 11-01-10 | Version 1.4 | |

1

2

3

3.1

3.2.(1)

3.2.1.2

3.2.1.1

3.2.1.3


•••••••••••••••••••••••••••••••••••••••••••••••

2.1.1 Sitemaps and pipelines

When working with Apache Cocoon 2.1, it is absolutely necessary to have some concepts very clear in mind, first of all the concepts of pipeline and sitemap. A good knowledge of the Cocoon 2.1 framework is required in order to be effective since the first moment in understanding and modifying the system object of this guide.

It is good anyway to spend some words about the general organisation of the code of the Website, in order to give a general idea about how the http request are in general processed by the cocoon framework.

Starting from the very beginning, when an http request is performed, the url is picked up and this is used to possibly retrieve a sitemenu entry in the sitemenu.xml file in the folder src/main/site. We will have a closer look to the sitemenu in one of the following paragraphs but for the moment let's say that via the sitemenu a 'name' and a 'datasource' will be associated to an URL.

The 'name' is actually the name of the folder containing the XSL transformations to be applied for that specific URL in order to produce the various HTML pieces composing the final XHTML page.

The 'datasource' is the position in the repository of the XML documents providing the information to be displayed.

Every HTTP request will be matched in the sitemap.xmap in the /src/main/site folder and will generate a series of sub-pipelines. Each of this will compose a part of the final XHTML page. In the most general case there are the following components:

•header•head•brand•breadcrumbs•quicklinks•relatedpane•navigationpane•center•navigation

If the related pipeline is not found in the source folder associated to the URL the default one will be picked up from the 'default' folder. Thanks to this fall back mechanism, when defining a new page structure, it is necessary to redefine one of the elements only when it has to be different from the default one. If nothing is defined the default one will be selected.


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••

2.1.2 A simple sitemap example

Every pipeline is usually composed by the following three elements: 1.one or more generators, 2.one or more transformations, 3.one serializer. In most cases, every pipeline will generate some XML picking up one or more documents and metadata files from the repository, then will perform one or more XSL transformation to get to the HTML and finally serialize the result in simple XML.

Let's consider for example the content of the head.xmap in the folder /src/main/site/sitemaps/contact, which is the sitemap used to produce the head section for the contact page:

<?xml version="1.0" encoding="UTF-8"?><map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0"> <map:pipelines> <map:pipeline internal-only="false" type="ecaching"> <map:match pattern="head/**"> <map:generate src="cocoon://document{sitemenu-entry:datasource}" element="page" /> <map:transform src="xslt/head.xsl" /> <map:serialize type="xml"/> </map:match> </map:pipeline> </map:pipelines></map:sitemap>

If we consider the central section of the XML contained in the <map:pipeline> tag you will

notice the classical structure mentioned above:

•generator: a document is retrieved from the repository calling the pipeline cocoon://document{sitemenu-entry:datasource} and that gives the XML which provides the base for the pipeline execution;•transformation: the XSL transformation xslt/head.xsl is called on the XML produced in the generator;•serializer: the result of the XSL transformation is serialized as XML.

In order to get deeper into the subject we recommend to refer to the online documentation for the Cocoon 2.1 framework.

Once all the pipelines for all the components for the web page have been executed, all the HTML pieces are put together and the final XSL transformation common2html.xsl is applied to produce the very final XHTML which will then be sent to the browser in response to the HTTP request.


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••

2.1.3 DASL queries

In the previous paragraph we saw a simple pipeline where the final XML was produced retrieving a single document from the repository and performing a single XSL transformation.

Sometimes to produce a page section it is necessary to retrieve information contained in multiple documents. This is done via queries on the repository. As we said before the repository uses the Apache Slide technology and in order to perform queries we need a particular format called DASL, based on the webdav protocol.

These DASL query are performed as well via a pipeline. All the DASL queries used by the Website have a match in the sitemap /site/dasl/sitemap.xmap

If we consider the fragment here below we will notice that the pipeline for a DASL query has two transformers:•the first to produce the XML for the DASL query (as a result of the XSL transformation xsl/getFloating.xsl) and •the second which execute the DASL query via a webdav call. After that the result is serialized in XML and can be used in other pipelines performing additional XSL transformations and getting finally to the HTML to display.

<map:match pattern="getFloating**"><map:generate src="site://resources/xml/empty.xml" /><map:transform src="xsl/getFloating.xsl"/><map:transform type="webdav"/> <map:serialize type="xml"/>

</map:match>

2.2 How to perform basics graphical changes

It is strongly advised to have someone on the team who is familiar with HTML and CSS. Customisations like changing the logo or adding different pictures to the website can be done quite easily.

You can find the elements for customisation in the following part(s) of the project:•a4b-site/main/site/resources/css•a4b-site/main/site/resources/images

The most important CSS files are the scherm.css and the avb.css


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••

2.3 How to adjust the URL-space

To change the URL-space, so it fits your own language, or the URL that you would like to have, the following two steps need to be performed:

•Step 1: Modify the sitemenu.xml file.•Step 2:Modify the urlrewrite.xml file.

The sitemenu.xml purpose is to map url's to corresponding Cocoon sitemaps and provide the sitemaps with datasources, language and locale settings.

A short example in which the url 'sectors' is mapped to the sitemap 'brancheoverview' along with Dutch locale and language settings:

<entry> <name>brancheoverview</name> <datasource>/content/nl/brancheoverview/normal.xml</datasource> <url>sectors</url> <language>nl-NL</language> <locale>nl</locale> <exactmatch>true</exactmatch></entry><entry> <name>brancheoverview</name> <datasource>/content/en/brancheoverview/normal.xml</datasource> <url>en/sectors</url> <language>en-EN</language> <locale>en</locale> <exactmatch>true</exactmatch></entry>

The file can be found in the Website project in the folder src/main/site

The urlrewrite.xml is used for permanent redirects. It can be found at a4b-site/src/main/webapp/WEB-INF/urlrewrite.xml

This file is based on the tuckey.org UrlRewriteFilter.


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••

2.4 How to add web statistics

In the Netherlands we use Google Analytics3 as our web statistics tool. This because it is free, easy to use, and easy to implement. And it gives all the information that our marketing and communication people need.In this paragraph it will be explained how you can add the code to the system, yourself.

•Step 1:Make a Google account (this is necessary for the administrator)

•Step 2:Log into Google Analytics with your Google account credentials

•Step3:Follow the instructions to complete your Google Analytics account

•Step 4:You will get a number and the ga.js code that looks like this:

<script type="text/javascript">var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));</script><script type="text/javascript"> try { var pageTracker = _gat._getTracker("UA-XXXXXXX-X"); pageTracker._trackPageview(); } catch(err) {}</script>

•Step 5:Replace the 'UA-XXXXXXX-X' with your Google Analytics code.

Follow the following steps to implement the Google Analytics code unobtrusive:

•Step 1:In the code, go to the following directory: a4b-site/src/main/site/resources/js/standaardscripts.jsIn this file all import of JavaScript is handled for the site.

•Step 2:Beneath the variable “var paginaTaal;” add the following variable: var pageTracker;

3 http://www.google.com/intl/en_uk/analytics/


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••

•Step 3:Beneath the function called toggleNext, add the following JavaScript:

/** JavaScript for Google Analytics*/

var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));

function startAnalytics(){pageTracker = _gat._getTracker("UA-XXXXXXX-X"); pageTracker._initData();

pageTracker._trackPageview();}

For the remainder, just follow the instructions from Google. It will take 24 hours, before the code is activated and will start to register all activities. If you want to filter out visits from your own company you can do so in your Google Analytics account. To find out how to do this, just read and follow these4 instructions.

2.4.1 How to add tracking for external links

We also keep track of our external links. Here5 you can find the instructions as Google provides them. We have implemented it in an unobtrusive manner. If you want to do this as well, just add the following function to the JavaScript file (behind the startAnalytics function).

function externalLinksAnalytics() {startAnalytics();

var externalLinks = document.getElementsByTagName("a"); var res = ""; var location = "http://" + document.domain; if (window.location.port != "") { location += ":" + window.location.port; }

4 http://www.google.com/support/analytics/bin/answer.py?answer=55481&cbid=ajfosb68qzxr&src=cb&lev=answer5 http://www.google.com/support/analytics/bin/answer.py?hl=en-uk&answer=72712


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••

var pattern = new RegExp(location);

for (i = 0; i < externalLinks.length; i ++) {

if (externalLinks[i].href != "" && !pattern.test(externalLinks[i].href)){

externalLinks[i].onclick=function() {pageTracker._trackPageview("/external_links/" +

this.href.replace(location,""));return true;

}//end }// end if }// end for

}// end function

You also need to call the function. This must be done from the function initializeAll(). Beneath: paginaTaal, add the following:

externalLinksAnalytics();

Internet Explorer handles it all in a different manner; so make sure to add the following beneath the comment /* for Internet Explorer*/:

if(window.addEventListener){window.addEventListener('load', ContentReady, false);

} else if(window.attachEvent){window.attachEvent('onload', ContentReady);

}

You will find the results of it in the report beneath: Content/ Content Drilldown.(The name is “ external_links”.)

This could also be done for downloads, like PDFs. But we have not implemented it; nor do we keep track of it.For more information about how to adjust your reports or add other functionalities just follow the instructions of the Google Help Centre6.

6 http://www.google.com/support/analytics/


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••

3 The CMSIn this chapter, you will find information about the CMS, from a developers point of view. Aspects like: how to adjust a (meta data) template and how to build/make an export file will be discussed.

The CMS used by the system is the Hippo CMS version 6 We strongly encourage the reader to browse the online documentation to get a good understanding of the internal functioning of this CMS.

3.1 How to configure the dashboard

The dashboard is the main page of the CMS, the one presented right after logging in. This will present a number of tabs and a number of different menus on the left. All of these elements can be configured via two metadata files contained in the repository.

3.1.1 Dashboard tabs

The dashboard, the standard version of the CMS, as distributed in the toolbox, presents 5 tabs:

•Dashboard•Search•Documents•Assets•Editing

One or more of these tabs can be removed or some new ones can be added. The configuration of the tabs structure is stored in the metadata document contained in the repository in the location configuration/perspectives/component.xml

As the toolbox is shipped the content of the file will appear as reported here below. We can clearly see the XML entry corresponding to every single tab.

<perspectives id="pm" className="PerspectiveManager"> <perspective src="cocoon://workbench/repository-configuration/perspectives/dashboard"/> <perspective src="cocoon://workbench/standard-configuration/perspectives/search"/> <perspective src="cocoon://workbench/standard-configuration/perspectives/documents"/> <perspective src="cocoon://workbench/standard-configuration/perspectives/assets"/> <perspective src="cocoon://workbench/standard-configuration/perspectives/editing"/> </perspectives>


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••

3.1.2 Dashboard menus

The dashboard menus on the left are configured in a configuration file in the repository, the configuration/perspectives/dashboard/component.xml. In there, for every menu to be displayed, an xml entry will be found.

For the New Document Wizard menu, for example, we will have the following xml entry:

<view src="cocoon://workbench/repository-configuration/perspectives/dashboard/views/newdocwizard"/>

referring to the repository folder perspectives/dashboard/views/newdocwizard. In there we will have a file component.xml describing the link in the menu:

<view id="newdoc" icon="documents" label="New Document Wizard" className="NewDocumentView" classSource="/wizard/js/NewDocumentWizardView.js" appUrl="/wizard/" bootParam="wizard-iframe" style="newdocwizard"/>

3.2 How to add a document type to the New Document Wizard

The dashboard presents a list of links on the left; one of this is called New Document Wizard and provides a shortcut to create new documents from a list of possible document types. This wizard can be customized to make new document types available.

The files describing the behaviour of the wizard are contained in the CMS module, more precisely in the folder src/main/site/wizard

The main file is the configuration.xml; in there you should make an entry for every document type you want to make available in the New Document Wizard.

By default one of these document types is the Product document type. It is maybe useful to have a look at the related entry in the configuration.xml to give an idea about how the whole mechanism works:

<resource:hippo id="product" type="product" name="product-title" ppath="nl/producten"> <widget:string id="product-title" skip="true"> <asp:property name="caption"/> <asp:xpath xpath="/document/content/general-item/title"/> </widget:string> <widget:string id="product-subtitle" skip="true"> <asp:xpath xpath="/document/content/general-item/subtitle"/> </widget:string>


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••

<widget:select id="product-type" src="cocoon://extensions/wizard/getProductTypes" /> <widget:select id="product-location" src="cocoon://extensions/wizard/getProductLocations" /> </resource:hippo>

From this XML we can see that when, creating a new document of the type Product, a form will be displayed asking for the following:•a caption which will be inserted in the new document in the content/general-item/title•a subtitle which will be inserted in the new document in the content/general-item/subtitle•a select with the possible product types produced from a call to the pipeline cocoon://extensions/wizard/getProductTypes retrieving the possible product types from the metadata document content/metadata/Producttype.xml•a select with the possible product locations produced from a call to the pipeline cocoon://extensions/wizard/getProductLocations retrieving the possible folders from the repository

When adding a new document type in the wizard a new entry in the configuration.xml will be necessary. This should contain the description of the fields to be contained in the form for the creation of the new document. Of course it is also necessary that the pipelines called to produce the values in the combo boxes are available and working fine.

3.3 How to translate or add labels in the Website

All the labels used by the Website are not hard coded in the pages, they are picked up from two metadata files present in the repository; one for the default language and one for the English language:

•content/metadata/message-bundles/messages.xml•content/metadata/message-bundles/messages_en.xml

These metadata files can be viewed and modified using the CMS. Simply log in in the CMS and browse the folders to the correct locations and open the file you are interested in. At that point you will see the list of labels. Every label is composed by a key (used by the Website to retrieve it) and a value (which will be displayed). In order to modify the value of a label, simply change the value and save the document.

If you want to add a new label to display in a customized page in the Website, the case is a little more complex. The list of keys the CMS expects to find are defined in the XML file called: keydefinitions.xml. Which you can find in the CMS in the folder:a4b-cms/src/main/site/types/messages/resources.

If you want to add a new label you should add it to the keydefinitions.xml. A new item formatted as shown below should be entered inside the catalogue element. Where * should be the key you wish to add and ** the default message.


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••

<message key="*">**</message>

Then rebuild the CMS with Maven and redeploy it to your web server. Only at that point the new key will be available and visible in the CMS when editing the documents messages.xml and messages_en.xml. At that point just insert the value you want to assign to the label for the two languages and save the documents.

3.4 How to adjust the export file

The export file is a file that contains data from the CMS which is exported to a CSV file. As a developer you can change the content of the export file by changing the code in the following files:•generalcontent.xsl•productExport.xml•sitemap.xmap•subsidieExport.xml•vacExport.xml

These can be found in: a4b-cms/src/main/site/export.

The most important one is in the file called generalcontent.xsl is. This is where the export file is actually being formulated. The other files, serve as input.

Users (editors) of the CMS use this file; to have an overview ofall the content that is present in the CMS.

3.5 How to make an export file

•Step 1:Login to the CMS (preferably the production environment)

•Step 2:Extend the URL with the following: /extensions/export/generalcontent.csv

•Step 3:Wait for the system to retrieve the information.

•Step 4:Save the document where you like.

•Step 5:Open the document with Excel or Open Office scalc.

If you are using Open Office scalc. ensure you tick the comma and the semi-colon (in the pop-up) before opening the document so the table displays the information correctly.


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••

3.6 Updating the zipcodes file

To ensure that the lookup of local information in the website and that CC (Cooperating Catalogues) products are correctly imported you must locale your postcode.xml metadata file.

The following steps describe how to perform this (based on a local deployment):

•Step 1: Open the zipcodes.csv file (a4b-xsd/src/main/webapp/zipcodes.csv).•Step 2: Localize this file. The structure is as follows:

wijkcode = zipcodeplaatsnaam = citygemeentenaam = municipalityprovincienaam = province

Example (dutch):

"wijkcode";"plaatsnaam";"gemeentenaam";"provincienaam" 1000;"AMSTERDAM";"AMSTERDAM";"Noord-Holland" 1099;"AMSTERDAM";"AMSTERDAM";"Noord-Holland" 1800;"ALKMAAR";"ALKMAAR";"Noord-Holland" 1801;"ALKMAAR";"ALKMAAR";"Noord-Holland" 1827;"ALKMAAR";"ALKMAAR";"Noord-Holland" 4260;"WIJK EN AALBURG";"AALBURG";"Noord-Brabant" 4261;"WIJK EN AALBURG";"AALBURG";"Noord-Brabant" 4264;"VEEN";"AALBURG";"Noord-Brabant" 4265;"GENDEREN";"AALBURG";"Noord-Brabant" 5300;"ZALTBOMMEL";"ZALTBOMMEL";"Gelderland" 5321;"HEDEL";"MAASDRIEL";"Gelderland" 5324;"AMMERZODEN";"MAASDRIEL";"Gelderland"

•Step 3: Rebuild and redeploy the a4b-xsd project.•Step 4: Execute the following url in the CMS:<cms-url>/extensions/zipcodes/postcodes.

After a little while some files will be replaced in the repository, namely postcode.xml and postcodelight.xml.

These files will be used as a base for zipcode-based lookups in the system. Verify them in the repository for correctness.


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••

4 The Cooperating Catalogues Export ToolIn this chapter you can find information regarding the CCET. The location of the XSDs of the tool are described, the location of the l18n files and the location of the CSS-files for the styling of the website. There is also a description of how grietje's domain configuration can be done and where the administrator account's log in details can be found.

4.1 XSD

The supplied XSDs should be placed in /var/tomcat/data/repository-sc-tool/xsd. These XSDs can be adapted in conformity with CC's specifications. Initially there will be the following XSDs:•audiencesc.xsd•government.xsd•language.xsd•municipalities.xsd•provinces.xsd•other.xsd•SamenwerkendeCatalogi.xsd•taxonomiesc.xsd

The XSD SamenwerkendeCatalogi, is the most important one.

4.2 I18N

In order to change the language in CC Export Tool the changes in the XSDs also have to be processed in the related Java code. You also have to amend the I18N property files. You can find these at: /nl/ictu/sc/web/WicketApplication.properties

4.3 CSS

The CSS files for styling are in the following folder: /nl/ictu/sc/web/page/resources/

4.4 Administrator account

The log in details of the administrator account are included in a property-file named logincredentials.properties. These credentials can be freely amended and amendments are immediately valid.


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••

4.5 Domain configuration grietje

The domain which the CCET runs on has to be configured for grietje.jsp. This domain is included in grietje.properties. This can be amended immediately and amendments are immediately valid.


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••

5 The PSC Message BoxThe first part of this chapter will explain what to do to change the look and feel of the Message Box Application. The second part will explain what steps a developer has to take to change the default language from Dutch to another language. For each of these two changes you have to rebuild the application which is explained in the third part of this chapter.

5.1 Look and feel

You can adjust the look and feel by editing the style sheets. Look for the style sheets in the web-ui project in the folder /src/main/webapp/css/

The images are located in the web-ui project in the folder /src/main/webapp/img. Please note especially the two images that use the dutch logo: logo-avb-print.gif and logo-avb.gif. You probably want to replace these, if you give your own logos the name of our logo they will be displayed in the application.

5.2 Language switching mechanism

The application supports the use of two languages, a default language and English. On the top of the screen the user has a tool bar to switch between a default language and the English language.

The initial language will be determined by the application based on the preferred language of the browser. If the default language or English is present in the preferred languages the application will use that language. If none of these is present the application will use the default language.

The standard Message Box application uses Dutch for the default language. To change the default language to your own language you have to take four steps:

1.Change the default language to your own language in BBoxLocale.java2.Create your own i18n file and put this file on the right location3.Create your own i18n file for notification messages and put this file on the right location4.Rebuild the application

5.2.1 Change the default language to your own language

The default language is set in the project web-ui in the java class BBoxLocale in the package nl.ictu.bbox.web.page.commons. Because the application uses Dutch as the default language, this is the parameter that has to be changed. Give the parameter DUTCH the value you want to support as default language.


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••

public static final Locale DUTCH = new Locale("nl", "NL");

5.2.2 I18N language files

The i18n files are in the project web-ui. Look for the file called BBoxApplication.properties which is probably in the folder /src/main/java/nl/ictu/bbox/web/application/. All the values of the labels in this file have to be translated. For the meaning of the labels you can look at the English language file (BBoxApplication_en.properties) in the same folder.

Pay special attention to the labels basepage.goDutch and basepage.goDutch.title. These two labels should be adjusted in both the default language file and English language file.

5.2.3 Create your own i18n file for notification messages

Look for the file called i18n-messages_nl.properties which is probably somewhere in a folder called /src/main/resources/properties/ You can copy this file to a file with your language extension in the name instead of “nl”. Put this file in the same folder. All the values of the labels in this file have to be translated. For the meaning of the labels you can look at the English language file (i18n-messages_en.properties) in the same folder.

5.2.4 Fine tuning details (optional)

In the wicketpage BBoxBasePage.html you can adjust the title of the browser window:

<title>eLoket - Berichtenbox | Antwoord voor bedrijven</title>

In the wicketpage MenuPanel.html you can adjust the title shown on top of the left menu:

<h2 class="sub">Berichtenbox <span class="textbrowse"><wicket:message key="np.navigation" /></span></h2>

5.2.5 Define the categories for the authorities

The application uses by default four categories for authorities: Municipalities, Waterboards, Provinces and Other. If you also need four categories you can just change the labels in the i18n files described in subparagraph 5.2.2,I18N language files.The application doesnt threat the categories differently from each other, so it doesnt really matter what the names or the labels of the categories are.

If you want more or less categories you need to adjust the java class AuthorityCategory in the package nl.ictu.bbox.model. If you want less categories you can just remove one or more, if you need an extra category you can add categories here, make sure you also add the same items in the i18n files.


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••

5.3 Rebuild the applicationYou can use the master-project to create a new version of the MessageBox.

Go to the directory bbox-eu with the pom.xml for the MessageBox Project. If you want to change the location of the modules which it depends on, change it in this pom.

mvn clean install

In the folder target a zipfile is available which holds this release.

5.4 The PSC Message Box Authentication

The PSC Authentication is used to protect the Message Box from unauthorized access. It is part of a larger project which is done by the Dutch government to provide a generic way for organisations to authenticate themselves to the government. Because of this larger project, the setup of the authentication provider may seem a bit complex and redundant. It is set up to allow for multiple authentication providers, and multiple applications which are protected by it.

Should you choose to use another form of authentication, you have to change the following points in the code and then rebuild the Message Box.

* in /web-ui/src/main/webapp/WEB-INF/web.xml 1.Remove / replace the filter with the name Aselect with your own authentication filter.2.Remove / replace the filter mapping with the name Aselect with the name of your own authentication filter. The servlet filter which does the authentication has to have the following characteristics. * Check whether someone is logged in, at every request.* Check whether the person making the request still has the correct credentials for this application, at every request.* If no one is logged in, or the person does not have the right credentials for this application he will not be permitted to continue in the filter chain. This filter has to have put the following attributes in the session for use in the application. "uid", "org", "user_attributes" in which at least the "kvknr" for the identification of the organisation, "auth_language", "auth_country" ASelectTicket in the package nl.ictu.bbox.filter of the component web_ui is the placeholder for the attributes which are used in the authentication filter (the above mentioned 5 attributes). This is also where the names of the attributes in the session can be amended. This placeholder is also used further in the application and these values are not taken from the session again elsewhere. This placeholder is filled with the correct values by the class AselectHelper. This helper class is used in 3 filters, namely:


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••

•BboxAcessFilter•BboxSpringSecurityContextFilter•Log4jMDCUserDataFilter.

5.4.1 Adjusting the PSC Authentication ProviderTo do so, you must execute the following four steps:

Change the web application pathThe default name of the web applications is “eovb”. By renaming the war before deployment or by renaming the <TOMCAT_HOME>/webapps/eovb/ directory the application path is changed.

Change the login screenThe HTML files of the authentication process are located in $ASELECT_HOME/work/aselectserver/conf/html. These can be tailored to the style and logo's the organization needs. The variables within square brackets should not be changed. At least the files:•error.html, •login.html, •logoutresult.html, •loggedout.html and •directlogin.html should be changed.If another language version of these files is present, look for file names like xxx_nl.html, where "nl" is the language extension used.

Change the look of the web applicationsAfter the eovb.war file has been deployed you will find the associated files in the Tomcat directory "webapps/eovb". To customize the application's screens the following files can be modified:•EovbHeader.jsp - Contains the top-most part of all screens.•EovbFooter.jsp - Contains the lower part of all screens.•css/* - The style sheets for the generated HTML-pages.•images/* - Images used in the HTML-pages.•js/* - Helper JavaScript functionality.

The UserEntry.jsp, PasswordEntry.jsp, OrgEntry.jsp, Admin.jsp and Result.jsp can probably be left alone. These files contain the central part of the HTML-pages.

Change the language of the web applicationsAll language dependant text can be found in the Tomcat directory:

"webapps/eovb/WEB-INF/classes/eovb"

For each file a Dutch and an English version is available.The Dutch version of the different files:•Common_nl.properties - General text, Result page and AdminMenu screen.


Date 11-01-10 | Version 1.4 | |


•••••••••••••••••••••••••••••••••••••••••••••••

•Org_nl.properties - Contains text for the Organization entry screens.•User_nl.properties - Contains text for the User entry screens.•Password_nl.properties - Contains text for the Password entry screens.

For the English versions, replace _nl by _en in the file names.

You can freely translate the text to your favourite language. You may however want to leave the [CAPITAL] stuff in place. This text will be replaced by the associated text that can be found in the configuration file "Configuration.properties" or is generated by the application.


Date 11-01-10 | Version 1.4 | |