Location: PHPKode > projects > synType CMS > macro-reference.txt

Macro-Reference for synType Version 0.12.2
==========================================
Modified on 2010-01-29


NEWS
The content macro has an additional parameter 'count' (2009-01-30).
New portal macro added (2009-02-01).



All macros, including their parameters, arguments etc., must be surrounded by duobbled opening and doubbled closing parentheses when used.
Example: 
{{macro}}

In the following documentation we do not put them in parentheses to make them more readable.

Some macros require parameters. Sometimes parameters are optional.
Parameters are separated from the macro name by a colon (macro:parameter).
Parameters with a well defined name (non variable) are noted with their name: parameter
If there is a list of possible non varaible parameters you can chose from, this is noted as: {choice1|choice2|choice3...}
Required, variable parameters are noted like this: <parameter>
Optional parameters are noted like this: [parameter], or a list: [parameter1[,parameter2]]
If optional parameters are variable it would be: [<paramenter>]
Lists of parameters are separated by commas: parameter1,parameter2

Some examples:
macroname:parameter
macroname:{choice1|choice2}
macroname:{choice1|choice2|<choice3>}
macroname:<parameter>
macroname[:parameter]
macroname[:parameter[,parameter2]]

Some parameters need arguments to be passed to them. Those parameters are usually called functions.
They are noted like this: function(argument) or function(argument1,argument2)
For arguments, the same rules as for parameters apply.

Examples: 
macroname:parameter,function(argument[,<optional_variable>])
macroname:parameter[,{parameter|function(argument)|other_function({argument|<variable>})}]



Template and Container Macros
-----------------------------

These macros are defined when creating or editing a Template, or Container, respectively.
To access these macros, simply write them with their macro name in doubled parenteses as described above.
Using these macos will insert the assigned Template or Container.

If a Container is wrapped by a Wrapper Template, you can use the following macros in the Wrapper Template:

container:title
	This macro inserts the title/name of the wrapped Container.
	
container:content
	This inserts the contents of the Container into the Wrapper Template.



'html_head' Macros
------------------

These macros are intended to be used within the <head>-tag of HTML page templates.

html_head:title
	This macro inserts the title of the page
	
html_head:meta
	This macro inserts meta-tags (automatically) generated by synType.
	These are: content-type, keywords, description, author, date and robots.
	
	It is possible to overwrite the default meta-tag for robots and content-type, or define own meta-tags.
	The default for robots is 'index,follow'. The default for content-type is defined in the system configuration file.
	To define own meta-tags, or overwrite them, use the meta Macro before html_head:meta:
	meta:<name>,<value>
	To overwrite the content-type settings use the following macros:
	meta:content-type,<value>
	meta:content-encoding,<value> 
	


'final' Macros

These macros can be used anywhere throughout the whole system; in templates, container and even in any content.

final:meta
	This is an alias of 'html_head:meta'.
	
final:url[,{site|images|button|exports|pdf|xml|scripts|css|files|errors|spg[,secure]}]
	This macro generates an URL that points to the directory given as the second parameter.
	If the second parameter is omitted, then it points to the root directory.
	If 'spg' is used as the second parameter, the URL will point to the current page.
	If the third parameter is used with 'spg', SSL/TLS will be forced.
	
	NOTE! If you are using Template Sets you should consider using the following macro instead. 
	
final:url,tmplset,{images|scripts|css}
	This macro is used in Templates and Containers to insert an URL to images, JavaScript-Files 
	or CSS-Files of the currently active Template Set.



'navigation' Macros

These macros can be used to create the Web site navigation.
	 
navigation:title
	This macro inserts the title/name of the current section.

