Using Macros

Macros available in the dotCMS system

Build RSS Feed
Build RSS From Content
Comment: Add a generic Comment component
Content Rating
Content Ticker
Crumbtrails
Date Formatting
Display File, Page, or Contentlet Trackback History
Displaying Resized Images
Displaying Thumbnail Images
Encrypt and Decrypt
Events Listings
Executing a SQL Query
Gets the details page link for a given contentlet
File Repository
Loads a Piece of Content
Google Mini Search
List Files on the File System
Mailing List
MP3 Player Button
MP3 Player Extended
MP3 Player (Streaming)
Navigation Menu Builder
Paginated Pull and Display of Contents
Permanent Link: Add Permanent Link to a File, Page or Contentlet
Permanent Link Trackback: Add RDF Trackback to a File, Page or Contentlet
Photo Carousel
Photo Gallery
Print the Average Rating of a Content
Print the Number of Votes on a Content
Pull RSS
Pulling and Displaying Contents
Pulling and Displaying Related Content (Relationships)
Random Image
Retrieve Selected Inode
Send To Friend
Site Map: Add Sitemap to a Page from the Root of the Site
Site Map: Add a Site Map to a Page from a Specified Folder to a Specific Depth
Social Bookmarks
Text Area
Tag Cloud
Title Generator
Video Gallery
Video Player

Build RSS This macro generates a RSS xml from a map list. Then name of the keys in the map have to be: 'title' (String - required), 'link' (Identifier - required), 'description' (String - required), 'guid' (Identifier -required), 'pubdate' (Date - optional) and 'author' (String - optional). This macro uses the permalink macro to generate the items link in the RSS.

Macro Syntax:

#buildRSS(channelTitle channelLink channelDescription list)

Arguments:

channelTitle
This is the value for the title tag of the channel.
channelLink
This is the value for the link tag of the channel.
channelDescription
This is the value for the description tag of the channel.
list
This is the map list of contents to display in the RSS.

Optional Parameters:

channelLanguage (velocity variable not a parameter)
This is the value for the language tag of the channel.
channelCopyright (velocity variable not a parameter)
This is the value for the copyright tag of the channel.
channelPubDate (velocity variable not a parameter)
This is the value for the publication date tag of the channel.
channelLastBuildDate (velocity variable not a parameter)
This is the value for the last build date tag of the channel.
channelDocs (velocity variable not a parameter)
This is the value for the docs tag of the channel.
channelGenerator (velocity variable not a parameter)
This is the value for the generator tag of the channel.
channelManagingEditor (velocity variable not a parameter)
This is the value for the managing editor tag of the channel.
channelWebMaster (velocity variable not a parameter)
This is the value for the Web Master tag of the channel.
channelWebMaster (velocity variable not a parameter)
This is the value for the Web Master tag of the channel.
permalinkDetailPage (velocity variable not a parameter)
This is the identifier of the page that we need to display the contents in the item link. It uses the permalink macro.

Usage:

The macro will display all the content obtained by the pullcontent macro in the RSS

Example: This show a simple way to call the macro with the required fields

#set($contentList = $!{contents.getEmptyList()})

	#pullContent($query '0' 'modDate desc')

	#foreach($content in $list)

		#set($item = $!{contents.getEmptyMap()})

		#set($_dummy = $item.put('guid', $!content.identifier))

		#set($_dummy = $item.put('title', $content.title))

		#set($_dummy = $item.put('description', $content.description))

		#set($_dummy = $item.put('link', $!content.identifier))

		#set($_dummy = $item.put('pubdate', $!content.contentLastModDate))


		#set($_dummy = $!contentList.add($item))

	#end



#buildRSS('Channel Title','http://hostname/test/test.dot','Channel description', $contentList)

Example2: This example shows how to include one o more of the optional parameters

#set($permalinkDetailPage='123')

#set($contentList = $!{contents.getEmptyList()})

	#pullContent($query '0' 'modDate desc')

	#foreach($content in $list)

		#set($item = $!{contents.getEmptyMap()})

		#set($_dummy = $item.put('guid', $!content.identifier))

		#set($_dummy = $item.put('title', $content.titleField))

		#set($_dummy = $item.put('description', $content.description))

		#set($_dummy = $item.put('link', $!content.identifier))

		#set($_dummy = $item.put('pubdate', $!content.contentLastModDate))


		#set($_dummy = $!contentList.add($item))

	#end



#buildRSS('Channel Title','http://hostname/test/test.dot','Channel description', $contentList)

Build RSS From Content This macro generates an RSS xml from a content lucene query.

Macro Syntax:

#buildRSSFromContent(channelTitle channelLink channelDescription query titleField descriptionField)

Arguments:

channelTitle
This is the value for the title tag of the channel.
channelLink
This is the value for the link tag of the channel.
channelDescription
This is the value for the description tag of the channel.
query
This is the lucene query to be use to get the contents to display in the RSS.
titleField
This is the content velocity name of the the field you want to display as title in the item tag.
descriptionField
This is the content velocity name of the the field you want to display as description in the item tag.

Optional Parameters:

channelLanguage (velocity variable not a parameter)
This is the value for the language tag of the channel.
channelCopyright (velocity variable not a parameter)
This is the value for the copyright tag of the channel.
channelPubDate (velocity variable not a parameter)
This is the value for the publication date tag of the channel.
channelLastBuildDate (velocity variable not a parameter)
This is the value for the last build date tag of the channel.
channelDocs (velocity variable not a parameter)
This is the value for the docs tag of the channel.
channelGenerator (velocity variable not a parameter)
This is the value for the generator tag of the channel.
channelManagingEditor (velocity variable not a parameter)
This is the value for the managing editor tag of the channel.
channelWebMaster (velocity variable not a parameter)
This is the value for the Web Master tag of the channel.
channelWebMaster (velocity variable not a parameter)
This is the value for the Web Master tag of the channel.
permalinkDetailPage (velocity variable not a parameter)
This is the identifier of the page that we need to display the contents in the item link. It uses the permalink macro.
orderBy (velocity variable not a parameter)
This is the order by field use in the pullcontent macro. Default value 'modDate desc' It use the pullcontent macro.
limit (velocity variable not a parameter)
This is the max number of element to get. Default value '0' show all. It use the pullcontent macro.

Usage:

The macro will display all the content obtained by the pullcontent macro in the RSS

Example: This show a simple way to call the macro with the required fields

#buildRSSFromContent('Channel Title','http://hostname/test/test.dot','Channel description','+type:content +deleted:false +structureInode:77290 +(+languageId:1* +live:true))','test1','test6')

Example2: This example shows how to include one o more of the optional parameters.

#set($permalinkDetailPage='123')
 #buildRSSFromContent('Test Title','http://hostname/test/test.dot','Channel description','+type:content +deleted:false +structureInode:77290 +(+languageId:1* +live:true))','test1','test6')

comment: Add a Generic comment Component to a Page This macro will allow you to add a generic component to any contentlet in the system. If you set the commentsModeration you could create workflow task over this component.

Macro Syntax:

   comment($contentlet.inode)

Arguments:

contentlet inode
This is the inode of the contentlet that will be commented.

Optional Parameters:

