diff --git a/cms-oss-changelog/src/changelog/entries/2025/07/8337.GPU-2036.documentation b/cms-oss-changelog/src/changelog/entries/2025/07/8337.GPU-2036.documentation new file mode 100644 index 0000000000..bdf1dc2762 --- /dev/null +++ b/cms-oss-changelog/src/changelog/entries/2025/07/8337.GPU-2036.documentation @@ -0,0 +1 @@ +Added documentation for properties available in Handlebars templates: "Handlebars Properties":https://www.gentics.com/Content.Node/cmp8/guides/handlebars_properties.html. \ No newline at end of file diff --git a/cms-oss-doc/src/main/source/handlebars_properties.textile b/cms-oss-doc/src/main/source/handlebars_properties.textile new file mode 100644 index 0000000000..de86740784 --- /dev/null +++ b/cms-oss-doc/src/main/source/handlebars_properties.textile @@ -0,0 +1,1313 @@ +h2. Resolving properties with Handlebars + +This document describes the properties of CMS objects resolvable in Handlebars templats. + +endprologue. + +h3. Page properties + +h4. cms.page.id + +Type: @String@ + +ID of the page. + + +{{cms.page.id}} + + +h4. cms.page.url + +Type: @String@ + +The URL of the page. + + +Link to page + + +h4. cms.page.template + +Type: "Template":handlebars_properties.html#template + +Template of the page. + + +{{cms.page.template.name}} + + +h4. cms.page.name + +Type: @String@ + +Name of the page. + + +

{{cms.page.name}}

+ + +h4. cms.page.filename + +Type: @String@ + +Filename of the page. + + +{{cms.page.filename}} + + +h4. cms.page.description + +Type: @String@ + +Description of the page. + + +

About this site

+

{{cms.page.description}}