navigation:root
navigation:root()
navigation:root([-]<identifier1>[|<identifier2>]...)
navigation:root(...)[,<template>[,{hide|<template>}]]
	This macro can be used to insert items from the root of the tree.
	With no arguments it inserts all root items.
	If arguments are provided, these are are a list of section identifiers. If the list is 
	prefixed with a hyphen (-), the items listed will be excluded from the result. Without
	the hyphen, only items within the list will be included in the result.
	The next parameter is optional, specifying the template to render the item in.
	The last parameter is optional as well and can be either 'hide' oder another template.
	This parameter is used to render items of the active section in a different template or
	'hide' it.
	
The following macros work the same way, but different items will be inserted by them.
To make it more simple, we just tell their shortest name.

navigation:children
    This macro inserts child items of the current section.
	This macro must be written in the same way as the 'navigation:root' macro.
	It has the same parameters and all.
	
	This macro has been renamed in Version 0.11!
	The old name was navigation:sub, up to Version 0.10.2
	
navigation:parent
	This macro inserts parent items of the current section
	This macro must be written in the same way as the 'navigation:root' macro.
	It has the same parameters and all.

	This macro will be available in Version 0.11
	It will bring back the functionality of the old 'navigation:sub(-v)'.

navigation:list
    This macro inserts items by providing their identifier in the arguments list.
	This macro must be written in the same way as the 'navigation:root' macro!
	The difference is that you must not prefix the list with a hyphen (-)! There is
	nothing to exclude, anyway.

navigation:item
    This macro inserts just one item, selected by its identifier as the argument.
	Everything else must be written in the same way as the 'navigation:root' macro! 
	Means, you may use one or two templates or 'hide' instead of the second template.

navigation:tree(<mode>[|<depth>]),<template>[,<template>[,<template>[,<template>]]]
	This macro inserts a navigation tree based on the navigation path, partly or fully, 
	depending on 'mode'.
	
	The 'mode' parameter must be one of the following:
	- root: Inserts the tree starting from the currently active root section.
	- children: Inserts the tree starting from the currently active sub-section.
	- parent: The same as 'self', but including parent sections.
	
	The 'depth' parameter controls up to how many levels to render. If it is an
	integer, it must be greater than 0. If 'mode' is 'root', the keyword 'active' makes 
	it stop at the currently active section.
	
	There are up to four templates you can specify. They have the following meaning:
	1. Renders each item.
	2. Renders sub-items. If omitted, the first template is used.
	3. Renders sub-items of the same level. It is used as a kind of container.
	4. Renders a top-level item an its sub-items. It can be used as a container as well.
	
	NOTE! All four templates MUST contain the local macro '{{subitems}}' to be replaced 
	by the item lists!
	
navigation:sitemap[(<depth>)],<template>[,<template>[,<template>[,<template>]]]
	This macro is not yet implemented!

	Temporary description of navigation:sitemap

	This macro inserts a sitemap of the Web site including all sections down to
	the level specified by 'depth'. If 'depth', which is an integer, is omitted,
	the full hierarchy will be rendered.

	There are up to four templates you can specify. They have the following meaning:
	1. Renders each item.
	2. Renders sub-items. If omitted, the first template is used.
	3. Renders sub-items of the same level. It is used as a kind of container.
	4. Renders a top-level item an its sub-items. It can be used as a container as well.
	
	NOTE! All four templates MUST contain the local macro '{{subitems}}' to be replaced 
	by the item lists!
	
navigation:path[,<separator>]
	This macro inserts the path, starting from the selected root item, down to the
	current section. You may have seen it in form of 'You are here: ...'. All items
	in the path are Links that are generated automatically! This is different from all
	the above macros.
	The separator ca be any kind of string, excluding a comma! HTML is allowed of course.
	It separates each item from the other. If the separator string is omitted, '->' will
	be assumed and a warning is generated in the CMS Report. 
	
NOTE: Macros that use template parameters can contain any other macro (except some local ones).
However, there are two local macros that should/must be used in the template: {{url}} and {{title}}.
'url' must be used in an anchor-tag for example. 'title' simply inserts the items title/name.
You may also use {{identifier}} in the templates to insert the identifier of the item. With
the local macro {{description}} you can insert the description of the item.
Without the url macro, the item will point nowhere, NO LINK IS GENERATED AUTOMATICALLY! 
	 