commentForceLogin (velocity variable not a parameter)
Optional: If set to "true" the user should be logged before could submit a comment
Default: false
commentAutoPublish (velocity variable not a parameter)
Optional: Controls whether the comment is automatically published or not.
Default: true
commentUseCaptcha (velocity variable not a parameter)
Optional: If set to "true" shows a captcha image to the comment's form, to validate human interaction
Default: false
commentUseAudioCaptcha (velocity variable not a parameter)
Optional: If set to "true" shows a audio captcha to the comment's form, to validate human interaction
Default: false
commentUseAudioCaptchaHeight (velocity variable not a parameter)
Optional: If 'commentUseAudioCaptcha' var is set to "true", this will be the height of the space that the audio player will be used
Default: 30
commentStripHTML (velocity variable not a parameter)
Optional: If set to "true" any html code that's sent in the comment field would be removed
Default: false
commentTitle (velocity variable not a parameter)
Optional: If set, that will be the name of the question to comment
commentsModeration (velocity variable not a parameter)
Optional: If set, that will be the name of the role to assign the workflow
maxDepth (velocity variable not a parameter)
Optional: If set, that will be the number of levels you could make a comment. Comments will be displayed in a threaded view - Comments in reply to other comments.
Default: 1

Usage:
Use this macro if you want to add a form to comment a contentlet, the macro, will add a form to add new comments and list the comments order by publish date.

Example 1: #set($commentForceLogin = 'false')
#set($commentAutoPublish = 'true')
#set($commentUseCaptcha = 'true')
#set($commentUseAudioCaptcha = 'true')
#set($commentUseAudioCaptchaHeight = 200)
#set($commentStripHTML = 'false')
#set($commentTitle = 'This is the question to comment')
#comment($content.inode)

Example 2: 
This example generate a content comment and a workflow task
from that comment
#set($commentForceLogin = 'false')

#set($commentAutoPublish = 'true')

#set($commentUseCaptcha = 'false')

#set($commentStripHTML = 'false')
#set($commentsModeration = 'Editor')
#set($commentForceLogin= 'true')
#comment($content.inode)

Return diferent messages depending the input date. The input date must be before the current date.

View Tool Syntax:

$dateviewapi.friendly(date)

Arguments:

date (date/required)
Date to diff with the current date.

Usage:

Use this to show the difference date and time between a string date (before the current date) and the current date.

Example 1:


Wed, 02 Apr 2008 16:23:14 +0000<br>
#set ($tempDate = $UtilMethods.parseDate("Wed, 02 Apr 2008 16:23:14 +0000", "EEE, dd MMM yyyy HH:mm:ss +SSSS"))
Result Message: $dateviewapi.friendly($tempDate)<br>

Assuming that current date is: Fri, 02 May 2008 17:20:00 - The output will be: Wed., April 2, 4:23 PM

Example 2:


Sat, 26 Apr 2008 16:23:14 +0000<br>
#set ($tempDate = $UtilMethods.parseDate("Sat, 26 Apr 2008 16:23:14 +0000", "EEE, dd MMM yyyy HH:mm:ss +SSSS"))
Result Message: $dateviewapi.friendly($tempDate)<br>

Assuming that current date is: Fri, 02 May 2008 17:20:00 - The output will be: Saturday at 4:23 PM

Example 3:


Thu, 01 May 2008 16:23:14 +0000<br>
#set ($tempDate = $UtilMethods.parseDate("Thu, 01 May 2008 16:23:14 +0000", "EEE, dd MMM yyyy HH:mm:ss +SSSS"))
Result Message: $dateviewapi.friendly($tempDate)<br>

Assuming that current date is: Fri, 02 May 2008 17:20:00 - The output will be: Yesterday at 4:23 PM

Example 4:


Fri, 02 May 2008 14:20:00 +0000<br>
#set ($tempDate = $UtilMethods.parseDate("Fri, 02 May 2008 14:20:00 +0000", "EEE, dd MMM yyyy HH:mm:ss +SSSS"))
Result Message: $dateviewapi.friendly($tempDate)<br>

Assuming that current date is: Fri, 02 Apr 2008 17:20:00 - The output will be: 3 hour(s) ago

Example 5:


Fri, 02 May 2008 17:10:00 +0000<br>
#set ($tempDate = $UtilMethods.parseDate("Fri, 02 May 2008 17:10:00 +0000", "EEE, dd MMM yyyy HH:mm:ss +SSSS"))
Result Message: $dateviewapi.friendly($tempDate)<br>

Assuming that current date is: Fri, 02 May 2008 17:20:00 - The output will be: 10 minute(s) ago

detailPageLink : Gets the details page link for a given contentlet. The link title can also be specified, otherwise the macro will attemtp to find a contentlet field with the name 'title' and use this as the default link title. If the 'Detail Page' structure field has not been set, the link will be composed of the current page url plus the parameter. Note that the name of the request parameter used for passing the selected inode to the details page, is determined by the properties key "INODE_PARAMETER_NAME". In case this key is missing, the parameter name defaults to "inode"

Macro Syntax:

detailPageLink($content)

Arguments:

content
This is the content to get the detail page for

Optional Parameters:

$linkTitle = 'My Title' (default Title of passed in Content) Use to override the title. The title is used to display the link

Usage:
Use this macro to get the detail page for a piece of content

Example 1: #set($linkTitle = 'My Title') #detailPageLink($content)

Content Rating The getRating macro, it's used to display a five start scale, that's the user's evaluation on the article. Also the macro allows the user evaluate this contentlet.

Macro Syntax:

#getRating(content_identifier)

Arguments:

content_inode
This is the identifier of the contentlet to be evaluated by the rating macro

Usage:

This macro will automatically show a five start menu indicating the acceptances for the contentlet.

Example:

#getRating($content.identifier)

Content Ticker

This macro takes a list of content items, and displays them each based on the titleField and titleDescription. It rotates each piece of content and fades them out of the page to show the next one. Optional parameters can determine the fade length and colors as well as the time between each ticker display.

Macro Syntax:

#ticker()

Arguments:

titleField
This is the field from the structure that will be displayed on the ticker for each content piece

Optional Parameters:

descriptionField
This is the field from the structure that will be displayed on the ticker for each content piece below the title.
fadeInLength
This determines the length in milliseconds it takes to fade the text in
fadeOutLength
This determines the length in milliseconds it takes to fade the text out
displayLength
This determines the length in milliseconds from one fade in to the next
fgcolor
This determines the color to display the text before it fades in.
bgcolor
This determines the color that the text fades in to.

Usage:
Use this macro if you want to add a content ticker to your site. You need to call the pullContent macro before calling the ticker macro, to provide the ticker with the list of content to display.

Example:

#pullContent('+type:content +deleted:false +structureInode:5 +(+languageId:1* +live:true)' '10' '')
#set($titleField = 'NewsHeadline')
#ticker($titleField)

Example with Optional Parameters:

#pullContent('+type:content +deleted:false +structureInode:5 +(+languageId:1* +live:true)' '10' '')
#set($titleField = 'NewsHeadline')
#set($descriptionField = 'NewsSummary')

#set ($fadeInLenth = 500)
#set ($fadeOutLenth = 500)
#set ($displayLength = 2000)
#set ($fgcolor = "#1A50B8")
#set ($bgcolor = "#ffffff")

#ticker($titleField)

Crumbtrail Builder This macro will build a crumbtrail using the path to the current page using unordered lists. This list can then be formated by css. The resulting code will look like.

<ul>
	<li><a href="/">Home</a></li>
	<li><a href="/folder_name/">Folder Name</a></li>
	<li>Page Name</li>  <-- No Link for current page
</ul>

Macro Syntax:

#crumbTrail()

Arguments: Optional Parameters:

homePath
The homepath can be set to point the home which is the beginning of the crumbtrail to a specified path.

