Content Object in Velocity

You may access the field values of any piece of content from Velocity code. To access the value of any Content field:

1. Retrieve the content object for the content.
   • This can be done with any of the $dotcontent Viewtool pull methods, or by invoking whichever of the three built-in content objects is most relevant. For more information, please see Pulling and Displaying Content for the general function, or Accessing Content Via Built-in Objects for the simpler, most recommended approach.
2. Access the field as a property of the content object.
   • The name of the property is the Velocity variable name assigned to the field in the Content Type.
   • Note: The property name is case-sensitive, so the case of the property name must exactly match the case of the variable name in the Content Type.

Simple Example

The following code displays the “Title” and “Text Field” fields from a Content item:

#set($content = $dotcontent.find("4d7daefa-6adb-4b76-896d-c2d9f95b2280"))
Title:      $content.title
Text Field: $content.textField

Alternately, using a built-in content object, you can skip that initial assignment. For example, inside a container, you might elect to use $dotContentMap:

Title:      $dotContentMap.title
Text Field: $dotContentMap.textField

Subsequent examples will proceed with the latter approach, but note that it remains perfectly valid to use $dotcontent.find() to pull the content object.

Embedding HTML in Content Fields

By default, all properties of Content objects retrieved through Velocity code are interpreted by both the HTML and Velocity parsers, allowing you to embed HTML formattting and Velocity code within Content item fields.

Embedded HTML

For example, consider a content item with the “Title” field set to the value <i>About Us</i> (including the HTML <i> and </i> tags), and the following Velocity code used to display the title field:

<b>Welcome</b> to the $dotContentMap.title page!