'system' Macros
---------------

These macros can be used in any template or container.

system:button,<name>
	This will insert a button which is defined in system-templates, where the 'name' matches its macro name.
	
system:form,<name> 
	This will insert a form which is defined in system-templates, where the 'name' matches its macro name.
	
system:login,<form>[,<panel>]
	This will insert a form for login if we have a guest. If panel is given, and we have a valid user, a control panel for the user is inserted.
	form is a template. Predefined ones are found in system-templates (login_quick or login_panel).
	panel is a template. The predefined one is found in system-templates (user_panel).
	
system:search,pagination[,<configuration>]
	This macro inserts pagination links on pages of search results.
	The optional configuration is used to format the links. This is predefined in system-buttons (pagination).
	TODO: More documentation on this.
	
system:search,query
	This macro inserts the query string last executed. This can be used to remind the user of what he was searching.
	
system:search,<result_row>,<no_results>
	This macro renders rows of search results.
	result_row is a template to render ne row of results. A predefined one can be found in system-templates (search_row)
	no_results is a template to tell that no results are returned from the query. A predefined one can be found in system-templates (search_noresults)

system:famous,articles,<template>[,<rows>]
	This macro generates links to famous articles published on the system (globally).
	This means that articles have a lot of clicks and are actively commented.
	template specifies which template to use that formats the link. template can be left an empty string to use the default.

system:hot,articles,<template>[,<rows>]
	This macro generates links to hot articles published on the system (globally).
	This means that articles have a lot of clicks.
	template specifies which template to use that formats the link. template can be left an empty string to use the default.

system:active,articles,<template>[,<rows>]
	This macro generates links to the most active articles published on the system (globally).
	This means that articles have a lot of comments.
	template specifies which template to use that formats the link. template can be left an empty string to use the default.

system:latest,articles,<template>[,<rows>]
	This macro generates links to the latest articles published on the system (globally).
	template specifies which template to use that formats the link. template can be left an empty string to use the default.

system:latest,articles,<template>,<identifier>[,<rows>]]
	This macro generates links to the latest comments posted in the section named by identifier assigned to an article.
	template specifies which template to use that formats the link. template can be left an empty string to use the default.

system:latest,comments,<template>[,<rows>]]
	This macro generates links to the latest comments posted in the system (globally) for an article.
	template specifies which template to use that formats the link. template can be left an empty string to use the default.

system:latest,comments,<template>,<identifier>[,<rows>]
	This macro generates links to the latest comments posted in the section named by identifier assigned to an article.
	template specifies which template to use that formats the link. template can be left an empty string to use the default.

Local macros for system:latest

Sample template: <a href="{{url}}">{{text}} ...</a> - {{date}}<br />

url
	This macro inserts the URL (e.g. to be used in the href attribute of an A-tag).
	
text
	This macro inserts the text of the link.
	In case of links to articles, this is the title. In case of links to comments this is the comment itself.
	In both cases the original text is cut off at 50 characters.
	(May implement this differently at some time!)
	
date
	This macro inserts the date of creation (comments) or first date of publishing (articles).  



'account' Macros
----------------

These macros can be used anywhere; they display information about the currently logged in user.

account:group
	This macro inserts the group name. 

account:username
	This macro inserts the user name. 

account:name
	This macro inserts the full name. 

account:email
	This macro inserts the email address. 

account:phone
	This macro inserts the phone number. 

account:salutation
	This macro inserts the salutation. 

account:address
	This macro inserts the address line (usually the name). 

account:address2
	This macro inserts additional address info (usually C/o etc.). 

account:street
	This macro inserts the street. 

account:zip
	This macro inserts the zip code. 

account:city
	This macro inserts the city. 

account:country
	This macro inserts the country.
	
--------------------------------------------------
Comming Soon: 
Macros used in the sign up-form, the account page, 
the lost password-form and account related emails