Usage:
The crumbtrail builder will create an unordered list of links, starting from the site root or "Home Page". It will then use the folder names for folders, build the path to the current page, and then display the page title as the last link. The resulting html can be easily formatted by wrapping it in a <div> tag and assigning it appropiate css styles.

Example:

<div id="crumbtrail">
   #navigation(1,1)
</div>

Display File, Page or Contentlet Trackback History This macro display a list of all the trackback pings made to the permalink showing the title,url, trackback date,blog name, and asset Identifier

Macro Syntax:

#pullTrackbacks(identifier)

Arguments:

identifier
This is the identifier or inode of the file, page or contentlet, you want to display the trackback pings history.

Usage:

Example:

#pullTrackbacks('12345')

#if($list.size() >0)

#foreach($track in $list)

	Asset Identifier:$!{track.assetIdentifier}

	Title:$!{track.title}

	Excerpt:$!{track.excerpt}

	URL:$!{track.url}

	Blog Name:$!{track.blogName}

	Trackback Date:$!{track.trackDate}

#end

#else

	No Trackbacks found


#end

Displaying Resized Images This macro will automatically create and display a resized image in your image html tag, with the height and width you specify in the servlet parameters. The servlet allows you to create new images with the size you prefer, specifying the width, height or both. If you want to display an image, but you don't know the exact values of the width and height to display the image proportionally, this servlet allows you specify the maximum height and maximun width the image could have, and generate a proportional image that doesn't exceed those values.

Macro Syntax:

   <img src="/resize_image?[[path] or [inode]]
   &[ [[height] and/or [width]] or [[maxh] and [maxw]] ]">

Arguments:

path
This is the root folder of the image (optional). You could use the image path or the image inode parameter to specify the image to be resized. It is mandatory that only one of the two be used.
inode
This is the image inode (optional). You could use the image path or the image inode parameter to specify the image to be resized. It is mandatory that only one of the two be used.
h
This is the new image height (optional). You could use the image height parameter alone or in combination with the width ("w") parameter.
w
This is the new image width (optional). You could use the image width parameter alone or in combination with the height ("h") parameter.
maxh
This is the image new maximum height could have (optional). If you use this parameter it must include the maximum width ("maxw") parameter.
maxw
This is the image new maximum width could have (optional). If you use this parameter it must include the maximum height ("maxh") parameter.

Usage:
The use of this servlet is very easy. You only have to add in the src attribute of the html image tag, the following text < img src="/resize_image?<parameters> " >

Example:

   <img src="/resize_image?path=/images/image.jpg&maxw=120&maxh=130">
   <img src="/resize_image?inode=91&maxw=120&maxh=130">
   <img src="/resize_image?path=/images/image.jpg&w=80&h=80">
   <img src="/resize_image?inode=91&w=80&h=80">
   <img src="/resize_image?path=/images/image.jpg&w=80">
   <img src="/resize_image?inode=91&w=80">
   <img src="/resize_image?path=/images/image.jpg&h=80">
   <img src="/resize_image?inode=91&h=80">

Displaying Thumbnail Images This macro will automatically create and display a thumbnail image in your image html tag, with the height and width you specify in the servlet parameters. The servlet allows you to create new images with the size you prefer, specifying the width, height or both.The thumbnail generates an image with a background color and places the resized image within the thumbnail. The background color can be changed with the parameters r,g,b.

Macro Syntax:

   <img src="/thumbnail?inode=[inode]&[ [[height] and/or [width]] or [[r] and [g] and [b]] ]">

Arguments:

inode
This is the image inode parameter to specify the image to be resized. It is mandatory that only one of the two be used.
h
This is the new image height (optional). You could use the image height parameter alone or in combination with the width ("w") parameter.
w
This is the new image width (optional). You could use the image width parameter alone or in combination with the height ("h") parameter.
r
This is the R from the RGB background color to use for the image. By default the RGB is White (255,255,255).
g
This is the G from the RGB background color to use for the image. By default the RGB is White (255,255,255).
g
This is the B from the RGB background color to use for the image. By default the RGB is White (255,255,255).

Usage:
The use of this servlet is very easy. You only have to add in the src attribute of the html image tag, the following text < img src="/thumbnail?<parameters> " >

Example:

   <img src="/thumbnail?inode=91&w=120&h=130">
   <img src="/thumbnail?inode=91&w=120">
   <img src="/thumbnail?inode=91&h=130">
   <img src="/thumbnail?inode=91&w=120&h=130&r=200&g=100&b=50">

Decrypt This macro allows to decrypt a string that was encrypted with #encrypt. The decrypted value is saved in the variable: $decryptedStr. If you want to echo out the decrypted value use: $crypt.decrypt('string to decrypt').

Macro Syntax:

#decrypt('string to decrypt')

Arguments:

string to decrypt
This is the string that will be decrypted.

Usage:

Example:

#encrypt('website@dotcms.org')
#decrypt($encryptedStr)
This is the decrypted value = $decryptedStr

Encrypt This macro allows to encrypt a string. The encryted emails can be used in email forms to avoid having email address in plain text. The encrypted value is saved in the variable: $encryptedStr. If you want to echo out the decrypted value use: $crypt.crypt('string to encrypt').

Macro Syntax:

#encrypt('string to encrypt')

Arguments:

string to encrypt
This is the string that will be encrypted.

Usage:

Example:

#encrypt('website@dotcms.org')
#set ($to = $encryptedStr)

Events Listings

Macro Syntax:

#events('from' 'to')

Arguments:

from
This is the from date, or start date, of your events listing. It must be in (mm/dd/yy) format.
to
This is the "to date", or end date, of your events listing. It must be in (mm/dd/yy) format.

Usage:

Example:

#events('1/1/2006' '2/1/2006')

Execute SQL Query This macro will allow you to execute a select statement on any predefined datasource.

Macro Syntax:

   #getSQLResults('select * from table')

Arguments:

dbConnection
Optional: By default the macro will execute your query against the dotCMS database unless you set a dbConnection.
dbStartRow
Optional: If you set dbStartRow your results will start at the given row.< The dbStartRow is zero based meaning that the first row is row 0./li>

dbMaxRow
Optional: If you set dbMaxRow your results will be limited to your maxRows. When possible your should do this with a limit in your query./li>

Usage:
Use this macro if you want to pull data from a database and display the results within some piece of content. If the SQL throws an error it will store the error in a variable named SQLError. See the example below for instructions on how to use this. It is only optional that you check for the error but it is recommended that you do so that your sql won't fail silently.

Example:

#set ($dbConnection = 'jdbc/test1')
#set ($dbStartRow = 1)
#set ($dbMaxRow = 4)
#getSQLResults('select * from test order by id')
$SQLError
#foreach($r in $results)
$r.id


#end

Example 2 - Here you see the the error being checked for and a custom message being throw on error:

#set ($dbConnection = 'jdbc/test1')
#set ($dbStartRow = 1)
#set ($dbMaxRow = 4)
#getSQLResults('select * from test order by id')
#if($SQLError)
Custom SQL message - I Failed
#else
#foreach($r in $results)
$r.id


#end
#end

File Repository This macro will automatically create a file repository using the path sent to it as the "root" folder.

Macro Syntax:

   #fileRepository('path')

Arguments:

path
This is root folder of the file repository. The end user will only be able to view files and folders under this directory.
fileRepositorySourceCode
This can be used as the display logic instead of the default html({velocityHome}/static/file_repository/index.html)

Usage:
The repository will show a list of files and folders that the view user has permissions to view. If the user is not logged in, they will only be able to view files and folders that have the CMS_ANONYMOUS read permission. If the user is logged in, they will be able to view any files and folders they have read permission on.

