CMS Utility Tag Library Version: 4.4.6 Last Published: Jan 17, 2012

Tag reference sheet

Tag library reference for the following tag libraries:

CMS Utility Tag Library - version 4.4.6

CMS Utility Tag Library

Namespace definition: xmlns:cmsu="cms-util-taglib"

Tags

  • aAttribute Tag which can be nested in a AHref tag in order to add parameters
  • aHref Utility tag which can be used to print out a link based on the value of a node data or tries to find the first page with a specific template name, starting from a specific page
  • breadcrumb Outputs "breadcrumbs" with links to parents of the current page
  • img Writes an html img tag for the image at "nodeDataName"
  • newlines Converts text in the body of the tag adding tags at new lines or wrapping lines in paragraphs
  • poweredBy A simple tag which can display the version and edition of the running Magnolia instance
  • redirect Redirects to the first child page
  • scaleImage Creates a scaled copy of an image
  • searchResultSnippet Output a set of snippets taken from any paragraph in the given page mathing any of the search term
  • simpleNavigation Draws a simple, css based, navigation menu
  • simpleSearch A simple tag which allows searching in all the site content with a "natural language" query
  • strToObj converts a string to an object using split
  • table Draws an html table
  • txt2img Tag that converts text into PNG images, and outputs a div element containing a set of img elements
  • xmp Simulates the xmp tag, escaping content
  • date Emits a date
  • fileSrc Returns informations as path, name or size of a file
  • simpleMail Sends a simple mail generated with all the fields found in nodeCollectionName

Required attributes are marked with a*

<cmsu:aAttribute>

Tag which can be nested in a AHref tag in order to add parameters.

Can contain:empty

Attributes

NameDescriptionType
name*The name of the attribute.String
valueThe value of the attribute.String

<cmsu:aHref>

Utility tag which can be used to print out a link based on the value of a node data or tries to find the first page with a specific template name, starting from a specific page.

Can contain:JSP

Example

<cmsu:aHref ... />

Attributes

NameDescriptionType
levellevel from where to start the template search.int
nodeDataNamenode containing the link information.String
postHrefhref part that is added after the nodeData content.String
preHrefhref part that is added before the nodeData content.String
templateNametemplate name to search for.String
atomName@deprecated use the nodeDataName attribute instead.String

<cmsu:breadcrumb>

Outputs "breadcrumbs" with links to parents of the current page.

Can contain:empty

Attributes

NameDescriptionType
activeCssCss class added to the current page link.String
delimiterdisplayed between the page names, e.g. ">"String
excludeCurrentExclude the current (active) page from the breadcrumb. Defaults to false. If true, the current (active) page is not included in breadcrumb.boolean
hidePropertyName for a page property which, if set, will make the page hidden in the breadcrumb.String
linkCreate links to pages. Defaults to true.boolean
nolinkCurrentAdd current page but without links. Defaults to false (also current page is linked)boolean
startLevelAt which level to start. Often you will want to omit top levels, e.g. if you split your site into multiple languages.String
titlePropertyName for a page property which holds the title to display in breadcrumbs. If empty, the standard title is used.String

<cmsu:img>

Writes an html img tag for the image at "nodeDataName". Also supports writing object tags for flash movies. (detected by the "swf" extension)

Can contain:empty

Attributes

NameDescriptionType
altNodeDataNameName of the node data holding the alt text for the image. If not set the default is nodeDataName + "Alt". The same value is added to the "title" attribute, if not null.String
classhtml pass through attribute.String
contentNodeThe content object to use.String
contentNodeCollectionNameName of the collection holding the content node, e.g. "mainColumnParagraphs".String
contentNodeNameInside a "contentNodeIterator": if not set, the current content node is taken. If set empty (contentNodeName=""), the top level content is taken. If specified, the named content node is taken. Outside a "contentNodeIterator": if not set or empty: the top level content is taken. If specified, the named content node is taken.String
heighthtml pass through attribute.String
idhtml pass through attribute.String
inheritInherit the value from parent pages, if not set in the current one.boolean
nodeDataName*the name of the nodeData containing the image path.String
pathThe absolute path to the content. You must define the repository attribute if the content is not stored in the website repository.String
repositoryUsed if the uuid or path attribute is set. Defaults to "website".String
stylehtml pass through attribute.String
uuidThe uuid to use for finding the content. You must define the repository attribute if the content is not stored in the website repository.String
widthhtml pass through attribute.String
actpageIf true we work on the current active page instead of any other node. @deprecatedboolean

<cmsu:newlines>

Converts text in the body of the tag adding <br /> tags at new lines or wrapping lines in paragraphs.

Can contain:JSP

Attributes

