List of resource type IDs

I have not included other Open Source modules or the OAMP suite. I may update this list later.

The JSP has no interface since I mainly use it for development. Simply create a JSP somewhere in the OpenCms VFS and then open the file via the browser. E.g.:

“http://workplace.com/system/createzip?source=/system/modules/foo&filename=foo-module.zip”

The source parameter specifies which directory to zip up and the filename parameter which filename to use for the generated file. You can only zip up resources with a total size of 10 megabytes. This is mainly to prevent OutOfMemory errors to happen. You can easily increase the size by altering the variable maxSourceSize to any value you need.

If you find any bugs or want to give feedback simply leave a comment or send me an email.

<%@page import="org.opencms.util.*,
                org.opencms.jsp.*,
                org.opencms.file.*,
                java.util.*,
                java.io.*,
                java.util.zip.*
" %><%

// Maximum filesize to prevent OutOfMemory errors
long maxSourceSize = 1024*1024*10; // 10 Megabytes

// The filename to use as output
String filename = request.getParameter("filename");

// The directory to zip
String source = request.getParameter("source");

if (CmsStringUtil.isEmpty(filename) || CmsStringUtil.isEmpty(source )) {
  // Ensure that all parameters are given
  throw new IllegalArgumentException("Please specify the 'source' and the 'filename' parameter");
}

if (!source.endsWith("/")) { source = source + "/"; }

CmsJspActionElement cmsa = new CmsJspActionElement(pageContext,request,response);
CmsObject cmso = cmsa.getCmsObject();
List zipResources = new ArrayList();

// Collect all the resources
CmsResource sourceResource = cmso.readResource(source);
if (!sourceResource.isFolder()) {
  throw new IllegalArgumentException("Please specify a folder to zip");
}
List cmsResources = cmso.readResources(source,CmsResourceFilter.DEFAULT);
for (Iterator i = cmsResources.iterator(); i.hasNext();) {
  zipResources.add(i.next());
}

// Create the zip file
ByteArrayOutputStream bos = new ByteArrayOutputStream();
ZipOutputStream zipfile = new ZipOutputStream(bos);

long currentSize = 0;
for (Iterator i = zipResources.iterator(); i.hasNext(); ) {
  CmsResource res = (CmsResource) i.next();

  currentSize += res.getLength();
  if (currentSize > maxSourceSize) {
    // Ensure that we don't zip up too much
    throw new RuntimeException("Source size is bigger than: " + (maxSourceSize/1024) + " kilobytes");
  }

  String sourcePath = cmso.getRequestContext().getSitePath(res);
  String targetPath = sourcePath;
  if (targetPath.startsWith(source)) {
    targetPath = targetPath.substring(source.length());
  }

  //out.println("Zipping " + sourcePath + " as " + targetPath + "<br/>");
  if (res.isFile()) {
  ZipEntry zipentry = new ZipEntry(targetPath);
  zipfile.putNextEntry(zipentry);
      CmsFile file = cmso.readFile(res);
      zipfile.write(file.getContents(),0,file.getLength());
  }
}

zipfile.close();
byte[] content = bos.toByteArray();

response.setContentType("application/octet-stream");
response.setContentLength((int)content.length);
response.setHeader("Content-Disposition", "attachment; filename=\"" + filename + "\"" );

response.getOutputStream().write(content,0,content.length);
response.getOutputStream().flush();

%>

The problem with OpenCms and App Engine is that the applications on App Engine run in a restricted sandbox which limits what you can do in terms of Java API functionality. There’s also a JRE whitelist which limits the classes you can access in your application. If you look at the scalability model promoted by App Engine these limitations make a lot of sense but unfortunately they make running OpenCms on there nearly impossible. You can find a detailed description of the App Engine runtime at Google code. The main problems are:

