The Plumtree Development Environment: UI Customization

Setting Up a 5.0.x Portal Development Environment (Java)

This page explains how to compile and run the UI projects with Eclipse and how to build a new WAR file using Ant.

Software Requirements & Recommendations

Before beginning any installation, make sure you have installed the components listed in the table below.

The variables listed in the table below are used in this guide to reference the location of the associated application.

Installing Portal Source Code

Note: Before installing the portal source code, confirm that you have a working Java portal. If you have trouble with installation, refer to the Plumtree Corporate Portal Installation and Upgrade Guide.

1. Extract UISourceCode.zip from the CD and copy the resulting \UI Source Code folder to the C:\ drive. This folder contains the following projects:

2. • nullnavigation
   • portal50
   • portalnavigation
   • portalpages
   • portalsamples
   • portaluiinfrastructure
   • samplePEI
   • userprofile

(The folder also contains a \zBuildIncludes subfolder that contains all the necessary build scripts for the Ant build.)

2. Add the necessary environment variables to the system:

The next step is to compile the UI source code using the Eclipse IDE.

Compiling Portal Source Code: Eclipse

Follow the instructions below to compile the UI source code using Eclipse. If this is the first time you are compiling the portal code, you must first complete the steps in the previous section.

1. Open Eclipse and click Window | Preferences.

2. Navigate to Java | Classpath Variables.

3. Click New to add a new variable. (All JAR references within the source code projects are done through a classpath environment variable.)

4. In the New Variable Entry window, enter PORTAL_HOME as the Name for the variable and click the Folder button. Navigate to PT_HOME\ptportal\5.0. Click OK to accept the location and click OK again to close the Preferences window.

5. Click File | Import. Select Existing Project into Workspace option and click Next.

6. Click Browse and navigate to SOURCE_HOME\nullnavigation\java. Click OK, then click Finish.

7. Repeat steps 5 and 6 for the following projects:

• portal50
• portalnavigation
• portalpages
• portalsamples
• portaluiinfrastructure
• samplePEI
• userprofile

8. In the main window, select all the projects, right-click, and select Refresh.

9. In the Eclipse Menu, select Project | Rebuild All.

The next step is to debug the compiled source code.

Debugging Portal Source Code: Eclipse

To debug the source code, first set up the Eclipse debugger for Tomcat by following the directions below.

1. In Eclipse, select Window | Open Perspective | Java.

2. Click Run | Debug... and double-click on Java Application. Name the project "Tomcat".

3. Browse the projects and select portalpages.

4. In the Main class field, type the following: org.apache.catalina.startup.Bootstrap

5. Click the Arguments tab.

   1. In the Program arguments window, type the following: start
   2. In the VM arguments window, type the following: -Djava.endorsed.dirs="..\bin;..\common\endorsed"-Dcatalina.base=".." -Dcatalina.home=".." -Djava.io.tempdir="..\temp"
   3. Under Working directory, uncheck Use default working directory, and select Local directory.
   4. Click Browse, navigate to TOMCAT_HOME\bin and click OK.

6. Click the Classpath tab.

   1. Click the Bootstrap subtab.
   2. Uncheck Use default class path.
   3. Click Add External JARs and add the following files (you can add one file at a time):
   4. • JAVA_HOME\lib\tools.jar
      • TOMCAT_HOME\bin\bootstrap.jar
      • TOMCAT_HOME\common\lib\servlet.jar

   5. Still on the Classpath tab, click the User classes subtab.
   6. Select all the existing projects and JAR files and click Remove.
   7. Click Add External JARs and navigate to PORTAL_HOME\lib\java. Select all the files in the folder (Ctrl-a), then deselect portalpages, portalluiinfrastructure, portal50, and servlet (hold Ctrl while you select the files). Click Open.
      Note: You should depend on the projects in Eclipse for the first three library files. If you wanted to debug the other project files you could leave out those JARs as well. servlet.jar is not included because you have already included Tomcat's servlet.jar.
   8. Select activation.jar (at the top of the list) and click Add Projects. Add the following projects:
      • portalpages
      • portaluiinfrastructure
      • portal50.

      Note: The other projects are included through the JAR files because in most cases, you do not need to debug through them (you can only step through source code that has been included via a project).

   9. Uncheck the two boxes labeled Add exported entries of selected projects and Add required projects of select projects.

7. Click Close and save the Tomcat configuration.

8. In the Eclipse package explorer, navigate to LoginView.java in the portalpages project (com.plumtree.portalpages.browsing.login).

9. Scroll down to the Display() method and add a breakpoint as shown below (double click in the grey left margin in front of the line on which you want to set the breakpoint).

10. Click Start | Programs | Plumtree and open PTSpy. Confirm that info logs are enabled: go to View | Runtime Settings and make sure Info-Severity Tracing is checked.

11. In Eclipse, select Run | Debug... and choose the newly created Tomcat application.

12. Hit Debug. (You can ignore the log4j warnings printed out to the console.)

13. After you see a message in PTSpy indicating that startup was successful, open a browser window and navigate to your portal. You should hit the breakpoint when you get to the login page. Use the options under the Run menu to Step Into, Step Over, Step Return, Resume or Terminate.

14. Note: If Tomcat doesn't start and if you get the following exception in the Console: Catalina.start: java.lang.NullPointerException, select Run | Debug..., select the Tomcat application, go to the Classpath tab, move xerces144.jar to the top of the list and try again.

You can now start creating your own project and begin customizing your portal. When you are done, you must update your production machine with a new WAR file. The next section explains how to build the new WAR file using Ant.

Building the New WAR File Using Ant

To successfully update and deploy custom Java code, you must run the provided Ant scripts to compile all Java code and create a WAR file (collection of JAR files) to be placed in the deployment directory of the portal environment.

Note: To use Ant scripts for deployment, the PATH environment variable must include the paths to the ANT_HOME\bin and JAVA_HOME\bin locations.

Follow the instructions below to compile the UI projects and build the WAR file.

1. Download the AssemblyInfo.zip file from the Threads and Samples page of the Developer Center. Unzip it and copy the resulting \assemblyinfo folder to the PT_HOME directory.

2. Open a command prompt and change the directory to SOURCE_HOME (i.e., the location of the c_buildui.xml script).

3. Run a clean build using the following command: ant -f c_buildui.xml dev.clean.tomcat
   
   Note: A clean build deletes all the source projects' classes and JAR files. They are then rebuilt and deployed. If the build is unable to delete jar files, make sure that you are not running or debugging the portal.

4. You should get a message about a successful build. The new WAR file is created under PORTAL_HOME\webapp.

You can now create your own project and begin customizing your portal. For details on creating custom projects, see Creating a Custom Project. For a list of topics, see the table of contents.

Next: Installing UI Customization Sample Code