Example:

   #fileRepository('/resources/documentation')

This would build a file repository from the contents found in the CMS folder /resources/documentation. If there were any sub folders, the user would be able to click through and view these as well.

 #set($fileRepositorySourceCode = '/application/file_repository.vtl')
#fileRepository('/documentation/repository') 

And the /application/file_repository.vtl file could look like this
#foreach($file in $fileRepository_filesList)
#set($imgpath = "/resize_image?path=/dotAsset/${file.identifier}.${file.getExtension()}&w=178")

<img src='$imgpath' alt=""/>
#end 



Another example of code for /application/file_repository.vtl could be like this:
<ul>
#foreach($file in $fileRepository_filesList)
<li>
Filename: ${fileRepository_showFolder$file.fileName}

Extension: ${file.getExtension()}

Friendly Name:$!{file.friendlyName}

File Size:$!{file.size}

Publish Date: $!{file.publishDate}
</li>
#end
</ul>

Loads a Piece of Content From its Identifier This macro will take an identifier of a piece of content and sets it to a variable $content

Macro Syntax:

   
		#getContent(contentIdentifier)

Example:

   
		#set($id = $request.getParameter("id"))

		#if($id)

			#getContent($id)

		#end

		My title is $content.title

Let you retrieve result from a google mini appliance.

View Tool Syntax:

$googleapi.searchGoogleMini(client, collection, subcollection, query, metaquery, start, num, autoFilter)

Arguments:

client (string/required)
This is the frontend client name, as its setup in the google mini appliance.
collection (string/required)
Name of the google collection to search on.
subcollection (string/non required)
Name of the google sub collection to search on. This property is not supported by all the google mini appliances.
query (string/non required)
The user query to narrow the results.
metaquery (string/non required)
Restricts the search results to documents with meta tags whose values contain the words or phrases specified.
This parameter requires the following sintax: [metatag name]:[metatag content]
Using | as the or operator and . as the AND operator
E.G.1. "department:Human Resources|department:Finance"
Meaning all the results where metatag deparment contains the phrase "Human Resources" or contains the word "Finance"
E.G.2. "department:Human Resources.department:Finance"
Meaning all the results where metatag deparment contains the phrase "Human Resources" and contains the word "Finance"
start (number)
Index where to start the search. Starting on 0.
num (number)
Number of results to retrieve, -1 to retrieve all results.
autoFilter (boolean true/false)
Activates or deactivates automatic results filtering performed by Google search.
Currently, Google search uses two techniques for automatic filtering of results:
Duplicate Snippet Filter - If multiple documents contain the same information in their snippets in response to a query, then only the most relevant document of that set will be displayed in the results.
Duplicate Directory Filter - If there are many results in a single web directory, then only the two most relevant results for that directory will be returned in the results. An output flag indicates that more results are available from that directory.

Usage:

Use this to pull search results from a google mini appliance, to make this web api work you have to setup the variable GOOGLE_MINI_SEARCH_URL on the dotmarketing.config.properties file pointing to the google mini appliance url like GOOGLE_MINI_SEARCH_URL=http://googlemini.dotcms.org

The api returns an specific GoogleMiniSearch object that contains all the variables necessary to display all the retrieved results.

GoogleMiniSearch Object - Attributes

	searchTime - The time taken by the appliance to retrieve the results

	query - The request query

	fromIndex - The start index of results

	toIndex - The end index of retrieved results

	estimatedTotal - The estimated total of result based on the given query

	searchResults - The list of results, this is a list of GoogleMiniSearchResult objects

	hasNextPage() - Method that returns true if results has a next page to display

	hasPreviousPage() - Method that returns true if results has a previous page to display

GoogleMiniSearchResult - Attributes

	identationLevel - Level of indentation used for inner results

	mimeType - Mime type of the result

	resultURL - The url to the result

	title - The title

	generalRatingRelevance - Relevance of the document in google mini

	additionalSearchDetails - More details about the retrived document 

	snippet - Result snippet 

	metaTagsFields - A map of metatags associated to the result

Example:


#set($searchObj = $googleapi.searchGoogleMini("default_frontend", "Main_Site", "", "Knight", "", 0, 100, false))
<b>Search Summary</b><br/>
<b>Total Search time:</b> $searchObj.searchTime<br/>
<b>Query:</b> $searchObj.query<br/>
<b>From Index:</b> $searchObj.fromIndex<br/>
<b>To Index:</b> $searchObj.toIndex<br/>
<b>Estimated Total:</b> $searchObj.estimatedTotal<br/>
<b>Has Next Results Page:</b> $searchObj.hasNextPage()<br/>
<b>Has Previous Results Page:</b> $searchObj.hasPreviousPage()<br/>
<b>Estimated Total of Results:</b> $searchObj.estimatedTotal<br/>
<br/>

#foreach($result in $searchObj.searchResults)
	<b>Result Index:</b> $result.resultIndex<br/>
	<b>Identation Level:</b> $result.identationLevel<br/>
	<b>Title:</b> $result.title<br/>
	<b>Snippet:</b> $result.snippet<br/>
	<b>Result URL:</b> <a href="$result.resultURL">$result.resultURL</a><br/>
	<b>General Rating Relevance:</b> $result.generalRatingRelevance<br/>
	<b>Mime Type:</b> $result.mimeType<br/>
	<b>Additional Search Details:</b> $result.additionalSearchDetails<br/>
	<b>Meta Tags Fields:</b> $result.metaTagsFields<br/>
	<hr/>
#end

List of Files from Underlying File System This macro will return a list of files that are available in a folder on the underlying file system.

Macro Syntax:

   #getFilesFromFS('path')

Arguments:

path
This is the folder of the directory under the WEB-ROOT. The end user will only be able to view files under this directory.

Usage:
The repository will show a list of files in a folder on the underlying file system. WARNING: THIS MACRO BYPASSES THE CMS PERMISSIONS COMPLETELY.

Example:

#getFilesFromFS('/css')
#foreach($file in $files)
   title: $!file.name 

   size : $!file.size 

   prettySize : $!file.prettySize 

   date : $!file.date

   prettyDate : $!file.prettyDate 

   link: $!file.link 

#end

This would build a list of file information found in the file system folder $WEB-ROOT/css.

Mailing List Generated on a Web Form that Displays the Public Mailing Lists This macro generates a checkbox list for all public mailing lists, in order to manage the user's email subscriptions to these mailing lists. This macro can be used either the user is logged in or using encrypted user id when the user is not logged in.

Macro Syntax:

#mailingList()

Usage:

The macro will display all public mailing lists name

Example: Let's assume we have a page with this macro, let's call it mailinglists_subscription.dot, if the user is logged in, this page can be accessed directly and its content will have the following macro call

      #mailingLists()

Example2: The user is not logged in, but we can access the prior page passing through the respective encrypted userId using the respective request parameter

      mailinglists_subscription.dot?ui=UUZVXTMAEvP6ABUja7Rkhg==

MP3 Player This macro will embed a streaming, flash based mp3 player using mp3s files you have uploaded into dotCMS. dotCMS will parse the xml file info and automatically display the song information in the player.

Macro Syntax:

#mp3Player('path')

Arguments:

path
This is the cms path to the uploaded mp3 files or the xml file with the play list. The path will look something like: /your/mp3s/file.mp3

Usage:

This macro will automatically display the following mp3 player

Example:

#mp3Player('/path/to/mp3s/file.mp3')

#mp3Player('/path/to/mp3s/playlist.xml')