• No filesystem access: OpenCms uses the filesystem for some very important tasks:
  • The JSP files are exported into the WEB-INF directory to be executable. This means there could be no dynamic updates or adds of JSP files through the workplace.
  • The configuration is stored in the filesystem and dynamically updated if e.g. the search configuration is updated or a module is installed. The configuration would have to be stored in the database.
  • The search index is stored in the filesystem. This could be circumvented if a Lucene database store like the one shipped with Compass is used. Nevertheless this would have to be implemented.
• No threading: OpenCms makes uses of threading for scheduled tasks, publishing and other tasks. Since App Engine doesn’t allow threads this would have to be implemented otherwise.
• Response-Time-Limit: App Engine imposes a time limit to handle request on the application. Escpecially the publishing mechanism in OpenCms causes very long response times. These parts would have to be rewritten.
• Persistent data has to be stored in the datastore: OpenCms uses an in memory HashMap to store the locking information (file locks). This makes it difficult to cluster OpenCms and also limits the use in Googles App Engine. This also affects the Flex-Cache: Publishing events would have to be propagated and I’m not sure if this would work with App Engine (comments are very welcome on this point).

I had a short talk with Alexander about this topic and it at least seemed to us that making OpenCms run on the App Engine would be an enormous task and is currently not worth doing without excessive sponsoring.

By usage of the property folders.available (you might have to define it first) on a template you can specify a list of comma seperated folders in which the template is available (in the dropdown).

Unfortunately this property works only on file level and can not be inherited via the folder hierarchy. Also it does not provide a secure solution since the template can always be set via the advanced property dialog.

But you never know when a feature could come in handy.

You can even create the CSS and images using a wizard: http://jqueryui.com/themeroller

The resulting themes are dual licensed under the GPL and MIT license.

Andreas Rüping suggests in his book Agile documentation to create small and highly focused documents, targeted at:

• An explicit target audience (This dictates for example the kind of information and the tongue the document is written in)
• Readers interested in a special part of the project/information (This dictates the contents and structure of the document)

These documents are laid out in a document landscape. The landscape is formed by different types of documents (for example: Requirements specification, conceptual description, business goals, architecture overview, API description, etc.). The landscape is developed over time by creating template and example documents. If you start a specific project you simply pick the matching documents and fill them with contents. The maintenance of the landscape can be a project in itself or you can just develop it while you are working. The result is a (more or less) coherent set of documents across multiple projects which are short (easily digestible), focused and easy to navigate. You will become more and more familiar with the types of document over time and find the relevant information more quickly.

The Antagonist of this type of documentation is the almighty project document. It is a chimera born out of all different kinds of project documents and information. Most of the time it’s this kind of document which is shown to clients who really care about documentation. Often supported with sentences like “Look, we produced over 200 pages of documentation”. If you take a closer look at the document you will most often notice that the contents consists of:

• A (too) general introduction to the topic of the project
• A definition of goals
• Copy and pasted examples from the manuals of the libraries used in the project
• Duplicated reference manual sections of the libraries used in the project
• The complete source code/config files (of course not in sync with the VCS any more)
• No really clear statements of what should be done/has been done
• Information from different time frames (planning/implementation/review)
• …

This information is often not structured in a very good way and delivered in a PDF without a navigateable table of contents (so that page numbers in the ToC differ from the real page numbers) or hyperlinks. The fellow developers or administrators who have to work with the documentation will only get half of the needed information out of the it and will waste time checking back with the management folks. The resulting product will most certainly miss some important aspects and if you have to look back at the project you will surely be confused.

Additionally this document violates an important principle of concurrent access to a resource (speaking: teamwork): Keep the chunks which need to be accessed by multiple persons at the same time (programs) as small as possible. In a web project you often separate the program into a set of files defining the output (templates, view files, you name it) and a set of libraries/scripts/whatever. This is not only to keep the webdesigners from having to read the program code but also to allow the presentation and the program to be edited at the same time. Do yourself a favour and not only spend time designing your software, also design your project documentation.