'portal' Macro
--------------

This macro loads articles, selected and sorted by its functions, into the internal cache and indexes them.
The result dependends on the selector and the order function used. Subsequent calls of the macro, with
different functions and/or parameters will empty the cache and start a new query based on the new parameters.
The macro will insert the article selected by its index and by using the given article template.

portal:select(<selector_function>[;order_function]),<template>[,<index>[,count]]
	This is the basic synta of the macro. The 'selector_function' and the 'order_function' is described below.
	
	selector_function:
	auto
	This function can be used to select any article from any section. The result can be modified by using the
	'order_function'
	categories(<category_string>[|<category_string>]...)
	This function selects articles that belong to one of the given categories. One or more categories can be
	given as strings. Each string must be separated by a pipe character (|).
	sections(<identifier>[|<identifier>]...)
	This function selects articles that belong to one of the given sections. One or more categories can be
	given by their identifier. Each identifier must be separated by a pipe character (|).
	search(<search_string>)
	This function selects articles found by the the search string. The search string can consist of one or more
	words. Words must be separated by blanks. Asterisks (*) can be used as wildcards.
	
	order_function (optional):
	order({priority|date|clicks|comments}[|{priority|date|clicks|comments}]...)
	This function can be used to modify the sort order of the result. All sorting is done in a descending order.
	It is possible to give one, up to four parameters, separated by pipe characters. 'priority' sorts by the 
	priority of articles, 'date' sorts by the date articles were first published, 'clicks' sorts the number of
	clicks articles have gotten and 'comments' sorts by the number of comments articles have assigned to them.
	shuffle({priority|date|clicks|comments}[|{priority|date|clicks|comments}]...)
	This function does the same as 'order(...)' with the difference that the result is shuffled. This means,
	the selected articles will be the same, but the indices used to address articles changes to a random order. 



'content' Macro
---------------

This macro loads articles of the current section into the internal cache and indexes them.
The order of the index dependends on the priority and the date of first publish.
The macro will insert the article selected by its index and by using the given article template.

content:<template>[,<index>[,<count>]]
	This macro inserts one or more articles using the given article template.
	'template' specifies the article template to render the article in.
	'index' is optional and can be used to select the desired article. The default value is 1.
	If 'count' is given, 'count' number of articles will be rendered, starting at 'index'.
	
	Examples:
	{{content:article_template,1,5}} will render the articles 1 to 5.
	{{content:another_article_template,6,5}} will render the articles 6 to 10.
	


'article' Macros
----------------

These macros can be used in article templates or in templates that are, directly or indirectly, assigned
to the articles page template. Each of these macros renders a property of the currently selected article 
within the template. properties are only rendered if they are available. 

article:id
	This macro inserts the ID.

article:priority
	This macro inserts the priority value.

article:views
	This macro inserts the number of views this article has counted.

article:author
	This macro inserts the real name of who has written the article.

article:creator
	This macro inserts the user name of who has written the article.

article:editor
	This macro inserts the user name of who has edited/modified the article.

article:image[,<style>]
	This macro inserts the assigned teaser image.
	The optional style variable can contain any CSS attributes.

article:category[,link]
	This macro inserts the category of the article.
	The optional link parameter can be used to make the category a link to the (full) article page

article:title[,link]
	This macro inserts the title of the article.
	The optional link parameter can be used to make the title a link to the (full) article page

article:{subtitle|teaser1|teaser2|content}[,<length>[,{word|sentence|paragraph}[,{0|1}]]]
	This macro inserts the sub-title, the teaser, the secondary teaser or the content of the article.
	If the second parameter is given, which is a numeric value, the length of the selected content type
	can be set. The third, optional parameter sets the mode in which the length value operates. word
	counts the number of words, sentence counts sentences and paragraph counts paragraphs after which 
	to cut off the content. sentence is the default.
	The last, optional parameter lets you decide whether to render the content with or without HTML-Tags.
	If 0 is used, which is the default, HTML-Code will be left untouched, if 1 is used, all HTML is 
	stripped off.   

