3.1.1Document properties in detail

« previous chapternext chapter »

Accessing a document in a JSP producing a website in a Generator service is explained in the previous chapter. All about the several types of document properties is explained within the admisistrators guide and the users guide. Now we look into accessing content from the several types of properties.

Assuming the object dmPage is of Type DocumentModel created from the JSP request like:

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

Accessing a String property

Assuming the constant PT_STRING_PROP_NAME is a valid property of type String within the document dmPage.

String s = dmPage.getString(PT_STRING_PROP_NAME);

The result s is filled with the valid value or an empty String. The String value is never null so it is empty if the document field is not filled.

String s = dmPage.getString(PT_STRING_PROP_NAME, errors);

The result s is filled with the valid value or an empty String. If the value was empty, an error message appears in the website preview indicating what field of what document is not filled.

String defaultValue = "Fallbackstring";
String s = dmPage.getString(PT_STRING_PROP_NAME, defaultValue);

If using a defaultValue, this value is returned if the property is empty. In this case no warning is shown in the preview website. If necessary an error message could be added manually.

Accessing a Date property

Assuming the constant PT_DATE_PROP_NAME is a valid property of type Date within the document dmPage.

Date d = dmPage.getDate(PT_DATE_PROP_NAME);

The result d is filled with the valid date object or null.

Date d = dmPage.getDate(PT_DATE_PROP_NAME, errors);

The result d is filled with the valid date object or null. If the value was empty, an error message appears in the website preview indicating what field of what document is not filled.

// Fetching the changed date of the resource (document)
Date defaultValue = dmPage.getResource().getChanged();

// and passing that date as default
Date d = dmPage.getDate(PT_DATE_PROP_NAME, defaultValue);

If using a defaultValue, this value is returned if the property is empty. In the example the date falls back to the date of the latest change of the document (date of last editing or publishing)

Accessing an Integer property

Assuming the constant PT_INT_PROP_NAME is a valid property of type Integer within the document dmPage.

int i = mrPage.getInt(PT_INT_PROP_NAME);

The result i is filled with the valid int value or -1 if the property is empty.

int i = mrPage.getInt(PT_INT_PROP_NAME, errors);

The result i is filled with the valid int value or -1 if the property is empty. If the value was empty, an error message appears in the website preview indicating what field of what document is not filled.

int defaultValue = 0;
int s = mrPage.getInt(PT_INT_PROP_NAME, defaultValue);

If using a defaultValue, this value is returned if the property is empty. In this case no warning is shown in the preview website. If necessary add a warning manually.

Accessing a Blob property

Assuming the constant PT_BLOB_PROP_NAME is a valid property of type Blob within the document dmPage.

byte[] blobData = mrPage.getBlob(PT_BLOB_PROP_NAME);

The result blobData is filled with the valid byte array or null if the property is empty.

byte[] blobData = mrPage.getBlob(PT_BLOB_PROP_NAME, errors);

The result blobData is filled with the valid byte array or null if the property is empty. If the value was empty, an error message appears in the website preview indicating what field of what document is not filled.

At the mimetype of the blob property it's decided how to handle the binary data. To get the MimeType use:

MimeType mimetype = dmPage.getBlobMimeType(PT_BLOB_PROP_NAME);

The MimeType object combines the internal mimetype ID with the name (text/plain, image/jpg, ...) and the ending of a file (.txt, .jpg, ...). The property itself only stores the internal minetype ID.

Performance issues

Reading and processing blob data is an expensive action. It is an extra load for the database and the memory management. So it is advised to read the blob only if preconditions apply. For instance if only an text blob content can be used at this point the code should look like:

String blobText = "";
if (dmPage.has(Types.PT_BLOB_PROP_NAME) && dmPage.getBlobMimeType(Types.PT_BLOB_PROP_NAME).getName().startsWith("text/")) {
  blobText = new String(dmPage.getBlob(Types.PT_BLOB_PROP_NAME), "UTF-8");
}

dmPage.has() returns true if the property is not empty and this is a property access without the expensive reading of the blob.

Examining the property access examples above:

byte[] blobData = mrPage.getBlob(PT_BLOB_PROP_NAME);

This is an expensive access especially if the property is empty.

byte[] blobData = mrPage.getBlob(PT_BLOB_PROP_NAME, errors);

This is not expensive because internally the emptiness is checked before access. But it's still unknown, which mimetype the content has. And maybe the access was necessary because the mimetype does not fit.

Accessing a Text property

The text property value is a String containing valid SGML code. The text is almost HTML containing non standard links and text components that have to be transformed into either standard HTML for a website or other formats for other content types.

Assuming the constant PT_TEXT_PROP_NAME is a valid property of type Text within the document dmPage.

String text = mrPage.getString(PT_TEXT_PROP_NAME);

The result text is filled with the valid HTML code or an empty String if the property is empty.

If not links or components are to be handled this way of accessing the text is sufficient for this purpose. This may be the case in simple teaser text fields or in meta description fields for page document types. Also within the configuration of these fields for the editors desktop inserting links and components can be disabled.

To transform links and handle components use TinyRichtextParts as described in a separate chapter.

Accessing a Linklist property

Assuming the constant PT_LINKLIST_PROP_NAME is a valid property of type Linklist within the document dmPage.

To get all documents from a linklist property use:

DocumentModel[] arLinkedDocuments = dmPage.getLinkedResources(PT_LINKLIST_PROP_NAME);

If no document is linked, the Array is simply empty but never null.

To only get linked documents of special resource types use:

ModelResource[] arLinkedDocuments = mrPage.getLinkedResources(PT_LINKLIST_PROP_NAME, RT_ARTICLE);

ModelResource[] arLinkedDocuments = mrPage.getLinkedResources(PT_LINKLIST_PROP_NAME, new int[] {RT_ARTICLE, RT_MEDIUM});

The array arLinkedDocuments contains the ModelResource objects for the documents of the requested types or the list is empty.

To only get the first linked document of the linklist property of any document type use:

ModelResource mrLinkedDocument = mrPage.getLinkedResource(PT_LINKLIST_PROP_NAME, 0);

If no document is available, a null value is returned.

ModelResource mrLinkedDocument = mrPage.getLinkedResource(PT_LINKLIST_PROP_NAME, RT_ARTICLE, 0);

This is the way to get the first document from the linklist property that is of document type article.

Using the ErrorView in these Linklist property access methods is also possible. But creating individual Error messages if linked resources are missing is recommended to clarify the reason for the document relation.