One last word: Of course I consider myself guilty of having produced some kind of an almighty project document (although maybe not as evil as described above) from time to time. You simply can’t do  everything right in a constrained environment like the real world. But the more often we stress the importance of good documentation and information design we will maybe come to a point where good documentation is considered really valuable and therefore honoured and budgeted with time,dedication and respect.

Do you have your own thoughts documentation? Ever or never produced a real beast? Please comment.

Dilbert on documented processes

This is just a raw code dump not a step by step tutorial.

You can also download a ZIP file for importing it into OpenCms. But you have to adjust the paths manually.

Example JSP calls

<%@ page import="org.opencms.file.*,
                 org.opencms.jsp.*,
                 org.opencms.xml.*,
                 org.opencms.xml.content.*,
                 org.opencms.xml.types.*,
                 org.opencms.util.*,
                 java.util.*" %><%

// The resource to read
String resource = "/system/modules/de.himberger.sebastian.site/schemas/publication/manipulate.html";

// The locale to use
Locale locale = new Locale("en");

// The names of the elements
String versionElement = "Version";
String fileElement = "File";

CmsJspActionElement cmsa = new CmsJspActionElement(pageContext,request,response);
CmsObject cmso = cmsa.getCmsObject();

// read the resource
CmsResource xmlContentResource = cmso.readResource(resource);
CmsFile xmlContentFile = CmsFile.upgrade(xmlContentResource,cmso);

// Output current xml
out.println("<h1>Before</h1>");
out.println("<pre>" + CmsStringUtil.escapeHtml((new String(xmlContentFile.getContents()))) + "</pre>");

// build up the xml content instance
CmsXmlContent xmlContent = CmsXmlContentFactory.unmarshal(cmso,xmlContentFile);

// This is a new version (in this case it is a nested schema
I_CmsXmlContentValue addedVersionValue = xmlContent.addValue(cmso,versionElement ,locale,0);

// Add a new element to the created version (nested schema)
I_CmsXmlContentValue addedFileValueRaw = xmlContent.addValue(
  cmso,addedVersionValue.getPath() + "/" + fileElement,locale,0);
CmsXmlVfsFileValue addedFileValue = (CmsXmlVfsFileValue ) addedFileValueRaw;
addedFileValue.setStringValue(cmso,resource);

// manipulate an element
I_CmsXmlContentValue theSameValueWeAdded = xmlContent.getValue(
  addedVersionValue.getPath() + "/" + fileElement,locale);
// ... do the same as above

// add and remove a value
I_CmsXmlContentValue secondAddedVersionValue = xmlContent.addValue(cmso,
  versionElement,locale,addedVersionValue.getIndex()+1);

out.println("<h1>After adding</h1>");
out.println("<pre>" + CmsStringUtil.escapeHtml((new String(xmlContent.marshal()))) + "</pre>");

xmlContent.removeValue(secondAddedVersionValue.getPath(),locale,0);

out.println("<h1>After removing</h1>");
out.println("<pre>" + CmsStringUtil.escapeHtml((new String(xmlContent.marshal()))) + "</pre>");

// In the real world you would now do
// xmlContentFile.setContents(xmlContent.marshal());
// cmso.writeResource(xmlContentFile);
%>

Version schema

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">

       <xsd:include schemaLocation="opencms://opencms-xmlcontent.xsd"/>
       <xsd:element name="XmlContentPublicationVersions"
                    type="OpenCmsXmlContentPublicationVersions"/>

       <xsd:complexType name="OpenCmsXmlContentPublicationVersions">
               <xsd:sequence>
                       <xsd:element name="XmlContentPublicationVersion"
                                    type="OpenCmsXmlContentPublicationVersion"
                                    minOccurs="0" maxOccurs="unbounded"/>
               </xsd:sequence>
       </xsd:complexType>

       <xsd:complexType name="OpenCmsXmlContentPublicationVersion">
              <xsd:sequence>
                      <xsd:element name="Title" type="OpenCmsString" />
		      <xsd:element name="PublicationDate" type="OpenCmsDateTime" />
                      <xsd:element name="Description" type="OpenCmsString" />
                      <xsd:element name="File" type="OpenCmsVfsFile" minOccurs="0"
                                   maxOccurs="10" />
              </xsd:sequence>
              <xsd:attribute name="language" type="OpenCmsLocale" use="optional"/>
       </xsd:complexType>

