Building OpenCMS 7
From InstallationWiki
| Official Page |
| Project Documentation |
| Download |
|
Contents |
[edit] Developing Basic Site Content
It is not necessary to create a development environment for basic OpenCms sites that consist of static HTML pages. For a site such as this one, we can use the Extended HTML Import feature to import our site into the OpenCms VFS. After we have imported our site, we will be able to edit it in the VFS, and then publish it. OpenCms will manage the different versions of our content, as we publish it. An additional advantage of using the Extended HTML Import utility for static content is that it separates our content neatly into Image, Link, and Document galleries. The Import utility creates references, automatically, inside the imported HTML, to these content items.
Once imported, we can edit our site pages with an in-site editing feature. The feature is accessible by clicking on the icon in the upper right of a content-editable region of the page we are previewing. Alternatively, we may navigate to the HTML page, using the Workplace Explorer. Once we locate it, we can use the 'Edit page' action to make our changes.
[edit] Setting Up an Environment for Creating JSP Code
Moving beyond this very basic type of editing, we will want to create an environment for developing JSP code. Although we can always use the Workplace Explorer to edit JSP files in the VFS, it is not well suited for development tasks. While there are many excellent code editors available that are better suited, there is no way to link any of these editors into the Workplace Explorer. Before we do this, lets create a JSP file in the VFS, first. From the Workplace Explorer, select the Offline project and ensure that the default site is selected. The default site appears in the Site pull-down menu as /sites/default. Then use the New button to create the JSP file:
Name the file Hello.jsp and uncheck the Edit properties of the new file option:
After clicking on Finish, the new file will exist in the VFS. To add code to the file after it has been created, the Edit sourcecode command is used.
As mentioned already, the source editor is sufficient for quick and dirty changes. But for full development, a more productive editor is preferred. There are three approaches that we can take, to use an external editor.
- Cut and paste from an external editor
- Editing via file synchronization
- Editing directly via WebDAV
The first approach is simple, and allows the use of any editor that we may be familiar with. However, this approach can be cumbersome and difficult when making changes to many files. While the second approach is a little better, it requires the server machine to be locally accessible. The last approach is the most useful, as it allows any editor and many files to be edited, and may also be accessed remotely. Let's take a look at the last two approaches.
[edit] Editing Files Using File Synchronization
The first approach is to utilize the OpenCms File Synchronization feature. This feature allows a location on a disk to be chosen, where files in the VFS will be mirrored to.
Once the files have been mirrored, they can be edited directly from within a developer IDE. Synchronizing the changes causes the VFS to be updated with the disk file changes. To configure file synchronization, select the Synchronization Settings icon from the within Administration view, located under the Workplace Tools icon.
Enable this feature by selecting the Enabled checkbox. The Target Folder field contains the folder location in the real file system, where the files from the VFS
should be mirrored to. The Resource option allows for multiple VFS source file locations to be selected. Each Resource or path added will have a corresponding sub-folder located underneath the Target folder path. Let's walk through an example:
For the target folder, first create a folder on the hard drive and then enter the path: C:\MySite.
For the resource, click the plus icon and enter the path: /sites/default/
Click OK to save the entries.
After selecting OK, use the Reload icon in the upper right of the Workplace Explorer. This will refresh the Workplace Explorer and cause the 'Synchronize
folder' icon to appear in the toolbar area. Select the icon, and then press OK to begin the synchronization process.
The synchronize action will always take the most recent file from each location and update the other location with it. Any files recently updated on disk will get put into the VFS, and any files updated more recently in the VFS will get updated on disk.
Any new files created on disk will get created in the VFS during the next synchronize action. However, this will only work after an initial synchronization has been done.
While doing this, don't forget that OpenCms file extensions do not necessarily reflect their OpenCms file types. When OpenCms writes a file from the VFS to disk, it writes the file on the disk to match the extension it has in the VFS. However, when going the other way round, OpenCms determines the VFS file type, based on the file extension on the disk. This means that a new JSP file created on disk with an HTML extension will get created in OpenCms with a type, 'plain'.
The Workplace Explorer may always be used to change the file type using the 'Change type' command. But it would be better to create the correct type, to begin with. This is possible by changing the file extension mappings. The mappings of file extensions to OpenCms file types are controlled in the opencms-vfs.xml
configuration file. This file is located at:
<opencms_install>\WEB-INF\config
To configure file mappings, locate the resource type to map a file extension to, and then add mappings to that resource type. Keep in mind that there may be only one file extension per resource type. For our example, if we wanted to ensure that files with the .html extension get set to JSP in the OpenCms VFS, we would make the following changes:
<type class="org.opencms.file.types.CmsResourceTypePlain" name="plain" id="1"> <mappings> <mapping suffix=".txt" /> <mapping suffix=".html" /> (remove this line) <mapping suffix=".htm" /> (remove this line) </mappings> </type> <type class="org.opencms.file.types.CmsResourceTypeJsp" name="jsp" id="4"> <mappings> <mapping suffix=".jsp" /> <mapping suffix=".html" /> (add this line) <mapping suffix=".htm" /> (add this line) </mappings>
The .html and .htm mappings have been removed from the plain file type and have been moved to the jsp file type. A restart of OpenCms is required for these changes to take effect. The next time OpenCms imports a file from disk with a .html or .htm
extension, it will appear as a jsp file type in the VFS. While making this change, we should also keep in mind that if we want to import an actual HTML file, we may have to revert our changes.
[edit] Using WebDAV for Editing
The previous approach works, but involves two steps and requires local access to the disk that the server is installed upon. Another approach to editing files is to access them directly, using the newly provided WebDAV support in OpenCms 7. WebDAV is an extension to the HTTP protocol that allows users to edit and manage files remotely.
OpenCms provides access to its VFS, using WebDAV, by pointing a web browser at the URL:
http://servername:8080/opencms/webdav
The OpenCms login credentials may be used in the authentication dialog. The browser may be used to navigate and view the files in the VFS. However, in order to edit and create files, a WebDAV client is needed. Most current operating systems provide a built-in WebDAV browser. Windows XP has one built into the Explorer, which can be accessed through the browser. To access it from the browser, select File->Open and enter the previous URL. Ensure that the Open as web folder option is checked.
After supplying the login credentials, the Windows Explorer will open up into the VFS:
Although Windows Explorer supports WebDAV, the file editor will also need to support it, to be able to edit and write files. Let's open Windows Notepad and place this code into it:
<%@ page pageEncoding="UTF-8" %> <%@ page import="org.opencms.jsp.*" %> Hello World My First JSP<br> <% CmsJspActionElement jsp = new CmsJspActionElement(pageContext, request, response); String strRoot = jsp.getCmsObject().getRequestContext(). getSiteRoot(); out.write( The site root is:" + strRoot); %>
This code should be saved into the Hello.jsp file that was just created. Unfortunately, Windows Notepad does not support WebDAV and thus the file cannot be saved
directly to the VFS. To get around this save the file locally, open the WebDAV location using Explorer, and then drag and drop the local file into it.
A workaround for editors that do not support WebDAV, is to use a free utility created by Novell that allows mounting a WebDAV location as a local drive. Information from Novell about this utility may be found here:
http://www.novell.com/coolsolutions/qna/999.html
After installing NetDrive, any editor may be used to edit files directly in the VFS. As soon as the file is saved from the editor, it can be clicked on in the Workplace Explorer to view the changes.
We now have two methods to create and edit application code that resides in the OpenCms VFS. Any JSPs that we create will have full access to the OpenCms Java API. To fully leverage the features of OpenCms, templates can be created to control the layout and functionality of the site. The template code is kept separate from the site content, to allow non-technical personnel to update the site.
Creating a template in OpenCms is simply a matter of creating a JSP file in the right location in the VFS. OpenCms requires that templates be placed into modules, and that the JSP code be placed into the templates directory of a module.
[edit] Debugging JSP Code in OpenCms
Developer tools such as Eclipse and NetBeans have rich environments that provide support for creating and debugging web application and JSP code. It is possible to use these environments to debug JSP code. But this requires that the project be set up in a specific way. We will show how this is done, using the Eclipse developer environment.
But before doing this, it is first helpful to understand how OpenCms handles the execution of JSP files from the VFS.
The first time a JSP file in the OpenCms VFS is served, it is written to the real file system, so that it can run as a normal JSP file would be run by the application server container. The location of the JSP file is configurable, and by default will appear underneath the WEB-INF directory of the OpenCms application, in a folder named jsp. Once the JSP is on the real file system, the OpenCms servlet will dispatch to it as a normal JSP file. If a breakpoint is set in the JSP file, the debugger must be able to match up the source with the compiled java class. The debugger will be able to locate the JSP source only if the project has been setup, with this in mind.
Now let's go through how to do this in Eclipse. We must first create the JSP within the OpenCms VFS. The JSP may be created anywhere, but for this example, we will use the Hello.jsp file we have just created. We first have to ensure that the JSP gets written to disk, by clicking on it within the Workplace Explorer. Remember that OpenCms will
write the JSP to disk and then execute it, displaying its output in the browser.
We now can set up the project in Eclipse. Using the New Project Wizard, expand the Java node and select Tomcat Project:
Provide a name for the project and click Next. On the next screen, provide a context name and web application root that matches the OpenCms web application installation. The default is /opencms, as shown in the following screenshot:
Click Finish to create the project.
Once the project has been created, the JSP files may be added to it. We want to add the JSP files that were written to disk by OpenCms. To do this, open the project, navigate
to the web application directory, and then select the WEB-INF folder.
The JSP files under this node may be added by right-clicking on it and selecting New > Folder. In the New Folder dialog box, open the Advanced option and check Link to folder in the file system.
The' Brows'e action can then be used to navigate to the existing folder. The folder to add is the location where OpenCms has placed the JSP files. The default location is:
<opencms_install>\WEB-INF\jsp
Navigate to this location, and click OK. On returning to the project, the jsp subfolder can be expanded to locate the Hello.jsp file. The file can be found at:
<project>\opencms\WEB-INF\jsp\sites\default\offline\Hello.jsp
After locating the JSP file, open it in Eclipse and double-click on the left gutter to set a breakpoint:
Now open your browser and run Hello.jsp by clicking on the Offline project from the Workplace Explorer. Eclipse will switch to debug view and will stop at the file source.
If Eclipse cannot locate the source of the file, the Edit Source Lookup Path button can be used to add the project path. In the Edit Source Lookup
Path dialog box, click the Add button and select File System Directory. Then browse to the location where OpenCms is installed and click OK. For
Tomcat, the default location is:
<tomcat_install_location>\webapps\opencms
After doing this, breakpoints can be set within the JSP code, and it may be walked through!
It is important to remember that although this method allows JSP code to be debugged, it is a one way trip, meaning that JSP files opened in Eclipse cannot be edited. Recall how the JSPs get written from the VFS to the disk. To make changes to the JSP file, one of the previously mentioned methods will need to be used.
It is also worth mentioning that best practices should be followed while writing JSP code. Although it is possible to write application logic in JSP code, it is better to encapsulate that code into Java beans or objects that the JSP uses. The majority of JSP code that makes up the OpenCms user interface, is written in this fashion. Following this convention will allow breakpoints to be set within Java classes, instead of debugging JSP code. It also allows for changes to be made directly to the loaded Java files.
[edit] Setting Up an Eclipse Environment to Build OpenCms
Moving ahead, JSP editing usually requires creating new Java classes that extend OpenCms. Although it is not necessary to build OpenCms in order to develop new code, it is often extremely useful to step through the OpenCms web application. In this section, we will cover the steps necessary to build OpenCms using Eclipse. Before starting,
we will need to install some tools.
[edit] Tools Needed to Build OpenCms in Eclipse
Sun Java JDK 1.5: The JDK is needed for us to build the OpenCms application. Although the older 1.4 JDK is supported, the default version and the one we are going to use, is the 1.5 JDK.
Download from: http://java.sun.com
Apache Ant 1.70: For building outside of an Eclipse environment, OpenCms provides ant build.xml scripts. Ant build scripts allow us to automate the process of building our Java projects. As Eclipse provides support for Ant build scripts, this tool only needs to be installed, if builds are to be done outside of Eclipse.
Download from: http://ant.apache.org/
Eclipse WTP 1.5.4: We may want to download and install the Web Tools Platform (WTP) version of Eclipse as it provides support for J2EE based web applications. After installing Eclipse, it should be configured to use the JDK that was installed.
Download from: http://download.eclipse.org/webtools/downloads/
Sysdeo Eclipse Tomcat Launcher plug-in: This is an Eclipse plug-in which provides us the ability to start and stop our Tomcat application server.
Download from: http://www.eclipsetotale.com/tomcatPlugin.html
Oracle JDBC Driver: The Oracle driver is optional, but is recommended. It may be needed if you intend to build OpenCms for an Oracle distribution, or if you want to eliminate all errors from your build. The ojdbc14.jar file needs to be downloaded and placed into a directory.
Download from: http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/index.html
[edit] Step 1: Checkout the Project Source from CVS
We start by creating a new project in Eclipse using the New Project Wizard. In the Wizard, locate the CVS option, select Projects from CVS and press the Next button.
In the Checkout from CVS dialog, provide the following information:
- Host:' cvs.opencms.org
- Repository' Path: /usr/local/cvs
- User:' anon
- Password:' anon
- Connection' Type: pserver
- Save' password: you may enable this, if desired
Pressing the Next button will bring us to the Select Module screen. Here, we have to check the Use specified module name option, and provide the value opencms.
After pressing the next button, we are asked how we would like the project to be checked out. We will take the default to use the New Project Wizard, and ensure that the Checkout subfolders option is checked.
Pressing the Next button will allow us to specify which version we would like to check out. At the Check Out As dialog box, we can use the Refresh
Tags action to retrieve the list of available versions, we may check out.
Expanding the Versions tree will reveal the list of available versions we may check out. To find out which version label to use for a particular OpenCms release is as easy as visiting the OpenCms website and looking at the associated release information. The version label is specified in the release notes. At the time of writing this tutorial, the most recent release is OpenCms 7 RC2, with a version label of build_7rc_2. Select the version you wish to check out and click Finish. This will bring us to the New Project wizard, as we had previously specified.
We now have to select Java Project and click Next. The New Java Project dialog box will appear next.
The project name will contain the name of the Eclipse project that we will create. It is good practice to use a project name that indicates the version of OpenCms, rather than just the generic name of OpenCms. This will allow other versions of OpenCms to be built, if necessary. For the Project Name, fill in: OpenCms_7RC2. For the JRE, we should use the JDK that was installed previously. For our project, we can use separate folders for our source and our output. To do this, select the Configure default option.
Ensure that the Folders option is selected, accept the default values of src and bin, and click OK. Clicking the Finish button will begin the process of checking out the project from the OpenCms source code repository.
[edit] Step 2: Setting the Classpath for Compilation
The checkout operation may take a while to complete. But when it is finished, Eclipse will attempt to compile the project immediately. OpenCms utilizes several other open source class libraries, which we must specify on the build path, in order to build successfully. We do this by right-clicking our newly checked out Eclipse project and selecting Properties.
In the project properties dialog box, select Java Build Path on the left, and then the Libraries tab. We then select the Add JARs button and add all the jars in, from the following locations:
OpenCms_7RC2/webapp/WEB-INF/lib OpenCms_7_RC2/modules/org.opencms.frontend.templateone.form/resources/system/modules/org.opencms.frontend.templateone.form/lib/
After specifying these libraries, Eclipse will once again compile the project. All errors will be removed except for the Oracle Database support. To remove these errors from the project we use the Add External JARs button to locate the ojdbc14.jar file and add it to our project build path.
[edit] Step 3: Using Ant to Build a Distribution Package
We have now successfully checked out and built OpenCms within the Eclipse Development Environment. The project settings will compile the java files in the project for us,
and will allow us to debug the OpenCms web application. This will be discussed in more detail, later on. However, if we want to build a distribution of OpenCms we will need to create jar files, zip files, and documentation. OpenCms provides an Ant build script to handle all this for us, and Eclipse provides support for executing an Ant build file.
The OpenCms build file uses some custom Ant build tasks, which are defined in jar files included in the source download. We must first configure the Ant environment to pick these jar files up as well as other jar files needed by the build file. From within Eclipse, select Windows > Preferences, expand the Ant option and select the
Runtime node.
In the Classpath tab, select the Global Entries item and click the Add JARs button:
In the dialog box, expand the OpenCms_7RC2/webapp/WEB-INF/lib node and select the following jar files.
- ant-contrib-1.0b1.jar'
- ant-opencms-1.1.jar'
- commons-beanutils-1.7.0.jar'
- commong-collections-3.2.jar'
- commons-digester-1.8.jar'
- commons-logging-1.1.jar'
Click OK to add the jar files.
The Ant build environment allows for property files to contain settings that are specific to each build platform. OpenCms takes advantage of this, by referencing the property values in its build script. We must set these property values within Eclipse according to our particular environment.
The Properties tab is where we will add these values. Select this tab and click the Add Property button. We will need to add the following properties:
-
tomcat.home: This property value sets the location of our Tomcat installation. The OpenCms build script also supports JBoss, in which case, you must set thejboss.homevalue. -
jboss.home: The OpenCms build script also supports the JBoss application server. If you are using JBoss, you may set this property value to the JBoss installation location. -
app.name: This property value contains the context name of the web application. The default value is 'opencms' but you may change this, if you decide to use a different context name. -
opencms.output: This property value contains the location that the compiled class and jar files will be placed into. -
opencms.input.externlibs: This property value contains the location of any external libraries that may be required . It is used by the build file to specify the location of the Oracleojdbc14.jarfile. -
modules.common.selection: When the build script creates a distribution, it allows for control over which optional modules get included. How the modules to be included get specified, is controlled by this property value. The possible settings are:interactive: If set to this value, then the build script will present a dialog box, where the user may select the modules to include in the build. This is the default setting.selection: If set to this value, then the modules to be included are specified by another property value:modules.common.selectionall: If set to this value, then the modules to be included are specified by theall-modules.propertiesfile. This file is located in the 'modules' subdirectory of the project source code.
We now can enable the Ant Window within Eclipse, by going to the menu and selecting Window > Show View > Ant. When the Ant build window appears, select the Add Buildfiles icon:
In the dialog box, expand the project OpenCms_7RC2 and select the build.xml file. The Ant window will show the build file with the target tasks inside it.
If we plan on working on more than one version of OpenCms, we should edit the build.xml file to change the project name from OpenCms to OpenCms_7RC2.
This will prevent our multiple OpenCms build scripts from having the same name of OpenCms in the Ant build window.
There is also a separate Ant build file for the OpenCms modules contained in the distribution. This build file is called from the main build file, but is provided to allow individual module builds, if necessary. To add this build file, select the Add Buildfiles icon again, and this time add the build.xml file located in OpenCms_7RC2/modules/.
We now can use the Ant build utility to build OpenCms from within Eclipse. There are several Ant tasks available, out of which, here are the most useful:
- bindist: This build target creates a complete OpenCms distribution along with all the modules. It is the same distribution that would be downloaded from the OpenCms web site.
- clean: This build target is used to clean up the build. All compiled classes and jars from a previous build are removed.
- jar: This target creates the
opencms.jarfile - tomcat.copy: This target copies the newly built
opencms.jarfile into the Tomcat application server directory. - jboss.copy: This target copies the newly built
opencms.jarfile into the Jboss application directory. - war: This target builds a
opencms.warfile that contains all the components selected for the distribution.
[edit] Building OpenCms outside of Eclipse Using Ant
If we want to build OpenCms from a command line, outside of the Eclipse environment, we just have to provide the property values for the build. To do this, we can create a
text file containing the build properties and specify it on the Ant command line. For example, the opencms.properties file might look like:
app.name=opencmstomcat.home=D:/apache-tomcat-5.5.20opencms.output=D:/AntBuildopencms.input.externlibs=D:/libsmodules.common.selection=all
The build can then be run with the Ant command:
>ant propertyfile opencms.properties [target]
[edit] Debugging OpenCms in Eclipse
Now that we can build OpenCms from source, we will be able to run it in a debugging environment. Although we do not want to modify the OpenCms source code, running through a debugger is a great way of getting a better understanding of how OpenCms works. This will help us when we create our own java classes that extend OpenCms. In order to debug, we may want to control our application server, from within Eclipse.
There are a number of Eclipse plug-ins available, that allow us to control the Tomcat application server. We will use the Sysdeo plug-in, which can be downloaded from the following location:
http://www.eclipsetotale.com/tomcatPlugin.html
The installation is very straightforward and the instructions are found on the web site. Now that we have everything we need, the steps to debug OpenCms are simple:
- Install OpenCms according to the OpenCms distribution instructions. After it has successfully installed, stop the application server.
- Use the jar Ant build target to build a debug version of the
opencms.jarfile. - Use the tomcat.copy Ant build target to copy the jar into our OpenCms installation directory.
- Start the Tomcat server using the Sysdeo plug-in.
- . Set a breakpoint in the OpenCms code and step through it.
We now will be able to peek into the inner workings of OpenCms using the Eclipse development environment.
[edit] Setting Up an Eclipse Environment without Building OpenCms
As mentioned earlier, it is not necessary for us to build OpenCms if we just want to develop code. In this case however, we want to create a library that allows us to easily
reference the OpenCms java files. To do this within Eclipse, we must first go to the Window > Preferences screen and expand the Java > Build Path > User Libraries node:
Click the New button and enter the name of our new library, OpenCms_7RC2, and then click OK. We now specify the jar files we want to put into our library, by using the Add JARs button. In the dialog window, navigate to the OpenCms installation and select the opencms.jar file. Any new project we create will be able to add this Library to the build path and use the OpenCms API.
[edit] Additional References
- For instructions in Accelerating Template Development in OpenCMS 7, click here.
- For instructions on Installing OpenCMS, click here
- For instructions on Developing Templates in OpenCMS 7, click here
- For instructions on Customizing OpenCms Site, click here
- For instructions on Troubleshooting Open CMS Installation, click here
- For instructions on Installing Open Source CMS, click here
[edit] Source
The source of this content is Chapter 2: Developing in OpenCms of OpenCms 7 Development by Dan Liliedahl Packt Publishing, 2008).