The file /path/to/playlist.xml needs to generate the following format:


<?xml version="1.0" encoding="UTF-8"?>
<playlist version="1" xmlns="http://xspf.org/ns/0/">
<trackList>
<track>
<location>http://$!{host.getHostname}/mp3s/file1.mp3</location>
<creator>File Creator 1</creator>
<title>File Title #1</title>
<genre>Other</genre>
<image>http://$!{host.getHostname}/mp3s/file1.jpg</image>
</track>

<track>
<location>http://$!{host.getHostname}/mp3s/file2.mp3</location>
<creator>File Creator 2</creator>
<title>File Title #2</title>
<genre>Other</genre>
<image>http://$!{host.getHostname}/mp3s/file2.jpg</image>
</track>

<track>
<location>http://$!{host.getHostname}/mp3s/file3.mp3</location>
<creator>File Creator 3</creator>
<title>File Title #3</title>
<genre>Other</genre>
<image>http://$!{host.getHostname}/mp3s/file3.jpg</image>
</track>

</trackList>
</playlist>

MP3 Player Button This macro will embed a streaming, flash based mp3 player button using mp3s files you have uploaded into dotCMS.

Macro Syntax:

#mp3PlayerButton('song_url')

Arguments:

song_url
This is the cms path to the folder which holds your uploaded file with the mp3 filename and extension. The path will look something like: /your/mp3s/filename.mp3
This can specify an xml file with a predefined playlist. In this case the path will look something like: /path/to/playlist.xml

Usage:

This macro will automatically display the following mp3 player

Example:

#mp3PlayerButton('/path/to/mp3s/example.mp3')

#mp3PlayerButton('/path/to/playlist.xml')

The file /path/to/playlist.xml needs to generate the following format:


<?xml version="1.0" encoding="UTF-8"?>
<playlist version="1" xmlns="http://xspf.org/ns/0/">
<trackList>
<track>
<location>http://$!{host.getHostname}/mp3s/file1.mp3</location>
<creator>File Creator 1</creator>
<title>File Title #1</title>
<genre>Other</genre>
<image>http://$!{host.getHostname}/mp3s/file1.jpg</image>
</track>

<track>
<location>http://$!{host.getHostname}/mp3s/file2.mp3</location>
<creator>File Creator 2</creator>
<title>File Title #2</title>
<genre>Other</genre>
<image>http://$!{host.getHostname}/mp3s/file2.jpg</image>
</track>

<track>
<location>http://$!{host.getHostname}/mp3s/file3.mp3</location>
<creator>File Creator 3</creator>
<title>File Title #3</title>
<genre>Other</genre>
<image>http://$!{host.getHostname}/mp3s/file3.jpg</image>
</track>

</trackList>
</playlist>

MP3 Player Extended This macro will embed a streaming, flash based mp3 player button using mp3s files you have uploaded into dotCMS.

Macro Syntax:

#mp3PlayerExtended('song_url')

Arguments:

song_url
This is the cms path to the folder which holds your uploaded file with the mp3 filename and extension. The path will look something like: /your/mp3s/filename.mp3
This can specify a xml file with a predefined playlist. In this case the path will look something like: /path/to/playlist.xml

Usage:

This macro will automatically display the following mp3 extended player

Example:

#mp3PlayerExtended('/path/to/mp3s/example.mp3')

#mp3PlayerButton('/path/to/playlist.xml')

The file /path/to/playlist.xml needs to generate the following format:


<?xml version="1.0" encoding="UTF-8"?>
<playlist version="1" xmlns="http://xspf.org/ns/0/">
<trackList>
<track>
<location>http://$!{host.getHostname}/mp3s/file1.mp3</location>
<creator>File Creator 1</creator>
<title>File Title #1</title>
<genre>Other</genre>
<image>http://$!{host.getHostname}/mp3s/file1.jpg</image>
</track>

<track>
<location>http://$!{host.getHostname}/mp3s/file2.mp3</location>
<creator>File Creator 2</creator>
<title>File Title #2</title>
<genre>Other</genre>
<image>http://$!{host.getHostname}/mp3s/file2.jpg</image>
</track>

<track>
<location>http://$!{host.getHostname}/mp3s/file3.mp3</location>
<creator>File Creator 3</creator>
<title>File Title #3</title>
<genre>Other</genre>
<image>http://$!{host.getHostname}/mp3s/file3.jpg</image>
</track>

</trackList>
</playlist>

Navigation/Menu Builder This macro will build a navigational menu using unordered lists sutiable for standard top or left-hand navigation. These lists can then be formated by css. The resulting code will look like (where the 2nd <li> is the active link).

<ul>
	<li><a href="/path/to/pageOrFolder">Menu item 1</a></li>
	<li class="active"><a href="/path/to/pageOrFolder">Menu item 2</a></li>
	<li><a href="/path/to/pageOrFolder">Menu item 3</a></li>
</ul>

Macro Syntax:

#navigation('startLevel' 'levelsToShow')

Arguments:

startLevel
This is navigational level to start the menu on.
levelsToShow
This is how deep you would like the generated menu to be.

Optional:

menuSpans
If the $menuSpans variable is set to true before the macro is called, then <span> tags will be added around each menu link, like:
<li><span><a href="/path/to/pageOrFolder">Menu item 1</a></span></li>

openAllLevels
If this variable is set all menu items will be displayed on the navigation with no regard to where the user is on the site. This is very useful for top navigation drop downs that need to show all links.

Syntax:

#navigation('startLevel' 'levelsToShow')

Example 1:

<div id="topNav">
   #navigation(1,1)
</div>

This would build a top level menu one level deep.

Example 2:

<div id="leftNav">
   #navigation(2,2)
</div>

This would build a navigation bar 2 levels deep, which would open as the user clicked into a subsection.

Example 2:

<div id="leftNav">
#set($menuSpans = true)
#navigation(2,2)
</div>

This would build a navigation bar 2 levels deep, which would open as the user clicked into a subsection. It will also add span tags around all links.

Example 2:

<div id="leftNav">
#set($openAllLevels=true)
#navigation(2,2)
</div>

This would build a navigation bar 2 levels deep, which would open as the user clicked into a subsection.

Paging Contents Any list of contents in the content database can be pulled and displayed in a paginated fashion on the front end of your website by using the #pageContent() macro

Macro Syntax:

#pageContent('query' 'sort by' '# per page' '# current page')

Arguments:

query
A lucene query that is copied from the "Content Manager" search screen. To see this query, search the content and click the "Show Query". Select the query and hit ctrl+c to copy to your clipboard. Return to the content where you want to pull the list and paste it (ctrl+v) into the macro.
sort by
The name of the field you would like to sort the results by. This is the "DB Column" name found on the struture.
# per page
Maximum number of contentlets to display per page
# current page
Number of the page currently displayed

Usage:

This macro returns a list of content(s) on a variable named $list of contentlets $content. The contentlet's properties can be displayed by referencing their variable names. So $content.firstName would display the variable named firstName for the listed contents. The variable name can be found in the structure detail for the content type being used.
If you need to add a link to a content detail page you will need to use the content's inode by adding this variable: $content.inode.
Also, there are a group of variables set by this macro that help you know things like $totalResults that contains the total number of contents, $totalPages for the total number of pages, $firstPageRecord for the first record number of the current page, $lastPageRecord for the last record number of the current page, $hasNextPage true if has a next page, $hasPreviousPage true if has a previos page

Example:

#pageContent('+type:content +live:true +structureInode:5' 'date1' '5' '1')

#foreach($content in $list)

   title: $!content.contentTitle

   summary: $!content.NewsSummary