</xsd:schema>

Publication schema

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">

       <xsd:include schemaLocation="opencms://opencms-xmlcontent.xsd"/>
       <xsd:include
            schemaLocation="opencms://system/modules/de.himberger.sebastian.site/schemas/publication/publication-version.xsd"/>

       <xsd:element name="XmlContentPublications" type="OpenCmsXmlContentPublications"/>

       <xsd:complexType name="OpenCmsXmlContentPublications">
               <xsd:sequence>
                       <xsd:element name="XmlContentPublication"
                                    type="OpenCmsXmlContentPublication"
                                    minOccurs="0" maxOccurs="unbounded"/>
               </xsd:sequence>
       </xsd:complexType>

       <xsd:complexType name="OpenCmsXmlContentPublication">
              <xsd:sequence>
                      <xsd:element name="Title" type="OpenCmsString" />
                      <xsd:element name="Subtitle" type="OpenCmsString" />
                      <xsd:element name="Description" type="OpenCmsHtml" />
                      <xsd:element name="Version"
                                   type="OpenCmsXmlContentPublicationVersion"
                                   minOccurs="0" maxOccurs="unbounded" />
              </xsd:sequence>
              <xsd:attribute name="language" type="OpenCmsLocale" use="required"/>
       </xsd:complexType>

</xsd:schema>

<cms:include file="/system/modules/com.example.ocms.commons/elements/pager">
  <cms:param name="currentPage">
    <c:out value="${model.currentPage}"/>
  </cms:param>
  <cms:param name="pageCount">
    <c:out value="${model.pageCount}"/>
  </cms:param>
</cms:include>

Became:

<wt:pager model="${model}"/>

Not does it only look cleaner and is much more focused, it also decouples your view more from the underlying CMS solution. Of course you could also develop a custom tag library using Java (which I have done a few times) but using a JSP the advantage that code can be changed on the fly and even from a web designer. You can always refactor your JSP taglib into a Java one if you need to do it. There are some limitations of JSP tag files (like you can’t use scriptlets in the body) but they are easy to get around.

But as always: This is no silver bullet. There are problems with tag files which may not be obvious at the first glance.

How to create a tag

Creating a tag is easy. I will show you the necessary steps while developing a tag which allows the user to loop over the contents of an OpenCms VFS directory.

Preparing your module

As normal Java libraries too, JSP tags need to be exported into the filesystem to be read by the Servlet-Container. Normally the tag files reside under a directory like ${yourwebapp}/WEB-INF/tags/mylibrary. So what we will do is adding a new export point to the module containing our tag files.

First we create a new directory called tags inside the module we want to contain our tags (normally I create a module for each site). The resulting structure will look something like this

The tags folder inside the module directory

Then we open the module administration and add an export point to our module (Administration -> Module Management -> Edit Your module -> Module exportpoints -> New exportpoint).

Adding the tags exportpoint

After pressing OK we are well prepared to add custom tags to our OpenCms module.

Creating the tag file

We now create a directory for our taglib. This will be located inside our newly created tags folder. Because we want to create a tag which interacts with the OpenCms VFS we will simply call the folder vfs. Inside this directory we create a new JSP resource called directoryLoop.tag. The result should look something like this:

The created tag file in the VFS

Now it’s time to write some code .

Writing the tag file

