How do I access Dynamic / Custom Metadata Fields in Velocity?

With the XPath Tool

If you're using an Index Block and the XPath Tool, you can target the name of your Custom Metadata Field in your XPath Syntax. Example:

#set ($category = $_XPathTool.selectSingleNode($contentRoot, "//calling-page/system-page/dynamic-metadata[name='category']/value"))

#if (!$_PropertyTool.isNull($category))
    $category.value
#end

or for multiple values:

#set ($categories = $_XPathTool.selectNodes($contentRoot, "//calling-page/system-page/dynamic-metadata[name='categories']/value"))

#if (!$_PropertyTool.isNull($categories) && $categories.size() > 0)
  #foreach($category in $categories)
    $category.value
  #end
#end

With our API

If you're using our API, you can use .getDynamicField() to set your variables. Example:

#set ($category = $currentPage.metadata.getDynamicField('category'))

#if (!$_PropertyTool.isNull($category))
    $category.value
#end

or for multiple values:

#set ($categories = $currentPage.metadata.getDynamicField('categories'))

#if (!$_PropertyTool.isNull($categories) && $categories.values.size() > 0)
    #foreach($category in $categories.values)
        $category
    #end
#end

It's also possible to access both the possible field items and selected field items of a multi-value field in order to access both their label and value properties. Referencing the label property is useful when you need to change the representation of a field item without affecting selected values in existing content:

#set ($possibleCategories = $currentPage.metadata.getDynamicField('categories').getPossibleFieldItems())
#set ($selectedCategories = $currentPage.metadata.getDynamicField('categories').getSelectedFieldItems())

Possible categories:
#if (!$_PropertyTool.isNull($possibleCategories))
    #foreach($category in $possibleCategories)
        $category.label - $category.value
    #end
#end

Selected categories:
#if (!$_PropertyTool.isNull($selectedCategories))
    #foreach($category in $selectedCategories)
        $category.label - $category.value
    #end
#end