#end

Permanent Link to a File, Page, or Contentlet This macro create a permanent link to a File, Page or Contentlet from the identifier or inode of them and add the trackback RDF reference to the page.
In the case where the identifier is from a contentlet, you could include which page you want to display the contentlet information, adding the page identifier in the optional parameter "permalinkDetailPage", if this parameter is not pass, the macro will look if the contentlet structure have a detail page set, using this page if this page is not set then use the same page where the permalink is include adding in the url the ?id param with the identifier.

Macro Syntax:

#permalink(identifier)

Arguments:

identifier
This is the identifier or inode of the file, page or contentlet, you want to create the link.

Optional Parameters:

permalinkDetailPage (velocity variable not a parameter)
This is the identifier of the page that display the contentlet information. This parameter is only use for contentlets
permalinkTitle (velocity variable not a parameter)
This is the link title. if is not set the default title is "Permalink"

Usage:

Example:

#permalink('12345')

Example2:

#set($permalinkDetailPage='78945') #permalink('12345')

Example3:

#set($permalinkTitle ="The Title") #permalink('12345')

Permanent Link Trackback: Add RDF Trackback to a File, Page or Contentlet This macro create the RDF tracback reference in the page for a permanent link to a file, page or contentlet in the case of the contentlet it check if receive a parameter called "permalinkDetailPage" that is the inode or identifier of the content page detail. If not, check if the struture have a page default or return to the same page adding the parameter

Macro Syntax:

#trackback(identifier)

Arguments:

identifier
This is the identifier or inode of the file, page or contentlet, you want to create the RDF reference.

Optional Parameters:

permalinkDetailPage (velocity variable not a parameter)
This is the identifier of the page that display the contentlet or inode of the file, page or contentlet, you want to create the link.

Usage:

Example:

#trackback('12345')

Photo Carousel This macro generates a carousel of photos, displaying sequentially one after another.

Macro Syntax:

#photoCarrousel (photoList photoDimensions)

Arguments:

imageFolder
This is the path where the images to be displayed are stored.
photoList
This is the list of photos to be displayed on a carousel. Every element of this list specifies the image url and the link where the image will redirect when it's clicked. This is only a required parameter if the imageFolder hasn't been defined.
photoDimensions
This is a list that specifies the width and height of the image to be displayed.

Optional Parameters:

photoCarrouselAutoSlide
Set to true if you want an automatic sequential display of the photos, otherwise set to false.
imageFolder
The URI of the folder that have the images.
photoCarrouselSourceCode
The URI with the page that will display the images.
showCaptions
This variable determine if the macro will display the images' caption. Default value true

Usage:

The macro will display a carrousel of photos

Example 1: This show a simple way to call the macro setting the image folder


#set($imageFolder = '/global/images/screencaps/')

#set($photoDimensions = $contents.getEmptyMap())
#set($dummy = $!photoDimensions.put("width", "125"))
#set($dummy = $!photoDimensions.put("height", "125"))
#set($photoCarrouselAutoSlide = true)

#set($photoList = $contents.getEmptyList())
#photoCarrousel($photoList $photoDimensions)

Example 2: This show a simple way to call the macro with the photo list fields

#set($photoList = $contents.getEmptyList())

#set($photo = $contents.getEmptyMap())
#set($dummy = $!photo.put("url", "/html/1.jpg"))
#set($dummy = $!photo.put("link", "http://www.yahoo.com"))
#set($dummy = $!photoList.add($photo))

#set($photo = $contents.getEmptyMap())
#set($dummy = $!photo.put("url", "/html/2.jpg"))
#set($dummy = $!photo.put("link", "http://www.google.com"))
#set($dummy = $!photoList.add($photo))

#set($photo = $contents.getEmptyMap())
#set($dummy = $!photo.put("url", "/html/3.jpg"))
#set($dummy = $!photo.put("link", "http://www.dotcms.org"))
#set($dummy = $!photoList.add($photo))

#set($photo = $contents.getEmptyMap())
#set($dummy = $!photo.put("url", "/html/4.jpg"))
#set($dummy = $!photo.put("link", "http://www.hotmail.com"))
#set($dummy = $!photoList.add($photo))

#set($photoDimensions = $contents.getEmptyMap())
#set($dummy = $!photoDimensions.put("width", "125"))
#set($dummy = $!photoDimensions.put("height", "125"))

#set($photoCarrouselAutoSlide = true)

#photoCarrousel($photoList $photoDimensions)

Example 3: This show a simple way to call the macro with the photo list fields and showing captions

#set($photoList = $contents.getEmptyList())

#set($photo = $contents.getEmptyMap())
#set($dummy = $!photo.put("url", "/html/1.jpg"))
#set($dummy = $!photo.put("link", "http://www.yahoo.com"))
#set($dummy = $!photo.put("caption", "Yahoo"))
#set($dummy = $!photoList.add($photo))

#set($photo = $contents.getEmptyMap())
#set($dummy = $!photo.put("url", "/html/2.jpg"))
#set($dummy = $!photo.put("link", "http://www.google.com"))
#set($dummy = $!photo.put("caption", "Google"))
#set($dummy = $!photoList.add($photo))

#set($photo = $contents.getEmptyMap())
#set($dummy = $!photo.put("url", "/html/3.jpg"))
#set($dummy = $!photo.put("link", "http://www.dotcms.org"))
#set($dummy = $!photo.put("caption", "dotCMS"))
#set($dummy = $!photoList.add($photo))

#set($photo = $contents.getEmptyMap())
#set($dummy = $!photo.put("url", "/html/4.jpg"))
#set($dummy = $!photo.put("link", "http://www.hotmail.com"))
#set($dummy = $!photo.put("caption", "HotMail"))
#set($dummy = $!photoList.add($photo))

#set($photoDimensions = $contents.getEmptyMap())
#set($dummy = $!photoDimensions.put("width", "125"))
#set($dummy = $!photoDimensions.put("height", "125"))

#set($photoCarrouselAutoSlide = true)

#photoCarrousel($photoList $photoDimensions)

Photo Gallery
The Photo Gallery "macro" pulls and displays all the photos (jpgs and gifs files) of a given folder, it also pulls and displays sub folders if they contain photos.

Macro Syntax:

#photoGallery('/thefolder')

Arguments:

thefolder
Path to the folder that contains the photos and/or sub photo galleries.

Optional Parameters:

showPhotoTitle
Set to false if you want to hide the photo names from the listing. Default: true.
showSubgalleryTitle
Set to false if you want to hide the sub galleries names from the listing. Default: true.
photoWidth
Width used to display the full image. Default: 600.
photoHeight
Height used to display the full image. Default: 450.
thumbnailWidth
Width used to display the thumbnails. Default: 90.
thumbnailHeight
Height used to display the thumbnails. Default: 90.
indexImage
By default when the macro selects the index image of a folder it uses index.jpg, if no index.jpg is found then it uses the first image found in the folder, but this behavior can be changed setting the defualt indexImage name to use. E.G. #set($indexImage="myIndex.jpg")

Usage:

Let say you have a folder structure like the following:

/photo_galleries -> folder where resides photos and sub galleries
/photo_galleries/photo1.jpg -> image of this top level gallery
/photo_galleries/photo2.jpg -> image of this top level gallery
/photo_galleries/gallery_1 -> folder where the first gallery resides
/photo_galleries/gallery_1/index.jpg -> main image of this gallery
/photo_galleries/gallery_1/XXX.jpg -> any other image of this gallery
...
/photo_galleries/gallery_2 -> folder where the second gallery resides
/photo_galleries/gallery_2/index.jpg -> main image of this gallery
/photo_galleries/gallery_2/XXX.jpg -> any other image of this gallery
...