I don’t want to go into the details of developing tag files in general. This topic has been covered by dozens of books and online tutorials. I have collected some links in this blog post which explain the development of tag files in detail. Have a look at the section Further reading if you want to find out.

I will assume you’ve already developed JSP files inside OpenCms so I won’t explain the steps in detail. If you have questions regarding the sourcecode simply post a comment.

Here’s the commented sourcecode for our tag file.

<%@ tag body-content="scriptless" %>
<%@ tag import="org.opencms.jsp.*,
                org.opencms.file.*,
                java.util.*" %>
<%@ attribute name="folder" required="true" %>
<%@ variable name-given="resource" scope="NESTED" %>
<%@ variable name-given="status" scope="NESTED" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %><%

// First we get the pageContext variable.
// Tag files only have an explicit JspContext but in this case
// it is a PageContext which is a subclass of JspContext.
PageContext pageContext = (PageContext)jspContext;

// Instantiate the usual CmsObject to access OpenCms data
CmsJspActionElement cmsa = new CmsJspActionElement(pageContext ,request,response);
CmsObject cmso = cmsa.getCmsObject();

// Read the resources, note that we can access the tag
// parameters using the pageContext.
String folder = (String) pageContext.getAttribute("folder");
folder = cmso.getRequestContext().removeSiteRoot(folder);
List resources = cmso.readResources(folder,CmsResourceFilter.DEFAULT,false);

// We store the list of resources in the pageContext for usage with JSTL
pageContext.setAttribute("resources",resources);

%>

<c:forEach var="resource" items="${resources}" varStatus="status">
  <jsp:doBody/>
</c:forEach>

As you can see the tag file looks like a usual JSP file with only a few differences.

The tag exports two variables: The current resource and the iteration status. These can be accessed from the invoking JSP. We will make use of this in the next example.

To use the tag you have to publish the file so it gets written to the file system. After you’re finished writing/modifying the tag: Don’t forget to publish it!

You can’t preview tags, even though they are JSP files. You also won’t get compiler warnings. You always need a JSP file to test your tag files.

Using the created tag

We will use the created tag to implement a simple file browser. The file browser displays the contents of a folder and allows the user to navigate into subfolders recursively. Please note that this is definately no production ready code.

<%@ taglib prefix="vfs" tagdir="/WEB-INF/tags/vfs" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>

<%-- Determine the current folder, set to "/" if no parameter given --%>
<c:set var="folder" value="${param.folder}"/>
<c:if test="${folder eq '' or folder == null}">
  <c:set var="folder" value="/"/>
</c:if>
<html>
<head>
  <style type="text/css">

   .row-1 {
     background-color: #ECECEC;
   }

  </style>
</head>
<body>
<h1>Resources of folder "${folder}"</h1>
<table>
  <tr>
    <th></th>
    <th>Name</th>
    <th>Size</th>
    <th>Date created</th>
  </tr>
  <vfs:directoryLoop folder="${folder}">
  <%-- We use the status for alternating row classes, useful for css --%>
  <tr class="row-${status.count % 2}">
    <td>
      <%-- Display D for directory or F for file --%>
      <c:choose>
        <c:when test="${resource.folder}" >D</c:when>
        <c:otherwise>F</c:otherwise>
      </c:choose>
    </td>
    <td>
      <%-- If the current resource is a folder, display a link --%>
      <c:choose>
        <c:when test="${resource.folder}" >
          <a href="?folder=${resource.rootPath}">${resource.name}</a>
        </c:when>
        <c:otherwise>${resource.name}</c:otherwise>
      </c:choose>
    </td>
    <td>
      <%-- If the current resource is a file, display size --%>
      <c:if test="${!resource.folder}">${resource.length}</c:if>
    </td>
    <td>${resource.dateCreated}</td>
  <tr>
  </vfs:directoryLoop>
</table>
</body>
</html>

As you can see the tags are included with the directive.

<%@ taglib prefix="vfs" tagdir="/WEB-INF/tags/vfs" %>