+ + +h4. cms.page.priority + +Type: @Number@ + +Priority of the page. + + +{{#lt cms.page.priority 1}} + +{{/lt}} + + +h4. cms.page.tags + +Type: List of "Tag":handlebars_properties.html#tag + +Tags of the page. + + +{{#each cms.page.tags}} + {{{gtx_render this}}} +{{/each}} + + +h4. cms.page.publishtimestamp + +Type: @Number@ + +UNIX timestamp of the last publish action. + + +

Last updated: {{cms.page.publishtimestamp}}

+ + +h4. cms.page.publishdate + +Type: @Date@ + +Date of the last publish action. + + +

Last updated: {{cms.page.publishdate}}

+ + +h4. cms.page.creationtimestamp + +Type: @Number@ + +UNIX timestamp of page creation. + + +

Created: {{cms.page.creationtimestamp}}

+ + +h4. cms.page.creationdate + +Type: @Date@ + +Date of page creation. + + +

Created: {{cms.page.creationdate}}

+ + +h4. cms.page.edittimestamp + +Type: @Number@ + +UNIX timestamp of last page update. + + +

Last edited: {{cms.page.edittimestamp}}

+ + +h4. cms.page.editdate + +Type: @Date@ + +Date of last page update. + + +

Last edited: {{cms.page.editdate}}

+ + +h4. cms.page.folder + +Type: "Folder":handlebars_properties.html#folder + +Reference to page's folder. + + +{{cms.page.folder.name}} + + +h4. cms.page.creator + +Type: "User":handlebars_properties.html#user + +Reference to page's creator. + + +Created by: {{cms.page.creator.firstname}} {{cms.page.creator.lastname}} + + +h4. cms.page.editor + +Type: "User":handlebars_properties.html#user + +Reference to last editor of the page. + + +Last edited by: {{cms.page.editor.firstname}} {{cms.page.editor.lastname}} + + +h4. cms.page.publisher + +Type: "User":handlebars_properties.html#user + +Reference to the last publisher of the page. + + +Last published by: {{cms.page.publisher.firstname}} {{cms.page.publisher.lastname}} + + +h4. cms.page.language + +Type: "Language":handlebars_properties.html#language + +Reference to the language of the page. + + +Language: {{cms.page.language.name}} ({{cms.page.language.code}}) + + +h4. cms.page.languageset.id + +Type: @String@ + +ID of the page's languageset. A languageset is a collection that groups pages of the same contents but with different translations together. So an English version and a German version of a page have the same languageset.id. + + +{{cms.page.languageset.id}} + + +h4. cms.page.languageset.pages + +Type: List of "Page":handlebars_properties.html#page + +Reference to other language layouts of the page. + + +{{#each cms.page.languageset.pages}} + {{this.language.name}} +{{/each}} + + +h4. cms.page.online + +Type: @Boolean@ + +True if page is online, false otherwise. + + +{{#if cms.page.online}} + Page is published +{{else}} + Page is offline +{{/if}} + + +h4. cms.page.version + +Type: Object + +Current version information for the page. + + +Version: {{cms.page.version.number}} +Created: {{cms.page.version.date}} +Editor: {{cms.page.version.editor.firstname}} +Is major version: {{cms.page.version.major}} + + +h4. cms.page.object + +Type: Object + +Object properties of the page. + + +{{gtx_render cms.page.object.OBJECTPROPERTY}} + + +h4. cms.page.ismaster + +Type: @Boolean@ + +True if it's a master page, false if localized copy. + + +{{#if cms.page.ismaster}} + Master page +{{else}} + Channel page +{{/if}} + + +h4. cms.page.inherited + +Type: @Boolean@ + +True if inherited from master node, false if not. + + +{{#if cms.page.inherited}} + Inherited from master +{{else}} + Local page +{{/if}} + + +h3. Node properties + +h4. cms.node.id + +Type: @String@ + +The ID of the node. + + +{{cms.node.id}} + + +h4. cms.node.https + +Type: @Boolean@ + +A boolean indicating whether this node uses HTTPS. + + + +{{#if cms.node.https}} + Home +{{else}} + Home +{{/if}} + + +h4. cms.node.host + +Type: @String@ + +The hostname of the node. + + + Home + + +h4. cms.node.folder + +Type: "Folder":handlebars_properties.html#folder + +The nodes root folder. + + +

{{cms.node.folder.name}}

+ + +h4. cms.node.path + +Type: @String@ + +The path of the node (an alias for @pub_dir@). + + + Home + + +h4. cms.node.pub_dir + +Type: @String@ + +The node's publish directory for pages (an alias for @path@). + + + Home + + + +h4. cms.node.pub_dir_bin + +Type: @String@ + +The nodes publish directory for files and images. + + + + + +h4. cms.node.master + +Type: @Boolean@ + +A boolean indicating whether this node a master (when set to @true@) or a channel (when set to @false@). + + +{{#if cms.node.master}} + +{{else}} + +{{/if}} + + +h4. cms.node.languages + +Type: List of "language":handlebars_properties.html#languages + +The languages available for this node. + + + Available languages (code and language name): +
+ {{#each cms.node.languages}} +
{{this.id}}
+
{{this.name}}
+ {{/each}} +
+ + +h3. Tag properties + +The expression @{{cms.tag}}@ will be resolved to the currently rendered tag. To access a tags properties from a rendered page use @{{cms.page.tags.TAGNAME}}@ where TAGNAME is the tags keyword. + +h4. cms.tag.id + +Type: @String@ + +ID of the tag. + + +{{cms.tag.id}} + + +h4. cms.tag.name + +Type: @String@ + +Name of the tag. + + +{{cms.tag.name}} + + +h4. cms.tag.parts + +Type: List of "parts":handlebars_properties.html#parts + +List of the tag's parts. + + +{{#each cms.tag.parts}} + {{this.}} +{{/each}} + + +h4. cms.tag.parts.PARTNAME + +Type: Part + +References a single part of a tag. + + +{{cms.tag.parts.PARTNAME.text}} + + +h4. cms.tag.empty + +Type: @Number@ + +@1@ in case the tag does not render any output, @0@ otherwise. + + +{{#if cms.tag.empty}} + +{{/if}} + + +h4. cms.tag.visible + +Type: @Number@ + +@1@ if the tag is active, else @0@. + + +{{#if cms.tag.visible}} + +{{/if}} + + +h3. Template properties + +h4. cms.template.id + +Type: @String@ + +ID of the template. + + +{{cms.template.id}} + + +h4. cms.template.name + +Type: @String@ + +Name of the template. + + +{{cms.template.name}} + + +h4. cms.template.tags + +Type: List of "Tag":handlebars_properties.html#tag + +List of all available tags of the template. + + +{{#each cms.template.tags}} + {{{gtx_render this}}} +{{/each}} + + +h4. cms.template.ml + +Type: @String@ + +Markup language of the template. + + +{{cms.template.ml}} + + +h3. Folder properties + +h4. cms.folder.id + +Type: @String@ + +ID of the folder. + + +{{cms.folder.id}} + + +h4. cms.folder.name + +Type: @String@ + +Name of the folder. + + +{{cms.folder.name}} + + +h4. cms.folder.description + +Type: @String@ + +Description of the folder. + + +{{cms.folder.description}} + + +h4. cms.folder.node + +Type: "Node":handlebars_properties.html#node + +Reference to the folder's node. + + +Home + + +h4. cms.folder.parent + +Type: "Folder":handlebars_properties.html#folder + +Reference to parent folder or null on top level. + + +{{#if cms.folder.parent}} + Parent: {{cms.folder.parent.name}} +{{else}} + Root folder +{{/if}} + + +h4. cms.folder.path + +Type: @String@ + +Publish path of the folder. + + +{{cms.folder.path}} + + +h4. cms.folder.creator + +Type: "User":handlebars_properties.html#user + +The folder's creator. + + +Created by: {{cms.folder.creator.firstname}} {{cms.folder.creator.lastname}} + + +h4. cms.folder.editor + +Type: "User":handlebars_properties.html#user + +The last user who edited the folder. + + +Last edited by: {{cms.folder.editor.firstname}} {{cms.folder.editor.lastname}} + + +h4. cms.folder.folders + +Type: List of "Folder":handlebars_properties.html#folder + +List of all subfolders. + + +{{#each cms.folder.folders}} + {{this.name}} +{{/each}} + + +h4. cms.folder.pages + +Type: List of "Page":handlebars_properties.html#page + +List of pages in this folder. + + +{{#each cms.folder.pages}} + {{this.name}} +{{/each}} + + +h4. cms.folder.files + +Type: List of "File":handlebars_properties.html#file + +List of files in this folder. + + +{{#each cms.folder.files}} + {{this.name}} +{{/each}} + + +h4. cms.folder.images + +Type: List of "File":handlebars_properties.html#file + +List of images in this folder. + + +{{#each cms.folder.images}} + {{this.name}} +{{/each}} + + +h4. cms.folder.filesandimages + +Type: List of "File":handlebars_properties.html#file + +List of all files and images in this folder. + + +{{#each cms.folder.filesandimages}} + {{this.name}} +{{/each}} + + +h4. cms.folder.children + +Type: List + +List of all subfolders, images and files. + + +{{#each cms.folder.children}} + {{this.name}} +{{/each}} + + +h4. cms.folder.object + +Type: Object + +Object properties of the folder. + + +{{gtx_render cms.folder.object.OBJECTPROPERTY}} + + +h4. cms.folder.ismaster + +Type: @Boolean@ + +True if master folder, false if localized copy. + + +{{#if cms.folder.ismaster}} + Master folder +{{else}} + Channel folder +{{/if}} + + +h4. cms.folder.inherited + +Type: @Boolean@ + +True if inherited from master node, false if not. + + +{{#if cms.folder.inherited}} + Inherited from master +{{else}} + Local folder +{{/if}} + + +h3. File properties + +h4. cms.file.id + +Type: @String@ + +ID of the file. + + +{{cms.file.id}} + + +h4. cms.file.name + +Type: @String@ + +Filename. + + +{{cms.file.name}} + + +h4. cms.file.description + +Type: @String@ + +Description of the file. + + +{{cms.file.description}} + + +h4. cms.file.size + +Type: @Number@ + +Size in bytes. + + +{{cms.file.size}} + + +h4. cms.file.sizekb + +Type: @Number@ + +Size in kilobytes. + + +{{cms.file.sizekb}} + + +h4. cms.file.sizemb + +Type: @Number@ + +Size in megabytes. + + +{{cms.file.sizemb}} + + +h4. cms.file.folder + +Type: "Folder":handlebars_properties.html#folder + +Reference to the file's folder. + + +{{cms.file.folder.name}} + + +h4. cms.file.extension + +Type: @String@ + +File extension. + + +{{cms.file.extension}} + + +h4. cms.file.type + +Type: @String@ + +MIME-type of the file. + + +{{cms.file.type}} + + +h4. cms.file.url + +Type: @String@ + +Link to file. + + +Download + + +h4. cms.file.width + +Type: @Number@ + +Image width (only for images). + + +{{cms.file.width}} + + +h4. cms.file.height + +Type: @Number@ + +Image height (only for images). + + +{{cms.file.height}} + + +h4. cms.file.isfile + +Type: @Boolean@ + +True if it's a file, false if it's an image. + + +{{#if cms.file.isfile}} + Regular file +{{else}} + Image file +{{/if}} + + +h4. cms.file.isimage + +Type: @Boolean@ + +True if it's an image, false otherwise. + + +{{#if cms.file.isimage}} + Image file +{{else}} + Regular file +{{/if}} + + +h4. cms.file.object + +Type: Object + +Object properties of the file. + + +{{cms.file.object}} + + +h4. cms.file.ismaster + +Type: @Boolean@ + +True if master file, false if localized copy. + + +{{#if cms.file.ismaster}} + Master file +{{else}} + Channel file +{{/if}} + + +h3. Rendermode properties + +h4. cms.rendermode.publish + +Type: @Boolean@ + +True if page is rendered during publish process. + + +{{#if cms.rendermode.publish}} + Publishing +{{/if}} + + +h4. cms.rendermode.live + +Type: @Boolean@ + +True when using Live Preview. + + +{{#if cms.rendermode.live}} + Live Preview +{{/if}} + + +h4. cms.rendermode.edit + +Type: @Boolean@ + +True when using Edit Mode. + + +{{#if cms.rendermode.edit}} + Edit Mode +{{/if}} + + +h4. cms.rendermode.preview + +Type: @Boolean@ + +True when using Preview Mode. + + +{{#if cms.rendermode.preview}} + Preview Mode +{{/if}} + + +h4. cms.rendermode.real + +Type: @Boolean@ + +True when using Real Edit Mode. + + +{{#if cms.rendermode.real}} + Real Edit Mode +{{/if}} + + +h4. cms.rendermode.frontend + +Type: @Boolean@ + +True when rendering in frontend mode (valid in edit mode only). + + +{{#if cms.rendermode.frontend}} + Frontend Mode +{{/if}} + + +h4. cms.rendermode.backend + +Type: @Boolean@ + +True when rendering in backend mode (valid in edit mode only). + + +{{#if cms.rendermode.backend}} + Backend Mode +{{/if}} + + +h3. Parttype properties + +The following properties are available in the Handlebars template of a construct containing an overview tagpart. All examples assume that the keyword word the overview tagpart is "overview", so accessing the tagpart can be done via cms.tag.parts.overview in the Handlebars template. + +h4. cms.tag.parts.overview.items + +Type: Collection + +This collection contains all the items of the overview, sorted according to the settings for "orderBy" and "orderDirection". When iterating over the items with the each helper, the current item is available via the variable this, and its properties are accessible via the dot notation. For example the name of an item is accessible as this.name. + +Every Handlebars template for an overview tag will use this property, since it is the only possibility to the get items in the overview. + + + + + +h4. cms.tag.parts.overview.listType + +Type: @String@ + +The type of objects listed by this overview tagpart. The value of this property will always be one of the following: + +* @FILE@ +* @FOLDER@ +* @IMAGE@ +* @PAGE@ +* @UNDEFINED@ + +Where "UNDEFINED" is a fallback value, that will not appear normally since the editor UI does not allow leaving the "Displayed Elements" property (which defined the listed object's types) empty. + +If an overview construct allows different object types to be selected, the "listType" property allows to generate different markup of different object types in the Handlebars template. If an overview construct only allows one object type, this property is normally not used at all in the Handlebars template. + + + + + +h4. cms.tag.parts.overview.selectType + +Type: @String@ + +The select type chosen by the editor for this tag. The value of this property will always be one of the following: + +* @AUTO@: The chosen select type was "Automatically from current folder" meaning that the items in the overview are taken from the same folder as the page with the tag itself. +* @FOLDER@: The chosen select type was "Folder" meaning that the items are taken from a list of folders. +* @MANUAL@: The chosen select type was "Individually" meaning that the editor selected the items for the overview manually. +* @UNDEFINED@: No select type was chosen. This is a safety fallback, since the editor UI does not allow leaving the "Select Type" field empty. + +This information is typically not important when rendering an overview and is only included for completeness sake. It is possible that rendering the selectType is helpful information for debugging, so adding a comment in the markup with the selectType might help find problems with the overview. + + + + + + +h4. cms.tag.parts.overview.orderBy + +Type: @String@ + +The property by which the items of the overview are sorted. The value of this property will always be one of the following: + +* @ALPHABETICALLY@: The items will be ordered by their name. +* @CDATE@: The items will be ordered by their creation date. +* @EDATE@: The items will be ordered by their edit date. +* @SELF@: The items will be in the same order as they were added by the editor. +* @UNDEFINED@: No sorting will be performed. This is a safety fallback since the editor UI does not allow leaving the "Order by" field empty. +This information is typically not important when rendering an overview and is only included for completeness sake. It is possible that rendering the orderBy is helpful information for debugging, so adding a comment in the markup with the orderBy might help find problems with the overview. + + + + + + +h4. cms.tag.parts.overview.orderDirection + +Type: @String@ + +The property by which the items of the overview are sorted. The value of this property will always be one of the following: + +* @ASC@: The items will be sorted in ascending order. +* @DESC@: The items will be sorted in descending order. +* @UNDEFINED@: No sort direction was defined. This is a safety fallback since the editor UI does not allow leaving the "Order" field empty. +This information is typically not important when rendering an overview and is only included for completeness sake. It is possible that rendering the orderDirection is helpful information for debugging, so adding a comment in the markup with the orderDirection might help find problems with the overview. + + + + + + +h4. cms.tag.parts.overview.maxItems + +Type: @Number@ + +The maximum number of items the editor set in the tag. The overview will list not more than this number of items. When the property is not set, all items will be listed. + +This information is typically not important when rendering an overview and is only included for completeness sake. It is possible that rendering the maxItems is helpful information for debugging, so adding a comment in the markup with the maxItems might help find problems with the overview. + + + + + + +h4. cms.tag.parts.overview.recursive + +Type: @Boolean@ + +This property indicates whether the overview also recursively lists elements of the correct type in subfolders which are in the scope of the overview. + +This information is typically not important when rendering an overview and is only included for completeness sake. It is possible that rendering the recursive is helpful information for debugging, so adding a comment in the markup with the recursive might help find problems with the overview. + + + + + + +h3. Select (Single)/Select (Multiple) Properties + +The following properties are available for Select (Single) and Select (Multiple) parts. + +All examples assume that the keyword word the select tagpart is "select", so accessing the tagpart can be done via cms.tag.parts.select in the Handlebars template. + +h4. cms.tag.parts.select.items + +Type: @Collection@ + +Collection of all entries in the database. + + +{{#each cms.tag.parts.select.items}} + {{this.key}} - {{this.value}} +{{/each}} + + +h4. cms.tag.parts.select.selection + +Type: @Collection@ + +Collection of all _selected_ entries in the database. + + +{{#each cms.tag.parts.select.selection}} + {{this.key}} - {{this.value}} +{{/each}} + + +h4. cms.tag.parts.select.nr + +Type: @String@ + +The ID of the entry. + + +{{cms.tag.parts.select.nr}} + + +h4. cms.tag.parts.select.keys + +Type: Collection + +The selections key set. + + +{{#each cms.tag.parts.multiselect.keys}} + {{this}} +{{/each}} + + +h4. cms.tag.parts.PARTNAME.values + +Type: Collection + +The selections value set. + + +{{#each cms.tag.parts.multiselect.values}} + {{this}} +{{/each}} + + +h3. URL Properties + +The following properties are available for PageUrl, FileUrl, ImageUrl, and FolderUrl parts. All examples assume that the keyword for the part type is "url". + +h4. cms.tag.parts.url.id + +Type: @String@ + +ID of the URL part. + + +{{cms.tag.parts.url.id}} + + +h4. cms.tag.parts.url.internal + +Type: @Boolean@ + +True if an internal link, false otherwise. Only available for PageUrl parts. + + +{{#if cms.tag.parts.url.internal}} + +{{else}} + +{{/if}} + + +h4. cms.tag.parts.url.target + +Type: Object + +Reference to the target object, either a "page":handlebars_properties.html#page, "file":handlebars_proprties.html#file (this type is also used for images) or "folder":handlebars_properties.html#folder. + + +{{gtx_render cms.tag.parts.url.target}} + + +h4. cms.tag.parts.url.size + +Type: @String@ + +Gets the formatted size (in KB or MB) of the target file. Only available for Fileurl or Imageurl parts. + + +{{cms.tag.parts.url.size}} + + +h4. cms.tag.parts.url.url + +Type: @String@ + +URL of the target. Only available for internal links. + + +Link + + +h4. cms.tag.parts.url.node + +Type: "Node":handlebars_properties.html#node + +The node of the target. Only available for internal links (may be empty). + + +{{#if cms.tag.parts.url.node}} + Node: {{cms.tag.parts.url.node.name}} +{{/if}} + + +h4. cms.tag.parts.url.nodeId + +Type: @String@ + +The target's node ID. May be 0 but never empty. + + +Node ID: {{cms.tag.parts.url.nodeId}} + + +h3. Checkbox Properties + +The checkbox part type only has one property called "checked". The example assumes that the keyword for the part is "checkbox". + +h4. cms.tag.parts.checkbox.checked + +Type: @Boolean@ + +Indicates whether the checkbox is checked. + + +{{#if cms.tag.parts.checkbox.checked}} + Checkbox is checked +{{else}} + Checkbox is not checked +{{/if}} + + +h3. Text Properties + +The text part type has only one property called "text". The example assumes that the keyword for the part is "text". + +h4. cms.tag.parts.text.text + +Type: @String@ + +The text value of the part. + + +Raw value: {{cms.tag.parts.text.text}} + + +h3. Node Properties + +In addition to the properties exposed by "nodes":#node in general the parttype can resolve the +name of the node directly. The example assumes that the keyword for the part is "node". + +h4. cms.tag.parts.node.name + +Type: @String@ + +The nodes name. + + +{{cms.tag.parts.node.name}} +