So calling,

#photoGallery('/photo_galleries')

Will display photo1 and photo2 as photos located in the /photo_galleries folder and then will list gallery1 and gallery2 as sub photo galleries of the /photo_galleries folder, the index.jpg (or index.gif) images are used as the main images when sub photo galleries thumbnails are shown, if the subfolder doesn't contain an index image then the first image found in the folder will be used as the index image.

To use the optional parameters you have to set them before the macro is called. E.G.
#set($showPhotoTitle = false)
#photoGallery('/photo_galleries')

Print Average Content Rating Prints out the average rating calculated by the dotCMS from the rating votes. It prints out the average rating formatted with two decimals. I.E. X.XX

Macro Syntax:

#printAverageRating(content_identifier)

Arguments:

content_inode
This is the identifier of the contentlet to be evaluated by the macro

Usage:

Example:

	#printAverageRating($content.identifier)

Print the Number of Votes of a Rated Content Prints out the number of votes of a content

Macro Syntax:

#printNumberOfVotes(content_identifier)

Arguments:

content_inode
This is the identifier of the contentlet to be evaluated by the macro

Usage:

Example:

	#printNumberOfVotes($content.identifier)

Pull RSS This macro will retrieve a RSS Feed and will return it in a list

Macro Syntax:

#pullRSS('url')

Arguments:

url
This is the URL where the RSS Feed is located.
rssTotal
Optional: The maximum number of entries retrieved by the macro.
rssFilter
Optional: A list of words that have to be in the title, these words are used to filter the RSS Feed entries.

Usage:

This macro returns a list with the RSS Feed. the macro will return the data in a variable called $list of contentlets $content.The contentlet's properties can be displayed by referencing their variable names. So $content.title would display the RSS entry title. there are four variable:
title
link
description
pubDate

Example:

#set($rssFilter = ['dotcms','dotmarketing'])
#set($rssTotal = 10)
#pullRSS('http://somesite/topnews.rss')
#foreach($content in $list)
   title: $!content.title
   description: $!content.description
#end

Pulling Content Any content or list of content in the content database can be pulled and displayed on the front end of your website by using the #pullContent() macro.

Macro Syntax:

#pullContent('query' '# results' 'sort by')

Arguments:

query
A lucene query that is copied from the "Content Manager" search screen. To see this query, search the content and click the "Show Query". Select the query and hit ctrl+c to copy to your clipboard. Return to the content you want to pull the list and paste it (ctrl+v) into the macro.
# results
Maximum number of contentlets to display on the listing
sort by
The name of the field you would like to sort the results by. This is the "DB Column" name found on the structure. If you want to return randomized results, you need to send sortBy as random.

Usage:

This macro returns a list or a single piece of content. If you specified more than one result you will have a variable named $list of contentlets $content. If you specified one piece of content, you can ignore the list and just use the $content variable. The contentlet's properties can be displayed by referencing their variable names. So $content.firstName would display the variable named firstName for the listed contents. The variable name can be found in the structure detail for the content type being used.
If you need to add a link to a content detail page you will need to use the content's inode by adding this variable: $content.inode

Example 1: This pulls a list of 5 content objects with structure inode 5 ordered by date1, and it displays the title and summary of each one.

#pullContent('+type:content +live:true +structureInode:5' '5' 'date1')
#foreach($content in $list)
   title: $!content.contentTitle
   summary: $!content.NewsSummary
#end

Example 2: This pulls a list of 1 random content objects with structure inode 5, and it displays the title and summary of each one.

#pullContent('+type:content +live:true +structureInode:5' '1' 'random')
#foreach($content in $list)
   title: $!content.contentTitle
   summary: $!content.NewsSummary
#end

Pulling and Displaying Related Content (Relationships) Any related content (driven by structure relationships) can be pulled and displayed on the front end of your website by using the #pullRelatedContent() macro.

Macro Syntax:

#pullRelatedContent('relationship name' 'content inode' 'limit' 'sort by')

Arguments:

relationship name
The name of the relationship as appears in the structures/relationships portlet.
'content inode'
The content inode which is the parent/child/sibbling of the related content you want to get.
limit
To restrict the number of results to show, if 0 is specified then it will pull all the results
sort by
To specify a sort by criteria by field variable name as listed in the structures portlet, if blank it will sort by the relationship order, also the varible named modDate is accepted to sort the results by last modified date.

Optional Parameters:

Condition (velocity variable not a parameter)
A lucene query that will be applied to the child before retrieve they

Usage:

This macro returns a list of related content. After the macro is called you will have a variable named $list of content objects. The content's properties can be displayed by referencing their variable names. So $content.firstName would display the variable named firstName for the listed contents. The variable name can be found in the structure detail for the content type being used.
If you need to add a link to a content detail page you will need to use the content's inode by adding this variable: $content.inode

Example 1: This pulls a list of up to 100 content related to content with inode 4686 that is related through relationship: Annual_Report_Article-Audio and it orders it by Headline, Text and Modified Date

#pullRelatedContent('Annual_Report_Article-Audio' '4686' '100' 'fullHeadline asc, bodyText desc, modDate')

#foreach($content in $list)
   headline: $!content.fullHeadline
   body: $!content.bodyText
#end

Example 2: This pulls a list of up to 100 content related to content with inode 4686 that is related through relationship: Annual_Report_Article-Audio and it orders it by Headline, Text and Modified Date. This only pulls content that match the condition where the Headline starts with the word "test".

#set ($condition = 'fullHeadline:test*')
#pullRelatedContent('Annual_Report_Article-Audio' '4686' '100' 'fullHeadline asc, bodyText desc, modDate')

#foreach($content in $list)
   headline: $!content.fullHeadline
   body: $!content.bodyText
#end

Random Image: Return a random image from a specified folder You must provide to this macro a path in order in order to return a random image

Macro Syntax:

#randomImage (path)

Arguments:

path
This is the path to a folder.

Usage:

The macro will return the image selected in the variable $image

Example:

#set ($path = '/global/images/')
#randomImage($path) 
<img src="/resize_image?inode=$!{image.inode}&w=911&h=322" alt="Top Banner" width="911" height="322" />

Retrieve Selected Inode Gets the inode selected by the user. Typically this will be used in 'detail' style pages (e.g. /news/details.dot), and therefore the inode will actually correspond to a selected contentlet. Note that the name of the request parameter used for extracting the selected inode, is determined by the properties key "INODE_PARAMETER_NAME". In case this key is missing, the parameter name defaults to "inode"

Macro Syntax:

#selectedInode()

Usage:

The macro will get the passed in inode for you

Example:

#selectedInode()

Send To Friend This macro generates a form to send an article to a friend by email.

Macro Syntax:

#sendtofriend (articleText)

Arguments:

articleText
This is the value for Article Text, sent on the email.

Optional Parameters:

sendToFriendId
This is the value of the form div.
sendToFriendStyle
This is the value of the style of the form div. By default it's "display:none;", so the form is hidden
sendToFriendCSSClass
This is the value of the CSS class of the form div.
subject
This is the value for the email subject.

Usage:

The macro will display a send to friend form

Example: This shows a simple way to call the macro with the required fields

#set($sendToFriendStyle = "display:inline;")
#sendtofriend('This is a Send To Friend test!!!')

Site Map: Add a Site Map to a Page.

Macro Syntax:

   #sitemap()