The usage of the tags is similar to normal tags with the exception that you can’t use scriptlets in the tag bodies. If the example is working you should see something like the following.

The output of the created JSP

If you have trouble reading the above code. Here is a more condensed version of a file using the tag:

<%@ taglib prefix="vfs" tagdir="/WEB-INF/tags/vfs" %>
<ul>
<vfs:directoryLoop folder="/system/modules">
  <li>${resource.name}</li>
</vfs:directoryLoop>
</ul>

Things to keep in mind

JSP tag files and OpenCms really are a nice fit, but before you start working on converting all your custom includes to tag files keep in mind some of the disadvantages of tag files in respect to using <cms:include>.

• Tag files are not seperated by online/offline. Since the tag files only get exported during publishing there is no way of developing the tags in the offline project. You always have to publish the tag file to see your changes (It’s like a normal, Java based, tag library). This means if you have an error in your code the live system will be affected by it. In my opinion this problem is not as big as it sounds. Tags are normally developed in a staged environment or on a developer machine and then deployed on the live server. Additionally they are no replacement for templates and therefore shouldn’t be changed often.
• Tag files are not cached. The output of a <cms:include> may be cached by the OpenCms FlexCache. This can speed up the rendering enormously, tag files are always processed. In my opinion this no big problem. Tag files will mostly always be used in JSP templates which in turn will be cached by the FlexCache. I would suggtest that tag files are used as the building blocks for JSP templates and therefore are one a finer granular level. The chunks you want to cache are normally much more coarse grained.

Finishing thoughts

In my opinion JSP tag files are a great thing. They can help you clean up messy JSP templates and nicely decouple your JSPs from OpenCms (although I used a pretty OpenCms heavy example in this post). I hope this post was useful and helped you adding another tool to your toolbox. If you have further questions or need help regarding a specific project, please leave a comment or contact me directly.

Further Reading

These tutorials can help you developing your own tag files or looking up classes used in this tutorial.

• The JEE 5 tutorial on creating tag files
• An online tutorial on JSP tag files by Oracle
• A java.net article on tag files, short and good
• The OpenCms JavaDoc, always handy

“Enterprise software just means that it’s targeted at customers who can afford the guy who restarts the application server every few hours.”

I had to laugh because while the quote is clearly cynical it has a true core. Especially if you compare languages like Java and PHP it’s true that PHP doesn’t have these kind problems. This is mostly because of the throw-away-the-state nature of PHP. After every served request PHP forgets what it’s done before and has to completely rebuild the working environment at the next request. Java in contrast is able to remember things between requests. Which makes it more powerful but also harder to maintain (more state, more problems). I’m really not sure if I’m buying into this enterprise-thing anymore. Especially if you need scalability you definitely want to keep application state at a minimum and without state you don’t really need those big interconnected clusters of application servers any more.

Here is a nice talk about scalability and serious (speak enterprise) languages I found recently. It’s from Cal Henderson a software development guy at Flickr. It’s really worth watching. Even if you’re not into Python and Django.

(Watch it at: http://www.youtube.com/watch?v=i6Fr65PFqfk&feature=PlayList&p=D415FAF806EC47A1&index=10)

Open the file /system/workplace/resources/editors/fckeditor/editor/js/fckeditorcode_gecko_2.js in OpenCms and replace the text:

FCK.ExecuteNamedCommand('CreateLink',B);var C=document.evaluate

with:

FCK.ExecuteNamedCommand('CreateLink',B);var C=this.EditorDocument.evaluate

Publish the file and this should be it. Don’t forget to empty your browser cache afterwards (don’t just press CTRL+F5) otherwise you will still get the old file.

Of course this is not a real fix, but if you have to get rid of the problem fast. This can help.

Update: In OpenCms 6.2.3 the file is called fckeditorcode_gecko.js not fckeditorcode_gecko_2.js.