article:{date_publish|date_expire|date_created|date_changed}[,<date_format>]
	This macro inserts a date assigned to the article.
	The optional variable date_format can be used to format the date as desired. The format string
	that has to be used is that of PHP's date-function. (go to http://www.php.net, and enter 'date'
	in the search form to see the help page for more information.)

article:related,<max_rows>[,<template>[,<relevance>]]
	This macro inserts a list of articles that are related to this article in some way.
	max_rows lets you define the maximum number of related articles you want to display.
	The optional variable template lets you define a template to render the generated content in.
	If template is omitted, an unordered list (<UL>-Tag) will be used instead of a template and
	will render links with the title of the article and a tooltip with the subtitle.
	Otherwise, if you provide a template, you can use the 'related' macro within the template.
	The last, optional parameter lets you set the relevance level. This must be a number:
	1 means high, 2 means medium and 3 means low relevance.
	
article:comments,count
	This macro inserts the number of comments this article has attached
	This is useful (and popular) to show together with a link to the comments page
	(see below, the macro article:control,comments,<template>).

article:comments,form,<template>
	Provided the article allows comments and the current user has permissions to add comments to
	the article, this macro inserts a form to add comments to the article.
	The variable template lets you specify which template to use that contains the form. A predefined
	template can be found in the system-templates section (comments_form).
	
article:comments,pagination,<template>
	Provided the article allows comments and the current user has permissions to view comments, this
	macro inserts links for the pagination.
	The variable template lets you specify the template which should be used to configure the look &
	feel of the links.
	
article:comments,list,<template1>[,<template2>]
	Provided the article allows comments and the current user has permissions to view comments, this
	macro inserts the comments.
	The variables template1 and, optionally, template2, lets you specify templates to render the
	comments in. If template2 is given, you can produce alternating rows with different designs.
	This means one row is rendered in template1, the next in template2, then template1 again and so on.
	Use the 'comment' macro within your templates.
	
article:rating
	This is not implemented!
	
article:control,{more|back|show_comments|print|recommend|pdf|discuss}
	This macro inserts links for the option selected in the second parameter.
	show_comments shows a page with only comments and the add comments form. back is also meant to be used
	on the comments page and naviagtes back to the article.
	more means a link to the full article page, print opens a window with the article to be printed,
	recommend lets users send an email to a friend with a link to this article by displaying a form to 
	enter an email address and whatever, pdf creates a link to download this article as PDF and discuss
	creates a link to the forum where this article can be discussed.
	The second parameter is also the name of the template that you may alter under System-Templates.
	NOTES:
	pdf and discuss are not available and probably they never will!
	recommend is not implemented in current versions of the CMS!


Additionally, the folowing are available in the 'search_row' System-Template

article:number
	Inserts the sequential number of the current result row of a query.
	
article:total_rows
	Inserts the number of total rows the query returned.
	


'related' Macros
----------------

These macros can be used in article templates. Each of these macros renders a property of the
related article of the currently selected article in the template. properties are only rendered if they 
are available. 

related:id
	This macro inserts the ID.

related:page_id
	This macro inserts the page ID.

related:author
	This macro inserts the real name of who has written the article.

related:creator
	This macro inserts the user name of who has written the article.

related:editor
	This macro inserts the user name of who has edited/modified the article.

related:category[,link]
	This macro inserts the category of the article.
	The optional link parameter can be used to make the category a link to the (full) article page

related:title[,link]
	This macro inserts the title of the article.
	The optional link parameter can be used to make the title a link to the (full) article page