Usage:
Use this macro if you want to add a site map for your whole site.

Example:

#sitemap() This would build a site map for everything from the root fo the site. It will stop at 100 levels deep.

Site Map Folder: Add a Site Map to a Page from a Folder to a Specific Depth.

Macro Syntax:

#siteMapFolder(2,2,'/folder1/myFolder')

Arguments:

Start Level
This is number of folders the map should start at from the path.
Depth
This is how many folders to drill inside of from the start depth.
Path
This is the path to the folder to start at.

Optional Parameters:

reverseOrder (velocity variable not a parameter)
Set this boolean to true to return the Site Map ordered descending. Default: false.
Show Home Page Link
Set to true if you want to display a link to Home Page

Usage:
Use this macro if you want to add a site map to your page from a specific path. You can specify how many level from the path to start and end.

Example:

#siteMapFolder(2,2,'/folder1/myFolder')

This would build a site map for everything 2 levels beneath /folder1/myFolder and go 2 levels deep.

Example2:

#set($reverseOrder = true)
#siteMapFolder(2,2,'/folder1/myFolder')

This would build a site map for everything 2 levels beneath /folder1/myFolder and go 2 levels deep in inverse order.

Example3:

#set($showHome = true)
#siteMapFolder(2,2,'/folder1/myFolder')

This would build a site map for everything 2 levels beneath /folder1/myFolder and go 2 levels deep adding a link called: Home linked to the site's Home Page.

Social Bookmarks This macro generates bookmark links to the most popular social bookmarking sites such as Digg, Del.icio.us or Reddit, you can choose from more than 10 different sites.
Available sites: blinkbits, blinklist, blogmarks, co.mments, connotea, del.icio.us, digg, google, newsvine, reddit, spurl, stumble upon, technorati, wists, yahoo.

Macro Syntax:

#socialBookmarks()

Usage:

The macro will generate the links to the chosen sites, given a list of the different bookmarking sites you wish to include.

Example:

#set ($socialBookmarksList = ['digg','delicious','yahoo','google','newsvine'])

#socialBookmarks()

Generates a Tag Cloud Based on Used Content Tags This macro generates a list of tag links with all the tags used on the content of the given structures, every link generated is associated one of the following css classes [xSmallTag, smallTag, mediumTag, largeTag, xLargeTag] depending on the usage of the tag.

Macro Syntax:

#tagCloud(structureNames url maxNumberOfTags)

Arguments:

structureNames
The list of structure names you want to use to pull the tag usage. ["name1", "name2", ...]
url
The url that is going to be used to link the tags in the cloud. To this url the macro adds the tag and the tag count as parameters of this url. <your url>?tag=<tag>&tagCount=<N>
maxNumberOfTags
Maximum number of tags to display on the listing, if 0 is provided then all the tags will be listed

Optional Arguments:

ignoredTags
A list of tags you want to be ignored by the macro, I.E. [tag1,tag2]

Example 1:

#tagCloud(["White Papers", "Blogs", "Testimonial"] '/mypage.dot' 40)

Example 2:

#set($ignoredTags = ["tag1", "tag2"])

#tagCloud(["White Papers", "Blogs", "Testimonial"] '/mypage.dot' 40)

Create a text area for a form. This is needed so you can create a text area in the backend of the dotcms.

Macro Syntax:

#textArea(name style)

Arguments:

name
text area html widget name
style
style to apply to testarea. ie.. width:200px

Optional Arguments:

id
Text Area ID
value
Text Area Initally Value

Example 1:

#textArea($myName "width:200px")

Example 2:

#set($id = "myID")

#set($value = $myValue)

#textArea("myName" "width:200px")

Title Generator This macro will create an image with the title sent as parameter.

Macro Syntax:

   #titleImage('title')

Arguments:

Font Face
Font Face: This is the font face to use when generating the image
#set ($font = 'tahoma')
Font Size
Font Size: This is the font size to use when generating the image
#set ($size = '20')
Font Color
Font Color: This is the RGB numbers for the color to use when generating the image
#set ($color = '30,30,30')
Break
Break: This is the maximum number of characters per line on the image. This is optional, if not defined all the title will be displayed on one line
#set ($break = '30')
title
The title text that will be shown in the image

Example:

   #set ($font = 'tahoma')
   #set ($size = '20')
   #set ($color = '30,30,30')
   #titleImage('Test Title')

Video Gallery This macro pulls all FLV files from a folder and displays a flash video player for each video. If a JPG image with the same name as the video file is provided it will be displayed as a thumbnail of the video.

Macro Syntax:

#videoGallery(url)

Arguments:

url
This is the path in the CMS where the videos and images are stored.

Optional:

width
This is the width used to create the image thumbnail. If not defined width defaults to 90 pixels.
height
This is the height used to create the image thumbnail. If not defined height defaults to 90 pixels.
showVideoTitle
Set this to false if you don't want to display the video title. It's set to true by default.
showVideoDescription
Set this to false if you don't want to display the video description. It's set to true by default.
r
This is the R color (R,G,B) to use as thumbnail background color. By default background color is set to white.
g
This is the g color (R,G,B) to use as thumbnail background color. By default background color is set to white.
b
This is the b color (R,G,B) to use as thumbnail background color. By default background color is set to white.
galleriesToShow
This variable determines how many videos to show at a time. If not defined all videos are displayed, if set the galleriesToShow videos will be displayed with links to view Next and Previous.

Usage:

The macro will create a video gallery of all videos in the folder: /videos/.

Example:

#videoGallery('/videos/')

Example2:

#set($showVideoTitle = false)
#set($showVideoDescription = false)
#videoGallery('/videos/')

This will display the video gallery with no titles and no descriptions for each video.

Example3:

#set($w = 200)
#set($h = 200)
#videoGallery('/videos/')

This will display the video gallery with image thumbnails of 200 x 200.

Example4:

#set($galleriesToShow = 2)
#videoGallery('/videos/')

This will display the video gallery with only two videos at a time, it will display links to Next and Previous to view the rest.

Video Player: Play Video in a Flash Video Player You can provide this macro a URL to a .flv file and it will provide a player for your video.

Macro Syntax:

#videoPlayer(url)

Arguments:

url
This is the path to the flv.

Optional Parameters:

width
This is the new video width (optional). You could use the video width parameter alone or in combination with the height parameter. Default: 275.
height
This is the new video height (optional). You could use the video height parameter alone or in combination with the width parameter. Default: 265.
autoPlay
If the video plays automatically when it loads. Default: true.
backgroundColor
The backgrounds color of the player. Default: #ffffff.
scale
default (Show all) makes the entire movie visible in the specified area without distortion, while maintaining the original aspect ratio of the movie. Borders may appear on two sides of the movie.
noorder scales the movie to fill the specified area, without distortion but possibly with some cropping, while maintaining the original aspect ratio of the movie.
exactfit makes the entire movie visible in the specified area without trying to preserve the original aspect ratio. Distortion may occur.
Default: 'default'.
autostart
true if you want to play the movie automatically when the video player is loaded.
false the movie won't be played automatically.
Default: 'true'.
overstretch
true will support overstretch.
false won't support overstretch.
Default: 'false'.
image
The image to show in the player. Default: default.jpg.

Usage:

The macro will play the video within an embedded flash player

Example:

#videoPlayer('/global/videos/myvideo.flv')

Example2:

#set($width = '500')
#set($height = '500')
#set($autoPlay = 'true')
#set($backgroundColor = '#000000')
#set($scale = 'default')
#videoPlayer('/global/videos/myvideo.flv')

"" ""