The value of $dotContentMap.title in the Title field is output exactly as it is stored, so the following HTML will be displayed (and sent to the user's browser):

<b>Welcome</b> to the <i>About Us</i> page!

getRaw Method

Since Velocity code in Content fields is interpreted, if the fields are intended to display characters which have special meaning in Velocity, the fields may not display as expected. To prevent this, you may use the getRaw() method to stop the field values from being interpreted. To use this method, replace the name of the field variable (e.g. $dotContentMap.textField) with .getRaw(), passing the name of the variable as a string to the getRaw method (e.g. $dotContentMap.getRaw("textField")), as in the following examples:

Contents of the Text Field:

This tutorial will show you how to use a #define directive in a C program.

When accessed directly using the Content object variable (e.g. $dotContentMap.textField), the #define will be interpreted as Velocity code, so the text in the field will not display correctly. (In fact the page may not display at all, since the “#define” in the text field is not properly formed Velocity code, so the Velocity parser will treat it as an error).

However, if the getRaw() method is used instead (e.g. $dotContentMap.getRaw("textField")), the entire field will be passed through without interpretation, so the #define will not cause any problems and the field and page will both display correctly.

Content Type Fields

Each field of a Content Type may be accessed by referencing the Velocity variable name of that field within the Content Type. For most field types, the value of the field is a simple type (such as String or Integer) and may be referenced directly. However some field types are returned as Velocity objects, which allows you to then access multiple separate properties of the object (for an example, please see Host/Folder Field, below).

The following examples show how to access the values of different types of Content fields in your content objects.

Please see the Pulling & Displaying Content — or $dotContentMap — documentation for more information on how to retrieve content from the Content Repository.

Basic Properties

The following properties of the content object are available for all content, of all Content Types.

Simple Field Types

The following types of Content Type fields return simple values when accessed as properties of the content object. These field values may be accessed and used directly in your Velocity and HTML code.

Files and Images

File Assets

uri:        $dotContentMap.fileAsset.uri
inode:      $dotContentMap.fileAsset.inode
identifier: $dotContentMap.fileAsset.identifier
path:       $dotContentMap.fileAsset.path
mimeType:   $dotContentMap.fileAsset.mimeType
extension:  $dotContentMap.fileAsset.extension
fileSize:   $dotContentMap.fileAsset.fileSize
width:      $dotContentMap.fileAsset.width
height:     $dotContentMap.fileAsset.height
metaData:   $dotContentMap.fileAsset.metaData
   #set($meta = $json.generate($dotContentMap.fileAsset.metaData))
   #foreach($key in ${meta.keys()}) 
      $key : $meta.get($key)
   #end

Binary Field

Binary fields are returned as objects. You can not access the contents of the binary field directly, but you can use the identifier and other properties of the object to access the appropriate file using standard URLs.

Note that when using URLs to access binary field values, you must usually also know (and use) the Velocity variable name of the Content Type field in the URL. All of the following examples are built using a value of binary1 for the Velocity variable name.

Binary File

/contentAsset/raw-data/${dotContentMap.identifier}/binary1/${dotContentMap.binary1.file}

Binary Image

Binary fields containing images can be accessed and transformed using the /contentAsset and /dA URL formats. For more information, please see the Image Resizing and Processing documentation.

Resized Image

<img src="/contentAsset/image/$dotContentMap.identifier/binary1/filter/Resize/resize_w/500">

Thumbnail Image

<img src="/dA/$dotContentMap.identifier/binary1/filter/Thumbnail/thumbnail_w/200/thumbnail_h/200/thumbnail_bg/255255255/">

Binary Field Properties

The following examples show the properties available for Binary fields, depending on whether the file stored is a simple file asset or an image. These values may be accessed by referencing the Binary field as a property of the content object, and the specific field below as a property of the binary field (e.g. $dotContentMap.binary1.fileSize).

File Asset Properties

<p>Binary Field File Asset Properties:</p>
<ul>
    <li>File metaData: $dotContentMap.binary1.metaData</li>
        <ul>
           #set($meta = $json.generate($dotContentMap.binary1.metaData))
           #foreach($key in ${meta.keys()}) 
              <li>$key : $meta.get($key)</li>
           #end
        </ul>
    <li>File uri:        $dotContentMap.binary1.uri</li>
    <li>File path:       $dotContentMap.binary1.path</li>
    <li>File inode:      $dotContentMap.binary1.map.inode</li>
    <li>File identifier: $dotContentMap.binary1.map.identifier</li>
    <li>File size:       $dotContentMap.binary1.fileSize</li>
    <li>File mimeType:   $dotContentMap.binary1.mimeType</li>
    <li>File extension:  $dotContentMap.binary1.extension</li>
</ul>

Image Properties

Images stored in Binary fields have all of the properties of files (see above), and the following additonal properties specific to images:

<p>Binary Field Image-Specific Properties:</p>
<ul>
    <li>Image height:     $dotContentMap.binary1.height</li>
    <li>Image width:      $dotContentMap.binary1.width</li>
</ul>

Fields with Pre-Defined Values

Checkbox Field

<p>Checkbox Field Properties:</p>
<ul>
    <li>Options:         $dotContentMap.fieldVar.options</li>
    <li>Possible Values: $dotContentMap.fieldVar.value</li>
    <li>Selected Values:</li>
        <ul>
        #foreach($value in $dotContentMap.fieldVar.selectedValues) 
           $value#if($foreach.hasNext()), #end
        #end
        </ul>
</ul>

Multi Select Field

Options: 
#foreach($option in $dotContentMap.fieldVar.options) 
   $option#if($foreach.hasNext()), #end
#end
values: $dotContentMap.fieldVar.values
Selected Values: 
#foreach($value in $dotContentMap.fieldVar.selectedValues) 
   $value#if($foreach.hasNext()), #end
#end

Radio Field

Options: 
#foreach($option in $dotContentMap.fieldVar.options) 
   $option#if($foreach.hasNext()), #end
#end
Possible Values:  $dotContentMap.fieldVar.values
Selected Values:  $dotContentMap.fieldVar.selectValue

Select Field

Options: 
#foreach($option in $dotContentMap.fieldVar.options) 
   $option#if($foreach.hasNext()), #end
#end
Possible Values:  $dotContentMap.fieldVar.values
Selected Values:  $dotContentMap.fieldVar.selectValue

Taxonomy

• Category Field
• Tag Field
• Relationship Field

Category Field

A Category field returns a list of Category objects:

#foreach($category in $dotContentMap.catFieldVar)
   $category.categoryName, $category.key
#end

Tag Field

A Tag field returns a list of strings:

#foreach($tag in $dotContentMap.tagFieldVar) 
   $tag, 
#end

Relationship Field

The value returned from a Relationship field varies based on the Cardinality of the Relationship:

List of Content Objects (One to Many, Many to Many)

<p>Related Content:</p>
<ul>
    #foreach($object in $dotContentMap.relationshipFieldVar) 
       <li>$object.title</li>
    #end
</ul>

Single Content Object (One to One, Many to One)

When a single content object is returned, the field value of that content object may be referenced directly, without the need to first get the content object:

<p>Related Content: $dotContentMap.relationshipFieldVar.title</p>

Other

Constant Field

Constant field values are stored as text (similar to a Text field). You can retrieve the value of a Constant field as follows:

$dotContentMap.fieldVar

Custom Field

Custom field values are stored as a large block of text (similar to a Textarea field). You can retrieve the value of a Custom field (but not the code) as follows:

$dotContentMap.fieldVar

Key/Value Field

#if ($UtilMethods.isSet($dotContentMap.fieldVar))
   #foreach($key in $dotContentMap.fieldVar.entrySet())
      #if($key.key != "map" && $key.key != "keys")
         $key.key: $key.value
      #end
   #end
#end