related:{subtitle|teaser1|teaser2}[,<length>[,{word|sentence|paragraph}[,{0|1}]]]
	This macro inserts the sub-title, the teaser, the secondary teaser or the content of the article.
	If the second parameter is given, which is a numeric value, the length of the selected content type
	can be set. The third, optional parameter sets the mode in which the length value operates. word
	counts the number of words, sentence counts sentences and paragraph counts paragraphs after which 
	to cut off the content. sentence is the default.
	The last, optional parameter lets you decide whether to render the content with or without HTML-Tags.
	If 0 is used, which is the default, HTML-Code will be left untouched, if 1 is used, all HTML is 
	stripped off.   

related:{date_publish|date_expire|date_created|date_changed}[,<date_format>]
	This macro inserts a date assigned to the article.
	The optional variable date_format can be used to format the date as desired. The format string
	that has to be used is that of PHP's date-function. (go to http://www.php.net, and enter 'date'
	in the search form to see the help page for more information.)
	NOTE:
	date_publish, date_expire and date_created are not implemented!
	
related:rating
	This is not implemented!
	
related:url
	This macro inserts the URL pointing to the full article page. This can be used to create custom
	links.
	


'comment' Macros
----------------

These macros can be used in article templates. The macro is divided into two sub-sections, one for
the form to add new comments, and another to render properties of a comment.

The macros to create the form:

comment:input,hidden
	This macro inserts hidden fields required by the form.
	ATTENTION! Do not ommit this in your template!
	
comment:input,username[,{<size>|<width>|<class>}]
	This macro inserts a text field for the user/nick name.
	size can be used to set the size attribute of the input field (e.g. size="<size>"), where size is a number.
	width is similar to size, but is a style. Use '200px', '20em' or '20%' formats. Other strings will not be
	interpreted!
	class lets you specify the class name for the input tag.
	
comment:input,email[,{<size>|<width>|<class>}]
	This macro inserts a text field for the users email address.
	size can be used to set the size attribute of the input field (e.g. size="<size>"), where size is a number.
	width is similar to size, but is a style. Use '200px', '20em' or '20%' formats. Other strings will not be
	interpreted!
	class lets you specify the class name for the input tag.

comment:input,email_hide[,checked]
	This macro inserts a checkbox as an option to let the user hide his email address.
	The optional parameter checked makes the checkbox checked by default.

comment:input,email_encode[,checked]
	This macro inserts a checkbox as an option to encode the users email address so robots cannot see them.
	The optional parameter checked makes the checkbox checked by default.

comment:input,email_link[,checked]
	This macro inserts a checkbox as an option to make the users email address a mailto link.
	The optional parameter checked makes the checkbox checked by default.

comment:input,hide_user[,checked]
	This macro inserts a checkbox as an option to hide the users user/nick name.
	The optional parameter checked makes the checkbox checked by default.
	ATTENTION! It is not recommended to allow this option! So better leave it out of your form. 

comment:input,body[,{<width>|<class>}[,<rows>]]
	This macro inserts a checkbox as an option to make the users email address a mailto link.
	width is a style to set the width of the textarea field. Use '200px', '20em' or '20%' formats. Other strings 
	will not be interpreted!
	class lets you specify the class name for the textarea.
	rows lets you specify the height of the textarea in rows/lines.
	
Properties of a comment

comment:id
	This macro inserts the ID of the comment.

comment:anchor
	This macro inserts an anchor for the comment.
	This is useful if you plan to have links that directly point to a comment (this comment).
	This is a must if you're using the macro 'system:latest,comments[,<rows>]' which generates
	links to the latest comments. Those links will go to the article and then, directly, to the
	comment that was clicked. 

comment:number
	This macro inserts the serial/sequential number.

comment:user_id
	This macro inserts the ID of the user.

comment:username
	This macro inserts the user/nick name of who has created the comment.

comment:email
	This macro inserts the email address of who has created the comment.

comment:content
	This macro inserts the text of the comment.

comment:{date|date_created}[,<date_format>]
	This macro inserts a date assigned to the comment.
	The optional variable date_format can be used to format the date as desired. The format string
	that has to be used is that of PHP's date-function. (go to http://www.php.net, and enter 'date'
	in the search form to see the help page for more information.)

Return current item: synType CMS