JAHIA CMS AND PORTAL SERVER

Transcription

1 Computer Practie JAHIA CMS AND PORTAL SERVER Web Application Developer Guide DRAFT VERSION Serge Huber Jahia Ltd 1.0 english Jahia Ltd 45, rue de la Gare 1260 Nyon Switzerland

2 i Disclaimers, Terms and Conditions DISCLAIMERS, TERMS AND CONDITIONS Copyright 2003 by Jahia Ltd. ( All rights reserved. THIS DOCUMENTATION IS PART OF THE JAHIA SOFTWARE. INSTALLING THE JAHIA SOFTWARE INDICATES YOUR ACCEPTANCE OF THE FOLLOWING TERMS AND CON- DITIONS. IF YOU DO NOT AGREE WITH THESE TERMS AND CONDITIONS, DO NOT INSTALL THE JAHIA SOFTWARE ON YOUR COMPUTER. 1. LICENSE TO USE. This is protected software (Jahia). The Jahia software is furnished under license and may only be used or copied in accordance with the terms of such license. Check the Jahia license ( to know your rights. 2. NAMES. The names JAHIA Ltd., JAHIA Solutions Sàrl, Jahia and any of its possible derivatives may not be used to endorse or promote products derived from this software without prior written permission of JAHIA Ltd. To obtain written permission to use these names and/or derivatives, please contact 3. DECLARATIONS AND NOTICES. This product includes software developed by the Apache Software Foundation ( Windows and Windows NT are registered trademarks of the Microsoft Corporation. For more information on these products and/or licenses, please refer to their websites ( Java is a trademark of Sun Microsystems, Inc. For more information on these products and/or licenses, please refer to their website ( Other trademarks and registered trademarks are the property of their respective owners. 4. DISCLAIMER OF WARRANTY. THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED WARRANTIES INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRAN- TIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DIS- CLAIMED. 5. LIMITATION OF LIABILITY. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS UP TO YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

3 ii Disclaimers, Terms and Conditions IN NO EVENT SHALL JAHIA LTD. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOW- EVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 6. GOVERNING LAW. Any action derived from or related to this agreement will be governed by the Swiss Law and shall be of the competence of the judicial authorities of the Canton of Vaud, Switzerland. 7. TERMINATION. This agreement is effective until terminated. END OF TERMS AND CONDITIONS

4 iii License agreement LICENSE AGREEMENT INSTALLING THE JAHIA SOFTWARE INDICATES YOUR ACCEPTANCE OF THE FOL- LOWING TERMS AND CONDITIONS. IF YOU DO NOT AGREE WITH THESE TERMS AND CONDITIONS, DO NOT INSTALL THE JAHIA SOFTWARE ON YOUR COMPUTER. The contents of this file, or the files included with this file, are subject to the current version of the Jahia Community Source License for the Jahia Portal Server (the "License"); You may not use this file except in compliance with the License. You may obtain a copy of the License at See the License for the rights, obligations and limitations governing use of the contents of the file. The Original and Upgraded Code is Jahia Portal Server. The developer of the Original and Upgraded Code is Jahia Ltd. Jahia Ltd owns the copyrights in the portions it created. All Rights Reserved.

5 iv Contents at a Glance CONTENTS AT A GLANCE WEBAPPS / PORTLETS DEVELOPMENT PART I Chapter 1 Introduction to Portlet Development... 2 Chapter 2 Compile and Deploy your First Portlet... 7 Chapter 3 Chapter 4 Porting existing applications to Jahia, or simply writing advanced applications with Jahia...13 Working with Jahia.org s Example Portlets...26 Chapter 5 Portlets Summary...39 Index...40

6 v Contents CONTENTS PART I WEBAPPS / PORTLETS DEVELOPMENT Chapter 1 Introduction to Portlet Development... 2 What is this all about?... 2 What is a Portal?... 2 Portal Features... 2 Portlet Definitions... 3 Pros and cons of portlet types... 3 Prerequisites... 4 Mixing Portlets and Content... 4 Support for standardized Java web applications and Frameworks... 5 Support of existing Web Application Frameworks... 5 Application generation tools... 5 Portlet standards... 6 The Java Portlet API standard (JSR 168)... 6 WSRP (Web Services for Remote Portlets) Standard... 6 Chapter 2 Compile and Deploy your First Portlet... 7 Hello Web Application... 7 Introduction... 7 Requirements... 7 Servlet code... 7 Web application deployment descriptor file... 8 Compiling the web application... 8 Packaging the web application... 9 Running the application... 9 Looking under the hood URL generation Web application entry point Chapter 3 Porting existing applications to Jahia, or simply writing advanced applications with Jahia...13 Introduction Key Basic things to remember for porting to Jahia Portal content size Web application contexts... 14

7 vi Contents Request/response processing Transforming action URLs to use encodeurl Single sign-on Web application role mappings Single entry point into web application Special request attributes set by Jahia Session Attributes Cache management Javascript issues CSS (Cascading Style Sheets) and Web Applications HTTP Redirects from web applications Chapter 4 Working with Jahia.org s Example Portlets...26 Web application Installation Installation a web application in Jahia Importing an existing web application from Jahia s public CVS Compiling a Jahia.org web application Database configuration OJB Database Configuration Understanding the Deployed File System Web application Deployment Automatic deployment of web applications Deployment descriptors overview Creating WAR and EAR files Re-deploying web applications Developing WebApps with an IDE (example with Jbuilder 8 EE) Chapter 5 Portlets Summary...39 Wrapping it up References Index...40

8 vii List of figures LIST OF FIGURES Part I Figure 2-1 Directory structure of the Hello web application... 7 Figure 3-1 Overview of request/response processing for a web application. Grey boxes represent J2EE container systems Figure 3-2 Class loader hierarchy in Tomcat Figure 3-3 Jahia Web application role mapping popup Figure 3-4 Cache processing during a request to a web application Figure 4-1 : Overview of the file system structure for a standard Jahia installation.. 31 Figure 4-2 : Jahia s file system overview Figure 4-3 : File system structure for a Jahia.org web application... 33

9 viii List of tables LIST OF TABLES Part I Table 1-1 : Possibilities of the different types of portlets... 3 Table 3-1 : Jahia-specific request attributes Table 3-2 : Cache modes and effects Table 3-3 : Special cache control request attribute Table 4-1 : Database creation script locations... 30

10 1 PART I - DRAFT - WEBAPPS / PORTLETS DEVELOPMENT

11 2 Chapter 1 Introduction to Portlet Development CHAPTER 1 INTRODUCTION TO PORTLET DEVELOPMENT 1.1. WHAT IS THIS ALL ABOUT? This manual presents different sections that details the specifics about writing portlet web applications for Jahia. We also cover some of Jahia s internal in the process when they are relevant to understanding why and how a certain subsystem works. We start with a short introduction on the context of portal and portlets WHAT IS A PORTAL? A portal is a feature-rich Web site. It provides a single point of access to enterprise data and applications, presenting a unified and personalized view of that information to employees, customers, and business partners. Portals allow you to have multiple Web applications within a single Web interface. In addition to regular Web content that appears in a portal, portals provide the ability to display portlets self-contained applications or content all in a single Web interface Portal Features Portals offer unified sets of features that concern both the end-user as well as the application developer. This section describes some of these features. Personalization and Authorization Because Jahia Portal comes with robust authentication and personalization features, administrators can determine what content a visitor can interact with and how that information will appear to the specific visitor. Visitors themselves can leverage Jahia Portal's personalization features to select their own content and create their own look and feel. A major component of the Portal development process is to create the elements that make such authorization and personalization possible. Group Portals Portals are designed either for single users or for groups. With group portals you can set up delegated administration for portals and restrict portal access to specific users. You can create multiple group portals within a portal Web Application. The group portals can share portal resources, such as layouts and portlets, but can be configured differently to satisfy the needs of each group separately. Because users are designated individually as members of a group, the group portal uses a static form of personalization. Unified User Profile In Jahia Portal, users are represented by user profiles. A user profile employs a user's ID to access such properties for that user as age or address. A Unified User Profile incorporates user data from external data sources in addition to or instead of LDAP servers, such as a legacy system or database, so that the user can access data from many different sources

12 3 Chapter 1 Introduction to Portlet Development through a single profile. During portal development, you will create this profile so that your Portal application can retrieve data from multiple external sources. Other Useful Features Jahia Portal also provides these other features that facilitate portal development: A layout paradigm for dynamic, interactive, personalized content Content modules called portlets, laid out in rectangular grids The ability to personalize portlets at many levels Delegated administration 1.3. PORTLET DEFINITIONS The term portlet is extremely used throughout the industry of web applications. A portlet can be anything from a portion of static HTML code to a piece of Java code. In order to clarify the notion, we will quickly present the definitions we use in this manual. Portlet A small HTML fragment element, usually in the form of a box on a page, which could be generated by different subsystems, such as a JSR 168 portlet application, a servlet that is included from the main page, or a JSP. JSR-168 Portlet API The Java Community Process has recently released the first version of the specification for the Portlet API. This is a standardized API to dispatch to portlet classes that generates HTML fragments. Jahia is currently working on integrating this standard, and we will update this document once this integration is complete. Web applications Jahia supports the use of standard J2EE web applications as the basis for developing portlets. This manual will therefore mostly cover this technique of building portlets. JSP It is also possible to build portlets simply by including JSP code in a JSP template within Jahia s context. This manual does not cover this type of development, but the template guide does, so if you are interested in this type of portlets, we strongly suggest you refer to that guide. Taglibs JSP may be messy to use as portlets if they are used in Jahia s web application context, unless there is a lot of available taglibs to use. Implementing portlet taglibs is another way of integrating HTML fragments. Notable projects that offer this type of functionality are Struts Tiles, Java Server Faces, etc... Again this is not the subject of this manual but is part of the template manual Pros and cons of portlet types There are some pros and cons for the various types of portlets. Basically we will cover in detail the limitations of using web applications in this manual, but we will quickly present here the other types, because depending on your needs you might be interested in one or another type of portlet. Table 1-1 : Possibilities of the different types of portlets Portlet type Standard spec Can work in standalone Java programming required In Jahia context Access to Jahia Content API JSR-168 Portlet API yes no yes no no J2EE Web application yes yes yes no no

13 4 Chapter 1 Introduction to Portlet Development Table 1-1 : Possibilities of the different types of portlets Portlet type Standard spec Can work in standalone Java programming required In Jahia context Access to Jahia Content API JSP yes no not necessarily yes yes Taglibs yes yes to use no, to yes yes develop yes 1.4. PREREQUISITES It is assumed in this manual that the reader is familiar with the following technologies: - Java programming language. - Java Servlet API especially HTTP Servlets. - Apache Tomcat - HTML, XML. - JavaScript, JSP files and Taglibs - Familiarity with Jahia s content model - Nobel prize in Quantum Physics In the examples, the Tomcat servlet container platform will be used. We recommend the reader to become familiar with this product MIXING PORTLETS AND CONTENT Jahia offers the possibility to mix portlets and content on the same HTML page since it offer the possibility to treat portlets as content from a template designer s point of view. In order to embed web applications in a Jahia template, he has the following possibilities: Embed it at a fixed place, or in a container list, as in the illustration below : Use the layout manager (MyYahoo-like home page), that offers powerful positioning possibilities such as column and row spans, moving of portlets, as illus-

14 5 Chapter 1 Introduction to Portlet Development trated below : 1.6. SUPPORT FOR STANDARDIZED JAVA WEB APPLICATIONS AND FRAMEWORKS Jahia is able to use standard J2EE web applications as portlets, provided a few modifications we present in the next chapters. Because of this capability, it means a lot of existing technologies and tools can be leveraged, since the Servlet API norm is now quite established and recognized as the de-facto standard for developing web applications Support of existing Web Application Frameworks Because of the possibility to use standard web applications, this also means that most existing web application building frameworks may be used to develop portlets. Examples of such technologies include: Struts, Java Server Faces, Webwork, Tapestry, JSTL Taglibs, There are some limitations as to the portability across J2EE servlet containers when using such frameworks, but with Tomcat most of these frameworks should work as expected Application generation tools There are also tools that may be used to quickly generate simple web applications. Often these should be used to quick-start an application development, but will need some modifying to properly integrate in the portal. Nevertheless, it might be interesting to use these tools if a great number of applications need to be developed. Also note that although these tools are cited here, there is no support offered for the use of these tools when integrating with Jahia, but hey, it might work :) Codecharge, JBuilder Enterprise,

15 6 Chapter 1 Introduction to Portlet Development 1.7. PORTLET STANDARDS For a long time there was no standardization effort in the field of portlet APIs. One of the many reasons was that portal vendors saw no incentive in standardizing one of the few ways left of locking-in developers. Fortunately with the commodotization of portals, this lock-in strategy started falling apart and new standards have recently been completed and are available or under implementation on most portals The Java Portlet API standard (JSR 168) Specified by: Java Community Process The Java Portlet API standard is an API mostly similar to the Servlet API, except that it specifies ways to build Java web applications that generate HTML fragments instead of complete pages. Because of this requirement and to allow for optimizations in the dispatching process, a request coming into a page is split into two sub request: an action request and a render request. The render request is basically the new sub-request that may be call more than once, while the action request will only be called once. Jahia will also introduce support for this API by integrating with the reference implementation of the API available here: WSRP (Web Services for Remote Portlets) Standard Specified by: Oasis Consortium The Java Portlet API standard is a great new addition to the J2EE platform, but it has one main drawback: it is Java-specific. One of the interesting ideas with portlets is to have the possibility to have an XML-standard to dispatch to portlets, which could be written in any language, available on other informations systems remotely, and aggregate the portlet onto our local portal. The idea here is to use the SOAP (Simple Object Access Protocol) XML standard to allow dispatching to remote portlets. These portlets may very will have been written in a different programming language, such as C/C++, or run on a different platform than the portal. One of the main drawbacks of this standard is that remote XML calls are usually quite slow, so the integration of system through such technologies should be reserved to applications that do not need to be accessed often. This standard will also be integrated into Jahia, but only after the Java Portlet API integration is complete, and will offer new possibilities.

16 7 Chapter 2 Compile and Deploy your First Portlet CHAPTER 2 COMPILE AND DEPLOY YOUR FIRST PORTLET 2.1. HELLO WEB APPLICATION Goal: Build and deploy a minimal web application from scratch Figure 2-1 Directory structure of the Hello web application Introduction Jahia allows the usage of standard J2EE web application as portlets, meaning that with some basic rules and modifications we can adapt existing web applications to work under Jahia. For this example, we will develop a small hello application that asks a user for it s name and then display a message saying Hello Name. The directory structure of our sample application is presented in The top-level directory name hello_webapp is not really important, and you can name it something else if you want, but the other two directory names are very important, and should not be changed, not even capitalized in a different way or else the application will no longer work correctly (this is a format defined by the J2EE web application standard) Requirements In order to develop, compile and run the following example, you will need the following installed on your computer: Recent Jahia package (version 4 or more recent), available at Sun JDK 1.4 or more recent, available at A text editor to edit the *.java files It is also assumed that you are reasonably familiar with all of the above software and that it is properly configured (i.e.: you have a JAVA_HOME environment variable pointing to your JDK installation) Servlet code Here is the code for the servlet that will contain all the code for the sample application. Note that this is not a recommend way to build an application, but it does have the merit of simplicity so for the moment we will not expand on it. 1 : // File : WEB-INF/classes/HelloServlet.java 2 : import java.io.ioexception;

17 8 Chapter 2 Compile and Deploy your First Portlet 3 : import java.io.printwriter; 4 : 5 : import javax.servlet.servletexception; 6 : import javax.servlet.http.httpservlet; 7 : import javax.servlet.http.httpservletrequest; 8 : import javax.servlet.http.httpservletresponse; 9 : 10 : public class HelloServlet extends HttpServlet { 11 : 12 : protected void service (HttpServletRequest request, 13 : HttpServletResponse response) 14 : throws ServletException, 15 : IOException { 16 : 17 : PrintWriter writer = response.getwriter(); 18 : String name = request.getparameter("name"); 19 : 20 : response.setcontenttype("text/html"); 21 : if (name == null) { 22 : writer.println("<form method=\"post\" action=\"" + 23 : response.encodeurl( request.getcontextpath() + "/hello" ) + 24 : "\">"); 25 : writer.println("enter your name: <input name='name'>"); 26 : writer.println("<br/><input type='submit' value='submit'>"); 27 : writer.println("</form>"); 28 : } else { 29 : writer.println("hello <b>" + name + "</b>"); 30 : } 31 : } 32 : } Before explaining all the details of the above source code, we will first describe the steps to compile, deploy and run the above application Web application deployment descriptor file J2EE web applications use a deployment descriptor XML file called web.xml, that basically contains information such as the name of the application, the servlets present in the application, the URLs that correspond to servlet, user role mappings, etc. For this application, again we will use a minimal web.xml file, which we will describe in more details after we have run the application for the first time. 1 : <?xml version="1.0"?> 2 : <!--$Id: web.xml,v /11/11 13:32:15 shuber Exp $ --> 3 : <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" 4 : " 5 : <web-app> 6 : <display-name>hello</display-name> 7 : 8 : <servlet> 9 : <servlet-name>hello</servlet-name> 10 : <servlet-class>helloservlet</servlet-class> 11 : </servlet> 12 : 13 : <servlet-mapping> 14 : <servlet-name>hello</servlet-name> 15 : <url-pattern>/hello</url-pattern> 16 : </servlet-mapping> 17 : </web-app> The location of the web.xml file must be (again this is imposed by the J2EE web application specification): WEB-INF/web.xml Compiling the web application Before it can be deployed and run, the application s source code must be compiled. The servlet we present has a dependency on the Servlet API s libraries, so we will need to include the

18 9 Chapter 2 Compile and Deploy your First Portlet servlet API library provided by Tomcat in our class path in order to compile the source code successfully. In Tomcat 4.1 this file is located in: TOMCAT_HOME/common/lib/servlet.jar whereas in Tomcat 5 it is located in TOMCAT_HOME/common/lib/servlet-api.jar TOMCAT_HOME is the directory where TOMCAT is installed. If you are using a packaged version of Jahia, this directory will usually be equivalent to: TOMCAT_HOME = JAHIA_HOME/tomcat To compile the Hello application, you must have a Java compiler available on your path and then you may type from the WEB-INF/classes directory: javac -classpath TOMCAT_HOME/common/lib/servlet.jar HelloServlet.java Of course in your are using Tomcat 5 or another J2EE web application container you will need another path to the Servlet API jar file Packaging the web application The standard way to package J2EE web applications is to build a WAR (Web Application Archive file). For our sample application, we can execute the following command from the hello_webapp directory: jar cvf hello.war. Note: the point at the end of the command is important, it means we want to build an archive from the current directory Running the application In order to run the application you will need to deploy it into the J2EE web application container, and then use Jahia s administration interface to make it available to users. The easiest way to deploy the application in Jahia s standard package is to use the built-in Tomcat. You can copy the hello.war file into the following directory: TOMCAT_HOME\webapps\jahia\WEB-INF\var\new_webapps\myjahiasite If all goes well, the file should disappear from the directory, which means it has been properly deployed in Jahia. If you have problems with the deployment, you should check in the site administration (Administration -> Manage portlets -> Component management options -> Automatic deployment mode) that the automatic deployment mode is activated for the site. You can also replace the above myjahiasite with another site name, meaning that the web application will only be deployed for that site. 1. Click on Add a portlet 2. From the Content drop-down, select Webapps and enter a title such as Hello Web Application

19 10 Chapter 2 Compile and Deploy your First Portlet 3. Click OK 4. Click Add a webapp 5. In the drop-down, select the Hello web application and click OK 6. If all goes well you should see the following screen: 7. Enter your name in the form and click on Submit, and you should see a response that says Hello your_name This concludes this step of running the sample application.

20 11 Chapter 2 Compile and Deploy your First Portlet 2.2. LOOKING UNDER THE HOOD Now that we have presented the steps required to develop, compile, package, deploy and run a simple application, we will go into more details, as to the important parts of each step, and explain how they interact with Jahia URL generation or why do we use response.encodeurl at line 23 in the hello web app source code? In general, web application have a lot of freedom on how to generate URL, whether they point to application actions (such as HTML form submission), external resources or just anchors on a page. As usual, lots of freedom means lots of ways to confuse and complicate things. The biggest problem specific to portals such as Jahia is that action URLs (form POST URLs for example), must generally point back to the portal, otherwise we will loose the context of the application s execution. A typical non-portal application could be generating URLs such as these: If the HTML generated by a web application contains such links in <A> tags, this means that when the user clicks one of these links, he will directly access the web application, completely bypassing Jahia s processing. This has two effects: no longer in Jahia s processing context no way to navigate back to Jahia (except for a browser s back button, but this is not what you user to have to do) So what is needed for web application to correctly integrate with a Jahia portal, is to rewrite their URLs to be Jahia-compliant. Fortunately Jahia intercepts an existing Servlet API response method called encodeurl to offer a service for rewriting URLs. If we look at the original JavaDoc definition for this method here is what we get: HttpServletResponse.encodeURL(String) public java.lang.string encodeurl(java.lang.string url) Encodes the specified URL by including the session ID in it, or, if encoding is not needed, returns the URL unchanged. The implementation of this method includes the logic to determine whether the session ID needs to be encoded in the URL. For example, if the browser supports cookies, or session tracking is turned off, URL encoding is unnecessary. For robust session tracking, all URLs emitted by a servlet should be run through this method. Otherwise, URL rewriting cannot be used with browsers which do not support cookies. Parameters: url - the url to be encoded. Returns: the encoded URL if encoding is needed; the unchanged URL otherwise Integrating the session ID in URLs is an important thing to do in web applications because it ensures that the application will function in environment that do not support cookies. Jahia modifies the semantic of this method to something like the following: Encodes the specified URL by wrapping it into a Jahia URL. This ensures that Jahia will get receives the request first, and then it will dispatch the result back to the application, by unwrapping it first. The application will see a regular request come in, so it can process it as it was a standalone web application. If we look at the what goes on behind the scenes in a response.encodeurl call we have something like this:

21 12 Chapter 2 Compile and Deploy your First Portlet The above sequence diagram illustrates the way Jahia intercepts calls to the request and response objects. We will present more details on all the intercepted methods in the next chapter Web application entry point Standard J2EE web application do not define a single entry point, but simply declare URL mappings such as in the following web.xml extract: 1 : <servlet-mapping> 2 : <servlet-name>hello</servlet-name> 3 : <url-pattern>/hello</url-pattern> 4 : </servlet-mapping> Basically this will map the servlet called hello onto an URL that looks like this: where the first hello is the name of the web application s context, which happens to be the same as the URL pattern defined in the web.xml. Another mapping that will also use the mapping is the following: A pattern matching is always a part of URL matching system, so the above URL will also call the hello servlet. Although applications may have multiple entry points, Jahia only supports a single entry point to a web application. In order to resolve the entry point, it uses the definitions in the web.xml deployment descriptor file, and tries to resolve an entry point based on the following sequence: 1. Is there a default servlet defined for mapping /? If yes, use that as the entry point 2. If no default servlet, let s look at <welcome-file> entries. If there is at least one define, use the first one as the application s entry point. 3. If there is no default servlet mapping or no welcome file, use the first declared servlet as the entry point. For most applications, the <welcome-file> method is the recommended way of declaring an entry point to Jahia. Basically you could have a <welcome-file> section that looks like the following: 1 : <welcome-file-list> 2 : <welcome-file>index.jsp</welcome-file> 3 : </welcome-file-list> And the index.jsp file could simply contain: 1 : <%@ page language="java" %> 2 : <jsp:forward page="/hello" /> This way you can precisely control your entry point, including calculating it based on same variables or anything you can come up with, such as a dispatching system to have entry points vary on some parameters such as the current user agent.

22 13 Chapter 3 Porting existing applications to Jahia, or simply writing advanced applications with Jahia CHAPTER 3 PORTING EXISTING APPLICATIONS TO JAHIA, OR SIMPLY WRITING ADVANCED APPLICATIONS WITH JAHIA 3.1. INTRODUCTION or what on earth is this section all about? Since Jahia offers an web application model that is quite close to the standard J2EE web application specification, porting an existing application is a process that is facilitated, but not without it s guidelines. Most of the guidelines presented in this section will be quite generic and not specific to Jahia, but some of the most advanced ones are. At the same time these guidelines of course also apply to new applications For the moment this section will not cover porting or writing new applications that are JSR- 168 compliant portlet applications, but once the support for this standard will be integrated in Jahia we will expand this section with relevant information about this new standard. Note that JSR-168 portlet application are more different from standard J2EE web apps than Jahia s web app model, so porting to the JSR-168 will require more modifications, but as the benefit of making the application a real (as in standard portlet). This document assumes that you have read and are familiar with the concepts presented in Chapter KEY BASIC THINGS TO REMEMBER FOR PORTING TO JAHIA In order for your web application to be transformed into a Jahia "portlet" web application, you should follow these basic rules: reduce content size for display within a portal the developer must understand that web applications are enclosed in contexts that have special limitations. call response.encodeurl on all action URLs generated by the portlet access login information through request.getremoteuser or request.getuser- Principal (Jahia maps the info through the use of Servlet API 2.3 wrappers for HttpRequest and HttpResponse objects) convert the application to use only one entry point, preferably as a JSP <welcome-file> in the web.xml deployment descriptor We will now present in more detail the above points as well as other important issues to correctly integrate your existing web application into Jahia.

23 14 Chapter 3 Porting existing applications to Jahia, or simply writing advanced applications with Jahia Portal content size or why can t I use up the whole page for my application? The first thing you can look at in your application is whether it will behave correctly in an HTML page consisting of multiple portlets, all displayed at once on the page. If you are trying to port an application that has always assumed it would be displayed alone on a page, you might run into some issues by trying to convert if it hasn t been properly designed for flexible view display. One good pointer is to make the application s HTML resizeable, meaning that the application doesn t assume a size in pixels, but can easily be resized to display each in full width of the page or in half or third width of an HTML page Web application contexts or why can t I access Jahia classes directly from my web application? In order to better understand how our web application integrates with Jahia, we will first start with a mile-high view of the structure of the whole J2EE web application container: HTTP Connector Servlet Container Services : -Session Management -Deployment -Dispatching to web applications -Resource sharing Servlet API Communication via Request/response wrappers Hello Classloader Jahia Classloader InfoNews Classloader Hello Web App Jahia InfoNews The first thing that we can note from this diagram is that all web applications are at the same level, including Jahia itself. Jahia is not a privileged application compared to another in anyway. It just has defined a way to communicate with other applications, by asking them to build content for a page display Request/response processing In order to better understand how the request and response processing is performed in a web application used by Jahia, we present here an overview of the communication system between Jahia and the application.

24 15 Chapter 3 Porting existing applications to Jahia, or simply writing advanced applications with Jahia Figure 3-1 Overview of request/response processing for a web application. Grey boxes represent J2EE container systems Request Response HTTP Connector Servlet Dispatcher Jahia RequestWrapper ResponseWrapper Servlet Dispatcher Hello Web App As we can see in Figure 3-1, Jahia uses the server s servlet dispatcher to call the web application. Before doing that it inserts wrappers around the request and response objects. These wrapper classes are specific to the Servlet API 2.3 and up, and they allow the definition of interceptor classes (classes that may intercept method calls on request and response objects), which is how Jahia manages to route different services to sub web applications, as well as post-process the output of the web applications before it is sent back to the client browser. Contexts and class loaders One important limitation of having separate web applications as portlets in a Jahia system is that each application is being executed in it s own separate servlet context. A context contains notably: class loaders for application specific classes and libraries session attributes (the session is unique for each client browser, but the attributes are local to a context and cannot be accessed from another web application s context) servlet configurations The notion context is very important, notably in environment where security is an issue. For example if we have two web application deployed in the same server in a hosting environment, they should not be able to interfere with each other if the server administrator does not want to allow it. Typically this means that cross-context dispatching will be forbidden. Jahia actually requires cross-context to be allowed, because it is itself a web application that wants to dispatch to other web application. The separate class loader limitation is very important. Basically it allows different web applications to use different versions of the same libraries without any conflicts. If we look at Tomcat s implementation and usage of class loaders, we can see that they are organized as a tree hierarchy, such as below:

25 16 Chapter 3 Porting existing applications to Jahia, or simply writing advanced applications with Jahia Figure 3-2 Class loader hierarchy in Tomcat Bootstrap System Common Catalina Shared Jahia Hello Web App The rules for class lookup are a bit particular, but here is a detailed order of lookup for a sample web application: 1. /WEB-INF/classes of your web application 2. /WEB-INF/lib/*.jar of your web application 3. Bootstrap classes of your JVM 4. System class loader classes (described above) 5. TOMCAT_HOME/common/classes 6. TOMCAT_HOME/common/endorsed/*.jar 7. TOMCAT_HOME/common/lib/*.jar 8. TOMCAT_HOME/shared/classes 9. TOMCAT_HOME/shared/lib/*.jar Basically the rule for lookup is the following: 1. Look in the current web application for a class 2. Then from the shared class loader, always first look in parent for a class, then in the current node. The reason we go into so much detail about class loaders is to correctly explain the fact that web application are not allowed to access Jahia classes directly, and this means they will have limited ways of communicating with Jahia, and especially they will not be able to access classes such as JahiaData or ParamBean since these classes are only present in Jahia s class loader. One way around this limitation would be to copy Jahia s classes into the shared class loader, but this might cause other conflicts with common classes between the web application and Jahia (usually this occurs with very common classes such as XML parsers, XSL transformers, logging classes, database drivers, etc...). Also, as this procedure is risky, it is not supported by Jahia s developers Transforming action URLs to use encodeurl As presented in Chapter 2, the use of response.encodeurl() method is central to porting an existing application to Jahia. The immediate question that comes to mind when working with existing code is: How do I know which URLs I should encode and which are the ones I can leave as they are? The easiest way to answer this, although not necessarily the most accurate would be: You should encode every URL generated by the application except for image URLs and in general access to static data (such as data files, etc.). The most important URLs to convert are <form> action URL such as the following:

26 17 Chapter 3 Porting existing applications to Jahia, or simply writing advanced applications with Jahia 1 : <form method="post" action="<%=request.getcontextpath() + /hello %>"> 2 : Enter your name: <input name= name > 3 : <br/> 4 : <input type= submit value= Submit > 5 : </form> The problem with the above code is that although it will work fine in a standalone web application, Jahia is no longer involved in the processing of the request, and we will loose all context information of the current Jahia user. Basically we want a way for the action URL to be modified so that we stay in a Jahia context. Jahia offers a URL modification services that is embedded in the call to the response.encodeurl() method, and that will perform the necessary URL transformations necessary to stay in the portal context. So the modified code that is portal-aware will look like this: 1 : <form method="post" action="<%=response.encodeurl( request.getcontextpath() + "/ hello" ) %>"> 2 : Enter your name: <input name= name > 3 : <br/> 4 : <input type= submit value= Submit > 5 : </form> Note that the above modification is in no way Jahia-specific in terms of implementation and will work seamlessly in standalone mode too. Actually the call to encodeurl is usually recommended if you want your application to support session tracking with clients that do not support or accept cookies. So in effect although this modification must be done everywhere an action URL is used, it will only improve your application and not make it specific to Jahia, but at the same time making it portal aware. You will also need to perform the encoding of URLs on HTML <a> tags if they are used to perform actions to a servlet. If they are links to external sites (such as in the case of a bookmark application for example), then they do not need to be encoded. It is also recommended not to encode URLs that do not need to be, such as usually <img> tags that access a static image (for dynamically images this is a different story), because it will make unnecessary requests to Jahia s portal, for resources that could very well be accessed directly Single sign-on or how can I make sure the user must enter his password only once for all portlets? As soon as you have multiple web applications running on a single servlet container, you will want to offer services to allow the user to login only once and be recognized in all applications. There are even cases where this must be done across servers and in such cases solutions such as Liberty Alliance ( become interesting. In Jahia portals, the goal is mostly to integrate with Jahia s authentication system and be able to re-use authentication information, so that the user only needs to login once in the portal. Basically, by using the request and response wrapper object presented in Chapter 2, Jahia maps authentication through the following method calls: request.getremoteuser() request.getuserprincipal() request.isuserinrole() It is assumed in this section that are familiar with the regular usage of these methods in standard J2EE web applications. If you are not, it is strongly recommended you refer to the J2EE specification and/or to guides on how to use these methods for user and role usage. Also it is also recommended that you become familiar with the deployment of web applications that use the methods in a standalone environment, which will greatly help when porting or writing the application for Jahia. We will now present the new semantics of the above method calls as they are defined for an application running under Jahia s context. For the original semantic of these methods we point you to the original Servlet API specification. HttpServletRequest.getRemoteUser() When running under Jahia, returns the login name for the current user. For example if the user that logged in Jahia is called root, this method will return a String containing root. Note that there is no guarantee that this name is unique when Jahia uses multiple sites, and

27 18 Chapter 3 Porting existing applications to Jahia, or simply writing advanced applications with Jahia that you may encounter multiple users with the same name, but that are coming from different sites. In order to get around this, you can use the context data sent by Jahia such as the current site, which the application may use to guarantee unicity of user information. We will details these context parameters further in this document. HttpServletRequest.getUserPrincipal() When running under Jahia, returns an Object that implements java.security.principal interface and that represents the currently logged in user in the Jahia portal. Again as with the getremoteuser() call, the getname() method on the Principal interface will not return a name unique to a Jahia installation but only to a site, so it is recommended to use this in conjunction with the sitekey that is available in special request parameters set by Jahia and described further in this document. HttpServletRequest.isUserInRole(String rolename) When running in Jahia, tests if the current logged in user is part of the role rolename. Usually in web applications you will want to use roles instead of users in order to allow users to combine roles and/or have separate responsibilities for groups of users. Role mappings are defined when instantiating an portlet web application on a page. The next section presents in details how role mapping works with Jahia. Figure 3-3 Jahia Web application role mapping popup Web application role mappings or how can I define and manage user roles in my web application? In the servlet specification, web applications have the possibility to declare and use roles to regroup users. Users may be part of multiple roles at a same time. The web application is not in charge of mapping users to roles, that is the responsibility of the J2EE servlet container. The application can then interrogate the servlet container to know whether a user is present in a role through the Servlet API call: HttpServletRequest.isUserInRole(String rolename) In the case of a web application running inside a Jahia portal, the mappings from user to roles will be performed by Jahia, and the above servlet API call will be intercepted to use Jahia s role mapping system. Figure 3-3 presents a screenshot of the HTML GUI interface for mapping roles to users and/or groups. Mappings roles to groups is a powerful way of mapping groups of users to a role. So in this example the manager role has been assigned to all members of the Jahia administrators group on the current site. As we can see in Figure 3-3, Jahia allows for graphical configuration of roles declared in web applications.

28 19 Chapter 3 Porting existing applications to Jahia, or simply writing advanced applications with Jahia Defining roles in a web application A web application defines the roles it uses by using the <security-role> tag in the web.xml deployment descriptor file such as in the example below: <security-role> <role-name>editor</role-name> </security-role> In the current version of Jahia, only <security-role> tags are used for role definitions, and <security-role-ref> references are ignored, so it is recommended that all the roles are properly defined with the <security-role> tag. When the web application is deployed, Jahia will read from the deployment descriptor the roles that were defined and will internally create groups for each web application that the user can manipulate using the GUI presented in Figure 3-3. An application can then test the presence of the current user in a certain role using code such as below: request.isuserinrole( editor ); Single entry point into web application or how do I know what servlet Jahia will call upon first access? Jahia supports only one entry point per web application, so it is important to know how to define this entry point so that you can route requests to the proper controller servlet in your new or existing application. We have already covered this topic in the previous chapter, under section Table 3-1 : Jahia-specific request attributes Special request attributes set by Jahia or how can I get information about Jahia s current context from my web application? Jahia inserts attributes into the request object that can be very interesting to applications developers. Note that the use of these attributes will make the application Jahia specific, whereas most of the other interceptors are not. The table below describes the name, type, possible values of the attributes set by Jahia and that may be accessed by web applications through the request.getattribute(string attributename) Servlet API call: Attribute name Type Value Description "org.portletapi.portal" String true Always set to value true in Jahia. This is the recommended way to determine whether it is running in standalone or within a Jahia Portal "org.portletapi.userlist" Vector of String objects List of user names Contains a list of user names that correspond to all the users that are in any role of the application. Useful to present a list of users for application-specific user assignments. Be warned though that it usually is a better idea to use roles for this but it may not always be possible. "org.portletapi.contextid" String == fieldid The contextid is a String that is useful to have an identifier to separate different instances of the same application. Jahia allows the same application to be instantiated multiple times on the same page. The contextid will be an identifier that will change among these instances, so that instance specific data may be stored in the application. In the current implementations of Jahia, the contextid is equivalent to the fieldid that contains the application. "org.portletapi.fullscreen" String true / false Not yet fully implemented. This attribute tells the application whether it is running in full screen mode or not. Basically if this attribute is true, the application may take over the whole screen, including HTML headers, etc.

29 20 Chapter 3 Porting existing applications to Jahia, or simply writing advanced applications with Jahia Table 3-1 : Jahia-specific request attributes Attribute name Type Value Description "org.jahia.sitekey" String jparams.getsitekey () The unique String identifier for the current site. You should use this in conjunction with the request.getremoteuser() call in order to make sure you have a unique user on a Jahia installation. For more information about the getremoteuser limitation check "org.jahia.siteurl" String jparams.getsiteurl () A String object that contains the siteurl parameter entered that usually corresponds to the domain name for the site, i.e.: etc... "org.jahia.siteid" String Integer.toString (jparams.getsiteid ()) "org.jahia.pageid", String Integer.toString (jparams.getpageid ()) String "org.jahia.operationmode", jparams.getoperation- Mode () A String object that contains an integer value that corresponds to the database identifier for the site. A String object that contains an integer value for the page number that the application is being displayed on. The current operation mode of the page. Possible values for this attribute in Jahia 4 are: normal (also called Live in our templates), edit (content edition mode), debug (not used, but still accepted in page URLs), preview (preview modifications to a page before it gets published in live mode), compare (a special mode to compare two versions of the content on the page) Session Attributes or how can I access Jahia s session attributes if at all possible? By default, Jahia does not share it s session attributes with application session attributes. This means that if you set an attribute in Jahia s session (through a scriptlet or tag in a template) using a call similar to this: request.getsession().setattribute( name, value ); You will not be able to access it from your application through the following call: request.getsession().getattribute( name ); This limitation exists for security reasons, as application should be as separates as possible in order to avoid namespace conflicts, as well as attribute corruption, etc. But it is possible to deactivate this limitation by using a special setting in the jahia.properties configuration file. webapps.dispatcher.inheritjahiasessionattributes = true The default setting is false, and settings this parameter to true will authorize web applications to access Jahia s session attributes. If you need to communicate in the other direction, from a web application to Jahia, it is not possible to use session attributes. You need to do this using request attributes Cache management or why isn t my application being called for each request that I make on a page? Jahia is an application that makes heavy use of data extracted out of a database. Unfortunately, a database back-end, while usually very scalable, is an expensive system in terms of performance. This is why database back-ends are often paired with in-memory caches to improve overall speed. This is possible because in a CMS and Portal server such as Jahia, read operations are much more frequent that write operations, so the benefit of caches becomes immediate. Basically Jahia has 3 caches that are important to application developers: 1. Front-end HTML page cache : used to store the full HTML generated by a request, so that subsequent requests for the same content will be served very quickly. This cache is the ultimate cache because it allows for extremely fast response times if it is not too often bypassed (unfortunately this is rarely the case for dynamic web applications). 2. Web application output cache : used to store the output of a single web application HTML fragment. The idea here is that when we have a page with more than one application displayed, we do not want to have the cost of dispatching

30 21 Chapter 3 Porting existing applications to Jahia, or simply writing advanced applications with Jahia to all the applications on each request when only one is really concerned by the current incoming request. This cache makes sure that we only really dispatch to the current target application, and that all others simply display whatever they were displaying previously. Of course this might cause problems if we have applications that must be refreshed regularly such as news tickers or instant messaging, but Jahia offers a way for applications to control this cache. 3. Web application request cache : used to cache the last requests that were sent to the application. This is mostly to make sure we remember the last application entry point used in cache the application request cache has been flushed. So basically the first entry point is automatically generated by Jahia based on the declarations in the web.xml (see the Entry Point section in this manual), and then subsequent GET requests are stored in this case in case we need to regenerate a call to the application. POST requests are never stored in this case in order to reduce the problems of submitting the same request twice. This implies that the same GET request may be posted multiple times to a web application, and that it should work despite that. Web applications running in a Jahia portal must be designed to work well with the various cache layers. It is important for application developers to understand how these caches work, because it will have important effects on the way the application is dispatched to. In the flow diagram on Figure 3-4 we present the processing for a request to a web application, in regards to how the different caches are accessed. This graph gives a detailed inside look as to how the caches are used. Incoming page request Outgoing page response Are we bypassing the HTML cache? Yes Are we processing a webapp action request? No No Is the page available in the HTML cache? No Is there an output cache for the webapp? Yes Yes Send HTML cache for page to client browser Get webapp output from cache Store page output in HTML cache Yes Yes No Store page output in HTML cache? No Is there a cached request for the webapp? No Build entry point request for webapp Dispatch to webapp Yes Store request in request cache for webapp Template-based Page aggregation Legend : Store webapp output in cache? Yes Store output in webapp output cache HTML Cache No Webapp Output Cache Webapp Request Cache Figure 3-4 Cache processing during a request to a web application In the above flow design, Jahia tries to use caches as early as possible to always keep total request time to an absolute minimum.

31 22 Chapter 3 Porting existing applications to Jahia, or simply writing advanced applications with Jahia Cache control through URL parameters Jahia offers a mechanism for controlling the front-end caches (HTML and web application output cache) simply through URL parameters. By default the front-end caches are activated. The name of the URL parameter is a path parameter called cache. So in effect here are different URLs that illustrates possible values for the parameter: (means the cache is on) The different modes not only control the loading from the cache but also the URL generation on the page. Depending on the cache mode the URLs will be generated with a special cache mode or not. The different modes are summarized in Table 3-2 :, and describe the mode that was specified in the URL parameter, whether Jahia will try to read from the cache, whether Jahia will update the cache, and finally the mode for the URL generation, which will basically be the next cache mode for the page. Table 3-2 : Cache modes and effects Mode HTML Cache Read HTML Cache Write URL mode on yes yes on offonce no yes on off no no off bypass no no on Warning : the /cache/off mode will generate all URLs on the page with /cache/off again, so this is not recommended when developing templates or generating your own URLs, because from that point on all navigation will be done in cache off-mode and be much slower. This mode is mostly reserved for development purposes, in order to check the functionality without cache. In this chapter we will not expand on this mechanism of cache control because the web applications are not able to control URL generation for a page, but this was presented for reference as it also helps explain how the cache works, and how it may be controlled for a page, notably for debugging and testing purposes. Cache expiration control mechanism Jahia offers a way for web applications to control the expiration of the web application output cache. Actually this will also control the expiration of the HTML cache, but this is transparently done by Jahia, so all you need to know is how to control the output cache. However, the web application request cache expiration can not be controlled by application, but it should not need to. Using a special request attribute name, an application can set an expiration delay in milliseconds for it s output cache to expire. This can be very useful for applications that need to be refreshed often, such as news syndication services, tickers, and so on. In Table 3-1 : Jahia-specific request attributes, we present the details of this mechanism for Table 3-3 : Special cache control request attribute Attribute name Type Description "org.jahia.portletapi.cacheexpirationdelay" Long Specifies in milliseconds the delay after which the web application output cache will expire. -1 means the cache will never expire, whereas 0 means the cache will never be stored. controlling the cache output. Again this is specific to Jahia so it will have no effect in standalone mode or on other portals.

32 23 Chapter 3 Porting existing applications to Jahia, or simply writing advanced applications with Jahia Javascript issues or why does my Javascript work differently on a page with 3 instances of my web application? Web applications use Javascript more and more to improve end-user experience. Using Javascript in portlets that generate fragments of HTML code can be a little tricky though, as the application developer does not have control over the whole page. HTML output issues For example, web applications are not allowed to generate an <html> tag, so that means they will also not be allowed to generate <head> tags, which often contain Javascript code. <script> tags must therefore be inserted in the flow of HTML where the application will be displayed. One way to get around the above limitation is to use request attributes to store fragments that are destined to the <head> tag in the template. This will work because of the order in which Jahia calls the web applications during the request process, which is basically: 1. Access to content & dispatching to webapps, storing the output of the applications in memory 2. Dispatch to page template for rendering back to browser So in step 1 we can set a request attribute that contains the HTML fragments destined to be inserted in the <head> tag, by used code similar to below: request.setattribute( headhtmlfragment_mywebapp, <script type= text/javascript >alert( test );</script> ); And then in your template, in the part that generates the <head> tag you can read the attribute from your web app, or even iterate over all the attributes generated by all the web apps on the page. Multiple instances of the same application on a page In a Jahia portal, it is allowed to have multiple instances of the same web application displayed on a page. Basically this means that if your application uses Javascript, it will have to be instance-aware. Instances are identified by the contextid attribute presented earlier in the special Jahia attributes. So it is highly recommended that this attribute be used to generate unique Javascript method names and objects. As this point can seem obscure, we will illustrate it with an example. Let s suppose we have an application that uses a form to submit user data. So our application generates an HTML fragment that looks like this: 1 : <script type= text/javascript > 2 : function submitform() { 3 : document.mainform.submit(); 4 : } 5 : </script> 6 : <form name= mainform action= <%=response.encodeurl(webappactionurl)%> method= post > 7 : <input type= text name= firstname /> 8 : <input type= text name= lastname /> 9 : <a href= # onclick= javascript:submitform() >Submit form</a> 10 : </form> The problem with the above code is that if it appears two or more times in an HTML page, we will have an invalid page that contains: 2 forms called mainform 2 scripts that are called submitform() In Javascript, overrides of functions are valid, but only the last one will be taken into account, so this means that if we click on the link on the first instance of the web application, the second instance of the Javascript code will be executed. The Javascript will then look for a form called mainform, and as they are two, the one that will be used will depend highly on the implementation of the browser s DOM (document object model). This code will have to be changed to allow for multiple instances in a single HTML page, such as below: 1 : <script type= text/javascript > 2 : function submitform_<%=contextid%>() {

33 24 Chapter 3 Porting existing applications to Jahia, or simply writing advanced applications with Jahia 3 : document.mainform_<%=contextid%>.submit(); 4 : } 5 : </script> 6 : <form name= mainform_<%=contextid%> 7 : action= <%=response.encodeurl(webappactionurl)%> method= post > 8 : <input type= text name= firstname /> 9 : <input type= text name= lastname /> 10 : <a href= # onclick= javascript:submitform_<%=contextid%>() >Submit form</a> 11 : </form> Basically what has been done is to make sure all the identifier are unique on the page, by using the contextid provided by Jahia. This ensures a correct behavior of the Javascript code as well as having compliant HTML form. Although this makes the code a little more complex, it is required for correct behavior in the case of multiple instances of a single web application on an HTML page CSS (Cascading Style Sheets) and Web Applications CSS are becoming more and more common in the world of HTML, and this is generally a good thing. However when dealing with web applications that must be adapted to generate fragments of HTML pages, there are some issues that need to be addressed in order to design applications that will fit into the portal. Ideally, the CSS styles should not be defined in the web application, but only used. This allows sharing of the look and feel among different portlet applications, and also makes changes to be performed easily, and even allows the use of themes that can modify the look and feel of the applications. Another added benefit of sharing style sheets is that it allows to avoid the namespace conflicts such as the ones we have identified in the previous section when dealing with Javascript code and/or forms. This ideal scenario does imply that existing web applications that already make use of CSS styles be modified to allow for external CSS files, and that work is done to unify the styles used, much like in the UNIX world people are now trying to make desktop applications look alike (through the use of standards such as GNOME). This might be a significant amount of work depending on the application s initial use of CSS, but in the long-term it is recommended. Even JSR-168 compliant portlets will face the same issue regarding CSS usage so it is not lost work when migrating to JSR 168 portlets. If it is not possible for a reason or another to unify the CSS among the applications to be deployed and used in a Jahia portal, then special care must be taken of name conflicts, just as is the case with Javascript and HTML form identifiers. Usually though it will not be a problem if the same style appears twice in the page for the same application, since we can reuse it without any problems. But if we have two different applications that use different style that happen to have the same name (such as maincolor ), then one of the two will need to be modified to correct the conflict HTTP Redirects from web applications or how can I perform a URL redirect from a portlet application that is called last on the page? The servlet API allows for a special HTTP redirect code to be sent back to the browser, in order to change the current URL that the user is requesting. There are rules on how to use this method specified in the Servlet API specification, mainly that the header must not yet have been committed, since this method actually adds a location attribute to the HTTP header of the current response. Of course the servlet API assumes that we are generating a whole response in our application, which is not the case when we are developing a portlet web application under Jahia. Basically what happens when an application does a call to such a method: response.sendredirect(myurl) Note that myurl does not internally call response.encodeurl, so if you want to redirect back to your web application you must perform the call like this: response.sendredirect(response.encodeurl(mywebappurl));

34 25 Chapter 3 Porting existing applications to Jahia, or simply writing advanced applications with Jahia Since Jahia first dispatches to web applications before dispatching to the JSP template that will be used to build the HTML page, redirect requests should work as expected, EXCEPT that it will be the first web application that performs a redirect that will win. If multiple applications decide to perform a redirect all at once, only the first will be taken into account.

35 26 Chapter 4 Working with Jahia.org s Example Portlets CHAPTER 4 WORKING WITH JAHIA.ORG S EXAMPLE PORTLETS This document explains: How to install a web application in Jahia How to import a webapps from the public Jahia CVS How to compile a WebApps How to deploy a web application on Jahia How to use an IDE to develop your webapps 4.1. WEB APPLICATION INSTALLATION Installation a web application in Jahia Jahia comes with a pack of web applications already available. We will not explain how to install these as all that is needed after Jahia's configuration is to restart Jahia once to make them fully available inside the portal. What we will quickly present here is how to deploy an application you have either developed yourself or downloaded from There are different ways to deploy applications in Jahia. We will present two of them here (leaving the others which involve low-level data structures manipulation). File-based deployment 1. Make sure you have fully configured Jahia and that you have a web site running 2. While Jahia is running, copy the EAR or the WAR file or your web application into the following directory : JAHIA_HOME/tomcat/webapps/jahia/WEB-INF/var/new_webapps/ SITE_NAME where SITE_NAME is the name of the site in which you want to make the web application available. The default SITE_NAME is "myjahiasite" and JAHIA_HOME is the directory where Jahia was installed 3. The application will then deploy and if all goes well you will see that it has become available in Jahia's administration interfaces (you must login with the superuser password to see it). Basically login, click on Administration, make sure you're administering a virtual site (upper right Switch mode to virtual site), click on Manage components. Web-based deployment 1. Launch Jahia 2. Login and go into the administration (click the administration button at the upper right of the web page) 3. Switch the mode to a virtual site if it's not on by default

36 27 Chapter 4 Working with Jahia.org s Example Portlets 4. Click on "Manage portlets" 5. Click on "Manually add a component" 6. In the select box here you must type a path to your web application. This may either be in the form of a PATH to a WAR or EAR file OR a directory where the application has already been deployed, for example : d:\jahia_402\tomcat\webapps\forum is a valid directory. Jahia will automatically look for a WEB-INF/web.xml file in that directory and deploy the web application 4.2. IMPORTING AN EXISTING WEB APPLICATION FROM JAHIA S PUBLIC CVS Please note that before using these steps YOU MUST have agreed to the license agreement that is available here : The following steps are Windows specific and use a free application called WinCVS ( but they would be quite similar using another operating system and CVS client. 1. Install WinCVS (available at 2. Launch WinCVS 3. Press the keys «CTRL + F1», then enter the following line into the CVSROOT input box : :pserver:anonymous@cvspub.jahia.org:/cvspub 4. Select the option «Login» from the «Admin» then click OK ; the password for the public cvs is : anonymous.

37 28 Chapter 4 Working with Jahia.org s Example Portlets 5. Change the browser s home location by selecting the option «Browse Location -> Change...» from the «View» menu, as in the example below : 6. Perform a checkout («Checkout Module» option in the Create menu) of the web application you want to work with or perform an update by right-click the name of the module in the browser view COMPILING A JAHIA.ORG WEB APPLICATION In order to compile a web application available on Jahia.org s CVS, you must have the following software properly installed : Sun Java JDK 1.4 or more recent, Apache Ant 1.5 or more recent, We will also assume in this section that you are familiar with Ant and that you understand how the build process works with this tool. You can then follow these steps to compile a web application : 1. Open the build.xml file in the directory of the application you have downloaded from the CVS, and modify the following line to point to your Jahia installation : <property name="deploy.webappsroot" value="jahia_home/ tomcat/webapps"/> where you must replace JAHIA_HOME with the directory where you have installed Jahia. This change is only necessary if you will want to deploy your applications directly using the Ant build system, which can be extremely useful during development.