Tag reference sheet

Tag library reference for the following tag libraries:

CMS Utility Tag Library - version 4.3.8

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

Name Description Type
name* The name of the attribute. String
value The 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

Name Description Type
level level from where to start the template search. int
nodeDataName node containing the link information. String
postHref href part that is added after the nodeData content. String
preHref href part that is added before the nodeData content. String
templateName template 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

Name Description Type
activeCss Css class added to the current page link. String
delimiter displayed between the page names, e.g. ">" String
excludeCurrent Exclude the current (active) page from the breadcrumb. Defaults to false. If true, the current (active) page is not included in breadcrumb. boolean
hideProperty Name for a page property which, if set, will make the page hidden in the breadcrumb. String
link Create links to pages. Defaults to true. boolean
nolinkCurrent Add current page but without links. Defaults to false (also current page is linked) boolean
startLevel At which level to start. Often you will want to omit top levels, e.g. if you split your site into multiple languages. String
titleProperty Name 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

Name Description Type
altNodeDataName Name 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
class html pass through attribute. String
contentNode The content object to use. String
contentNodeCollectionName Name of the collection holding the content node, e.g. "mainColumnParagraphs". String
contentNodeName Inside 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
height html pass through attribute. String
id html pass through attribute. String
inherit Inherit the value from parent pages, if not set in the current one. boolean
nodeDataName* the name of the nodeData containing the image path. String
path The absolute path to the content. You must define the repository attribute if the content is not stored in the website repository. String
repository Used if the uuid or path attribute is set. Defaults to "website". String
style html pass through attribute. String
uuid The uuid to use for finding the content. You must define the repository attribute if the content is not stored in the website repository. String
width html pass through attribute. String
actpage If true we work on the current active page instead of any other node. @deprecated boolean

<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

Name Description Type
para If 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

Name Description Type
pattern Sets 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

Name Description Type
var Name 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

Name Description Type
allowOversize Allow resizing images beyond their original dimensions? boolean
imageContentNodeName* The name of the new contentNode that will contain the scaled version of the image. String
maxHeight The maximum height of the image in pixels. int
maxWidth The maximum width of the image in pixels. int
parentContentNodeName The 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

Name Description Type
chars Number of characters to include in search snippets. Default is 100. int
maxSnippets Maximum 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

Name Description Type
classProperty Name for a page property that will hold a css class name which will be added to the html class attribute. String
contentFilter A variable in the pageContext that contains a content filter, determining if a given page should be drawn or not. String
endLevel The end level for navigation, defaults to 0. int
expandAll Sitemap mode. Can be assigned the "show" value. Only showable pages will be displayed. Any other value will result in displaying all pages. String
hideInNav Name 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
markFirstAndLastElement If 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
nofollow Name 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
openMenu Name 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
relativeLevels If set to true, the startLevel and endLevel values are treated relatively to the current active page. The default value is false. boolean
startLevel The start level for navigation, defaults to 0. int
style The css class to be applied to the first ul. Default is empty. String
wrapperElement When 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

Name Description Type
itemType The 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
repository The repository we search in. Default is website repository. String
scope Scope for the variable. Can be "page" (default), "request", "session", "application". String
startLevel The start level for search, defaults to 0. Can be used to limit the search only to the current website tree. int
startPath The path we search in. String
useSimpleJcrQuery Set 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
supportSubstringSearch Search 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

Name Description Type
delims delimiters 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

Name Description Type
cellpadding Standard html attribute. String
cellspacing Standard html attribute. String
class Standard html attribute. String
header Use first row as column headers. boolean
id Standard html attribute. String
style Standard 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

Name Description Type
divCSS The 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
parentContentNodeName The name of the parent of the new contentNode. String
text* The text to be converted. String
textBackColor The color of the background in hexadecimal format, e.g. 'ff0044'. Default is 'ffffff' (white). String
textFontColor The color of the text in hexadecimal format, e.g. 'ff0044'. Default is '000000' (black). String
textFontFace The font face of the text, e.g. 'Helvetica'. Default is 'Helvetica'. String
textFontSize The size of the text, in points, e.g. 12. Default is '12'. int
textSplit The 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

Name Description Type
actpage If "true", atom is taken from the currently active page. @deprecated boolean
atomName @deprecated String
language Locale string (see java.util.Locale). @deprecated String
nodeDataName Where the date comes from. @deprecated String
pattern Date pattern. Defaults to "yyyy.MM.dd - HH:mm:ss". See the java.text.SimpleDateFormat javadoc for details. @deprecated String

<cmsu:fileSrc>

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

Can contain:empty

Attributes

Name Description Type
contentNodeName If left empty, local contentNode is used as set by contentNodeIterator, otherwise the global contentNode is used. @deprecated String
fileNameOnly If "true", the file name without the path will be generated. @deprecated String
nodeDataName* @deprecated String

<cmsu:simpleMail>

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

Can contain:empty

Attributes

Name Description Type
bcc Mail "bcc" field. String
cc Mail "cc" field. String
from* Mail "from" field. String
logging Log all the information sent by the mail. boolean
loggingDirectory Where to log to. For each page the log is created separately on a weekly basis. String
loggingEncoding Encoding of the log file. Default is UTF8. For windows excel use ISO-8859-1. String
loggingExtension The file extension to use for new files. Default is log. Use csv for easy opening with Excel. String
loggingFilename Name for the file (without extension). If not set, the pages path is used to create a file. String
nodeCollectionName Collection (paragraphs) that holds the configured form fields. If not set the current collection is used. String
redirect Page to redirect to after a successfull submission. String
replyTo Mail "replyTo" field. String
subject* Mail "subject" field. String
template Instead 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
type Mail type. Used to get the mail from the factory. String