NameDescriptionType
paraIf true each line will be wrapped in a <p> tag. Default to false (use br's).boolean

<cmsu:poweredBy>

A simple tag which can display the version and edition of the running Magnolia instance.

Can contain:empty

Attributes

NameDescriptionType
patternSets a different message pattern than the default. This uses the java.text.MessageFormat syntax. Available parameters are: {0} Magnolia edition {1} Magnolia version {2} Magnolia build number or date {3} Magnolia product url {4} Magnolia provider name {5} Magnolia provider address {6} Magnolia provider email <strong>Warning: since this is using java.text.MessageFormat, you need to escape single quotes, for example: "I''m showing my Magnolia love by using the {0} version {1}."</strong>String

<cmsu:redirect>

Redirects to the first child page. If the server is an authoring instance or magnolia and the preview mode is not active the tag will simply add to the pagecontext a variable named from the <code>var</code> attribute containing the path of the child page. <p> A typical requirement is to have pages with no content which will simply redirect to a child page: using this tag you can easily build a "redirect" template and use it for empty pages: </p> <pre> Title Template Mod. Date -----------------------^----------------^-------^----------------------^--------------- - siteroot - o redirect 05-01-01 - it - o redirect 05-01-01 + home Home page o home 05-01-01 </pre> <p> This tag should be put <strong>before</strong> any other tag or include in the page, since response should not be committed yet for it to work. </p> <p> Example: </p> <pre> &lt;cmsu:redirect var="destpage" /> This page has no content and it will redirect to &lt;a href="${pageContext.request.contextPath}${destpage}">${destpage}&lt;/a> in a public instance. </pre>

Can contain:empty

Example

<cmsu:redirect var="destpage" /> This page has no content and it will redirect to <a href="${pageContext.request.contextPath}${destpage}">${destpage}</a> in a public instance.

Attributes

NameDescriptionType
varName for the variable which will contain the URL of the page this tag will redirect to.String

<cmsu:scaleImage>

Creates a scaled copy of an image. The maximum width and height of the images can be specified via the attributes. <br /> <br /> If the scaled image with the specified name does not exist in the repository, then this tag will create it and save it. If the scaled image already exists, then it will not be recreated. <br /> <br /> The name of the node that contains the original image is set by the attribute 'parentContentNode', and the name of the nodeData for the image is set by the attribute 'parentNodeDataName'. If 'parentContentNode' is null, the local content node is used. <br /> <br /> The name of the content node that contains the new scaled image is set by the attribute 'imageContentNodeName'. This node is created under the original image node. This ensures that, if the original images is deleted, so are all the scaled versions. <br /> <br /> This tag writes out the handle of the content node that contains the image. <br /> <br />

Can contain:empty

Attributes

NameDescriptionType
allowOversizeAllow resizing images beyond their original dimensions?boolean
imageContentNodeName*The name of the new contentNode that will contain the scaled version of the image.String
maxHeightThe maximum height of the image in pixels.int
maxWidthThe maximum width of the image in pixels.int
parentContentNodeNameThe name of the content node that contains the image to be copied and scaled.String
parentNodeDataName*The name of the data node that contains the image data to be copied and scaled.String

<cmsu:searchResultSnippet>

Output a set of snippets taken from any paragraph in the given page mathing any of the search term.

Can contain:empty

Example

<pre> &lt;cmsu:simplesearch query="${param.search}" var="results" /&gt; &lt;c:forEach items="${results}" var="page"&gt; &lt;cmsu:searchResultSnippet query="${param.search}" page="${page}" /&gt; &lt;/c:forEach&gt; </pre>

Attributes

NameDescriptionType
charsNumber of characters to include in search snippets. Default is 100.int
maxSnippetsMaximum number of snippets to print out.int
page*A Content node of type mgnl:content (a magnolia page), typically returned by the simpleSearch tag.info.magnolia.cms.core.Content
query*Search query.String

<cmsu:simpleNavigation>

Draws a simple, css based, navigation menu. The menu layout can then be customized using css, and the default menu should be enough for most uses. Two following page properties will also be used in the menu: <ul> <li><code>navTitle</code>: a title to use for the navigation menu, if different from the real page title</li> <li><code>accessKey</code>: an optional access key which will be added to the link</li> <li><code>wrappingElement</code>: an optional html element (div, span, p, etc) to go within the &lt;a&gt; tag wrapping the anchor text </ul>

Can contain:empty

Example

<pre> &lt;cmsu:simpleNavigation startLevel="3" style="mystyle"/&gt; Will output the following: &lt;ul class="level3 mystyle"&gt; &lt;li&gt;&lt;a href="..."&gt;page 1 name &lt;/a&gt;&lt;/li&gt; &lt;li&gt;&lt;a href="..."&gt;page 2 name &lt;/a&gt;&lt;/li&gt; &lt;li class="trail"&gt;&lt;a href="..."&gt;page 3 name &lt;/a&gt; &lt;ul class="level3"&gt; &lt;li&gt;&lt;a href="..."&gt;subpage 1 name &lt;/a&gt;&lt;/li&gt; &lt;li&gt;&lt;a href="..."&gt;subpage 2 name &lt;/a&gt;&lt;/li&gt; &lt;li&gt;&lt;strong&gt;&lt;a href="..."&gt;selected page name &lt;/a&gt;&lt;/strong&gt;&lt;/li&gt; &lt;/ul&gt; &lt;/li&gt; &lt;li&gt;&lt;a href="..."&gt;page 4 name &lt;/a&gt;&lt;/li&gt; &lt;/ul&gt; </pre>

Attributes

NameDescriptionType
classPropertyName for a page property that will hold a css class name which will be added to the html class attribute.String
contentFilterA variable in the pageContext that contains a content filter, determining if a given page should be drawn or not.String
endLevelThe end level for navigation, defaults to 0.int
expandAllSitemap mode. Can be assigned the "show" value. Only showable pages will be displayed. Any other value will result in displaying all pages.String
hideInNavName for the "hide in nav" nodeData. If a page contains a boolean property with this name and it is set to true, the page is not shown in navigation. Defaults to "hideInNav".String
markFirstAndLastElementIf set to true, a "first" or "last" css class will be added to the list of css classes of the first and the last li in each ul.boolean
nofollowName for the "nofollow" nodeData. If a page contains a boolean property with this name and it is set to true, rel="nofollow" will be added to the generated link (for links the should be ignored by search engines).String
openMenuName for the "open menu" nodeData. If a page contains a boolean property with this name and it is set to true, subpages are always shown also if the page is not selected. Defaults to "openMenu".String
relativeLevelsIf set to true, the startLevel and endLevel values are treated relatively to the current active page. The default value is false.boolean
startLevelThe start level for navigation, defaults to 0.int
styleThe css class to be applied to the first ul. Default is empty.String
wrapperElementWhen specified, all links will have the anchortext wrapped in the supplied element. (such as "span")String

<cmsu:simpleSearch>

A simple tag which allows searching in all the site content with a "natural language" query. It simply strips all the reserved chars from input string, build an xpath query and feed Magnolia QueryManager. By defaults search terms are ANDed, but it also supports using the AND or OR keywords in the query string. Search is not case sensitive and it's performed on any non-binary property. A collection on Content (page) objects is added to the specified scope with the specified name.

Can contain:empty

Example

<pre> &lt;cmsu:simplesearch query="${param.search}" var="results" /&gt; &lt;c:forEach items="${results}" var="page"&gt; &lt;a href="${pageContext.request.contextPath}${page.handle}.html"&gt;${page.title}&lt;/a&gt; &lt;/c:forEach&gt; </pre>

Attributes

NameDescriptionType
itemTypeThe itemTypes search/returned by this tag. Default is mgnl:content which is used for pages.String
query*Query to execute (e.g. "magnolia AND cms OR info")String
repositoryThe repository we search in. Default is website repository.String
scopeScope for the variable. Can be "page" (default), "request", "session", "application".String
startLevelThe start level for search, defaults to 0. Can be used to limit the search only to the current website tree.int
startPathThe path we search in.String
useSimpleJcrQuerySet this attribute to false to generate the search query as it was generated until Magnolia 3.5.4 (which will force a search on non-indexed word, which usually leads in less good results). As from 3.5.5, this is true by default, and generates simpler and better queries. See "6.6.5.2 jcr:contains Function" from the JCR Spec (pages 110-111) for details.boolean
var*The search results (a collection of Content nodes (pages)) will be added to the pagecontext using this name.String
supportSubstringSearchSearch for substrings too. This can decrease performance. Default value is false. @deprecated not used when useSimpleJcrQuery is set to true.boolean

<cmsu:strToObj>

converts a string to an object using split.

Can contain:JSP

Attributes

NameDescriptionType
delimsdelimiters characters; default: <code>"\n"</Code>.String
var*name of the pageContext variable where the obj is put to.String

<cmsu:table>

Draws an html table.

Can contain:JSP

Attributes

NameDescriptionType
cellpaddingStandard html attribute.String
cellspacingStandard html attribute.String
classStandard html attribute.String
headerUse first row as column headers.boolean
idStandard html attribute.String
styleStandard html attribute.String

<cmsu:txt2img>

Tag that converts text into PNG images, and outputs a div element containing a set of img elements. The font face, text color, text size and background color can be set via the tag attributes. <br /> <br /> The images are saved under the node specified by the attribute parentContentNodeName. Under this parent node, a new node is created, with the name specified by the attribute imageContentNodeName. Under this node, each image will have it own node. The names of the image node are based on the text that they contain. (Special characters such as &, /, chinese characters, etc. are replaces by codes to ensure that these names are legal.) <br /> <br /> If the images for the specified text do not exist in the repository under the specified parent node, then the this tag will create the images and save them. If the images for the text already exist, then they will not be recreated. <br /> <br /> The text to be converted into images can be split in three ways. If the attribute textSplit is null or is set to TEXT_SPLIT_NONE, then a single image will be created of the text on one line. If textSplit is set to TEXT_SPLIT_WORDS, then the text is plit into words (i.e. wherever there is a space). Finally, if textSplit is set to TEXT_SPLIT_CHARACTERS, then a seperate image is created for each letter. <br /> <br /> The tag outputs a div that contains one or more img's. The CSS class applied to the div is specified by the divCSS attribute. The CSS applied to the images depends on how the text was split. For text that was not split, the CSS applied is set to CSS_TEXT_IMAGE, for words it is CSS_WORD_IMAGE, and for characters it is CSS_CHARACTER_IMAGE. Any spacing that is required between images will need to be set in your css stylesheet. <br /> <br /> The textFontFace attribute may either be a font name of a font installed on the server, or it may be a path to a TTF file. The class to generate PNG images from TrueType font strings is originally by Philip McCarthy - http://chimpen.com (http://chimpen.com/things/archives/001139.php). I have made a couple of small changes. <br /> <br />

Can contain:empty

Attributes

NameDescriptionType
divCSSThe CSS class that will be applied to the div that contains these text images. Defaults to "text-box".String
imageContentNodeName*The name of the new contentNode to create, under which all image nodes will be saved.String
parentContentNodeNameThe name of the parent of the new contentNode.String
text*The text to be converted.String
textBackColorThe color of the background in hexadecimal format, e.g. 'ff0044'. Default is 'ffffff' (white).String
textFontColorThe color of the text in hexadecimal format, e.g. 'ff0044'. Default is '000000' (black).String
textFontFaceThe font face of the text, e.g. 'Helvetica'. Default is 'Helvetica'.String
textFontSizeThe size of the text, in points, e.g. 12. Default is '12'.int
textSplitThe method used to split the text into sub-strings: 'none', 'words', or 'characters'. Default is 'none'.String

<cmsu:xmp>

Simulates the xmp tag, escaping content. This is useful for displaying code examples.

Can contain:JSP

This tag has no attributes.

<cmsu:date>

Emits a date. @deprecated see cms:out.

Can contain:empty

Attributes

NameDescriptionType
actpageIf "true", atom is taken from the currently active page. @deprecatedboolean
atomName@deprecatedString
languageLocale string (see java.util.Locale). @deprecatedString
nodeDataNameWhere the date comes from. @deprecatedString
patternDate pattern. Defaults to "yyyy.MM.dd - HH:mm:ss". See the java.text.SimpleDateFormat javadoc for details. @deprecatedString

<cmsu:fileSrc>

Returns informations as path, name or size of a file. @deprecated see cms:out.

Can contain:empty

Attributes

NameDescriptionType
contentNodeNameIf left empty, local contentNode is used as set by contentNodeIterator, otherwise the global contentNode is used. @deprecatedString
fileNameOnlyIf "true", the file name without the path will be generated. @deprecatedString
nodeDataName*@deprecatedString

<cmsu:simpleMail>

Sends a simple mail generated with all the fields found in nodeCollectionName. @deprecated since 4.0

Can contain:empty

Attributes

NameDescriptionType
bccMail "bcc" field.String
ccMail "cc" field.String
from*Mail "from" field.String
loggingLog all the information sent by the mail.boolean
loggingDirectoryWhere to log to. For each page the log is created separately on a weekly basis.String
loggingEncodingEncoding of the log file. Default is UTF8. For windows excel use ISO-8859-1.String
loggingExtensionThe file extension to use for new files. Default is log. Use csv for easy opening with Excel.String
loggingFilenameName for the file (without extension). If not set, the pages path is used to create a file.String
nodeCollectionNameCollection (paragraphs) that holds the configured form fields. If not set the current collection is used.String
redirectPage to redirect to after a successfull submission.String
replyToMail "replyTo" field.String
subject*Mail "subject" field.String
templateInstead of the mail type you can define a template to use. This template must be registered in the mail module.String
to*Mail "to" field.String
typeMail type. Used to get the mail from the factory.String