3.1Working with document properties

3.1Working with document properties

« previous chapternext chapter »

With an example of an article document this chapter shows how a JSP gets access to the document and document properties to produce an article website.

The following conditions for this JSP apply

  • There is a document type article. It has a String property named headline.
  • There is a document of type article in a folder. (i.e. /en/news/news1)
  • The Generators generatorconfig.txt has an entry to use the page-article.jsp if a request targets a document of type article with the ending .html. The config entry looks as follows:
doctype=article, .html, page-article.jsp
  • The Generator service configuration allows generating of documents in the folder /en.
  • An URL http://myproject:[generator port]/en/news/news1.html is called.

With these preconditions applying the page-article.jsp is accessing the article document, reading and producing the articles headline into a web page.

<%@page import="
                app.cmsworks.cms.document.ErrorView,
                app.cmsworks.cms.document.DocumentModel,
                app.cmsworks.util.uilink.UILink,
                app.cmsworks.cms.document.HTMLErrorView
               "
        session="false"
        contentType="text/html;charset=UTF-8"
%><%@include file="includes/documentmodel.jsf"
%><%
DocumentModel dmPage = null;
ErrorView errors = new HTMLErrorView();
UILink uiLink = new UILink(request);
String htmlMetaTitle = "";
String htmlHeadline = "";
// fetch the sensible data
try {
  dmPage = new DocumentModel(request, new Types());
  errors.setPreview(dmPage);
  
  htmlHeadline = dmPage.getString(Types.PT_ARTICLE_HEADLINE, errors);
  htmlMetaTitle = htmlHeadline;
}
catch (Throwable t) {
  if (!errors.exit(response, t, dmPage, this.getClass().getName())) {
    %><%= errors.render() %><%
    return;
  }
}
//now start the HTML-Output
%><!DOCTYPE html>
<html lang="en">
  <head>
    <title><%= htmlMetaTitle %></title>
    <%= uiLink.getIncludes() %>
  </head>
  <body class="article">
    <%= uiLink.getPageLink() %>
    <h1><%= htmlHeadline %></h1>
    <%= errors.render() %>
  </body>
</html>

This example just shows the access to the article document when requesting an URL to a Generator JSP for an article.

The first line to access the article is this one:

dmPage = new DocumentModel(request, new Types());

With the request object from the Servlet the DocumentModel object will provide access to the Generator service (the service the JSP was executed in) as well as to the CMS service. The document is requested from the CMS service and is available too.

To get the field content from the String property headline the following line is used:

htmlHeadline = dmPage.getString(Types.PT_ARTICLE_HEADLINE, errors);

DocumentModel

This class represents a document and provides access to the CMS and to the interface of an UrlCreator. It wraps the document to extend the basic Resource implementation by adding an advanced error support accessing wrong or empty fields and supporting URL creation.

int documentId = 30;
DocumentModel dmAny = new DocumentModel(documentId, dmPage);
dmAny.getCMS(); // returning the CMS
dmAny.getMyService(); // returning the service the JSP is executed in
dmAny.getId(); // returning the document id

A DocumentModel can be created

  • from a Request-Object of the Servlet
  • from a document id and another DocumentModel
  • form a document id and singularly the CMS service, the service implementing the UrlCreatorable interface and the Types object

Document property contents can be fetched with the following Methods:

dmAny.getString("propertyname");
dmAny.getText("propertyname");
dmAny.getInt("propertyname");
dmAny.getBlob("propertyname");
dmAny.getDate("propertyname");
dmAny.getLinkedResources("propertyname");

Types

The Types object is an implementation of the DocumentModelConstants interface adapted by the DocumentModelConstantsAdapter.

Primarily this class contains static constants defining the document types and properties of the projects document model.

Overriding the methods of the Adapter returning real values for special document types and property names enables the usage of special features like categories or teaser functions.

This types implementation is put into the documentmodel.jsf which is used in the example above.

<%@page import="app.cmsworks.cms.document.DocumentModelConstantsAdapter"
        pageEncoding="UTF-8"
%><%!
public class Types extends DocumentModelConstantsAdapter {
  /*
  Constant prefix RT means ResourceType
  Constant prefix PT means Property of Type
  */

  // =====================================================================
  public static final int RT_MEDIUM = 1;
  
  public static final String PT_MEDIUM_DATA = "data";
  public static final String PT_MEDIUM_WIDTH = "width";
  public static final String PT_MEDIUM_HEIGHT = "height";

  // =====================================================================
  public static final int RT_ARTICLE = 2;
  
  public static final String PT_ARTICLE_HEADLINE = "headline";
  public static final String PT_ARTICLE_TEXT = "text";
}

%>

Defining document type model constants in documentmodel.jsf

The constants about document type ids and property names combining the document type and field name secure the usage of those properties in the ongoing development. Always adjust the type definitions after changing the document model of the project. And all Errors while compiling the JSPs will show up to be adjusted to the new document model. Also no property name can be misspelled when using the constants.

ErrorView

The ErrorView is simply created with

ErrorView errors = new HTMLErrorView();

After initializing the DocumentModel from the request it has access to the Generator configuration and knows if the Generator creates a preview or a production (live) page.

This info has to be passed on to the ErrorView with

errors.setPreview(dmPage);

Every access to a document property could be on a wrong or empty field. In programming it would always be needed to check manually if the content is properly available. The ErrorView is handling those errors.

When accessing a document field content the ErrorView object can be added like this:

htmlHeadline = dmPage.getString(Types.PT_ARTICLE_HEADLINE, errors);

If the property content is missing, the ErrorView gets a new entry to be shown in the web page of the PreviewGenerator. Now the editor of the article document knows that for this web page the field content of the headline must be filled.

If the programmer used a wrong field a CMSPropertyAccessException arises which stops any further content processing. No exception is thrown if the field is just empty.

Further checking if the content is acceptable depends on the usage of the field content and must be implemented individually. So for example if the content is not empty but too long a self created Error message can be added:

errors.add("The headline is too long!");

To also create a reference to the missing field content a link can be added:

errors.add(errors.asUILink(dmPage) + "The headline is too long!");

If a missing content should lead to not producing the website and should abort any further processing, the following construct can be used:

if (htmlHeadline.length() > 200) {
  errors.abort(errors.asUILink(dmPage) + "The headline is too long!");
}

If a field content is optional do not use the ErrorView. The following may apply

if (dmPage.has(Types.PT_MY_PROPERTY)) {
  sbContent.append("<p>" + dmPage.getString(Types.PT_MY_PROPERTY) + "</p>");
}

For finally rendering the errors into the web page the following code is placed at the end of the body tag:

<%= errors.render() %>

Those error are only produced if the generator is configured as preview generator. In live/productive generators the render-call will produce nothing.

UILink

UILink uiLink = new UILink(request);

UILink is a class to provide connections to the documents used to create the web page. Mostly multiple documents are used in one website and those documents contents will be displayed. The UILink is a helper for editors to directly open such a used document for editing. Press Shift + Control to activate the Links in a preview website.

To create such a link the JSP has to contain:

<%= uiLink.getPageLink() %>

The document called by the request (dmPage) is referenced by this UILink.

When using other documents contents within the website those documents can also be accessible using:

<%= uiLink.getLink(dmAny.getResource()) %>

The document dmAny is some other document that is used in the page because it's a linked document or a search result or something.

To enable the engine of UILinks (activating the shortcut listener) the following code has to be placed at the head of the website:

<%= uiLink.getIncludes() %>

The following chapter will now deal with the access to documents properties in detail.

« previous chapternext chapter »