Free-Conversant Support / Simple Macros
 Home   About Conversant   Free Sites   Hosting   Support   XML-RPC 

Search



Documentation >> Macros >> Simple Macros

What Are Conversant's Macros?

Conversant's macros are html comment tags that you can put in your pages or templates (or even in resources). They are automatically replaced at serving time by information extracted from the database. For example, the navigation bar (that appears by default in the left column of your site) is inserted into the template by the use of such a simple macro: <!--#navbar-->.

All macros begin with <!--#, followed by the name of the macro. They all end with -->. For the simplest macros, like <!--#navbar-->, that's all there is to it.

Some macros also allow you to specify parameters which affect what the macro puts on your page (the macro's output). In most cases, these are written just like HTML tag attributes, where you specify the name of the parameter, then an equals sign, and then the value of the parameter inside double quotes. Here's an example:

<!--#msgBody msgNum="71"-->

In that example the macro name is "msgBody", and a single parameter named "msgNum" is being passed to it. The value of the parameter's is "71". (This macro is telling Conversant to insert the text from message 71. For more information on this macro, see the documentation on Message Macros.

Note that macros look like html comments, so if they're not processed by Conversant for some reason, they won't be visible in the pages. Also, you may disable any simple macro temporarily by removing the '#' that precedes the name.

Important Tip: if macro doesn't seem to be working correctly, remember to view the source of your page! Macro errors are often shown there in <!--html comments>.

Supported Simple Macros

This is not a complete list of the macros. There are HUNDREDS of macros! There's a more complete list here.

<!--#siteName-->

Replaced with the "name" of the conversation, as set in the "General" panel of the admin preferences.

<!--#siteUrl conversation="name of conversation"-->

Replaced with the web URL of the conversation. You might use it in your navigation bar, for example, instead of typing out the URL for every link.

Note that the URL returned by this macro always ends with a '/'.

The parameter "conversation" is optional. If not provided, then it returns the url of the current conversation. If it is provided, then it returns the url of the specified conversation. (Note that it only looks for conversations in the current zone.)

<!--#siteLink text="link text" conversation="name of conversation" id="link-id" class="link-class" style="link-css-style" title="link title" ...-->

Replaced with a link to the conversation's home page.

The optional parameter "text" becomes the text of the link as shown on the page. If not provided, the value comes directly from siteName macro.

The parameter "conversation" is optional. If not provided, then it links to the current conversation. If it is provided, then it links to the specified conversation. (Note that it only looks for conversations in the current zone.)

id, class, style and title are optional, and map directly to the html tag attributes of the same name

This tag also supports the full set of JavaScript Events for Link-Producing Macros (also known as the "Intrinsic Events").

<!--#pageTitle-->

Replaced with the title of the current page (or it's subject if it's a message).

<!--#stylesheetTag name="cssname" embed="true/false"-->

This macro is how you add stylesheets to your template (typically in the head of your template).

The name attribute is optional. If not provided, Conversant will use the default stylesheet for your page, as specified in the structure editor. If it is provided, then the stylesheet you've named will be used instead. This attribute is included to allow you to use more than one stylesheet in a page or template.

The embed attribute is also optional. If not provided, then the default value is used, which is false. False indicates that your page will link to the stylesheet, which will be served separately from the page and cached by the browser. True indicates that the page will have the stylesheet embedded in it, thus forcing the browsers to download the stylesheet with every page they request.

To specify the default stylesheet for your page, use the structure editor in your site's admin area (/yourSiteName/admin/conversations/yourSite/structure)

<!--#requireStylesheet name="cssname" embed="true/false"-->

This macro can be used anywhere in any template, message or resource. It doesn't actually insert anything into your page, but instead causes the stylesheetTag macro to link to an additional stylesheet.

The parameters for this macro are identical to those for the stylesheetTag macro.

Some pages on your site may require additional stylesheets that you don't use on the rest of your site. For example, you may have a large group of styles which are only needed by your Weblog II page. You could put a stylesheetTag macro in your weblog's wrapper template, but <link> and <style> tags are only supposed to appear in the HTML <head> section.

You could create a new "full page template" for the weblog, but then if you redesign part of your site you have to make the same changes in both templates.

This macro solves problems like that. You can put it anywhere (such as in your weblog's wrapper template), and the stylesheetTag macro will link to the stylesheet you specify (in additional to whatever it was already going to link to).

Use this macro as often as you like, to link to as many different stylesheets as you need. It will only link to a particular stylesheet one time (so it's ok to ask for the same stylesheet from two different templates).

<!--#javascript name="jsname" language="JavaScript" type="text/javascript" embed="true/false" extension=".js"-->

Replaced with the javascript (either the text of the script, or a link to it) you defined in your admin/structure pages (/yourSiteName/admin/conversations/yourSite/structure), unless the optional parameter "name" is provided.

The parameter "name" is optional. If provided, then the javascript named in the parameter will be returned, instead of the default defined in the structure pages. The value of this parameter must be the name of a javascript that has been defined in the javascript editor in the admin interface. (This parameter allows you to use any number of javascripts into a page/template.)

The parameter "language" is optional. If not provided, then the default "JavaScript" is used. Use this attribute if your script requires a specific version of JavaScript, such as JavaScript1.1, or is written in another scripting language like VBScript.

The parameter "type" is optional. If not provided, then the default "text/javascript" is used. This parameter allows you to create a technically complete script tag, and is especially important if your script is in a language other than JavaScript (such as VBScript, or tclscript).

The parameter "embed" is optional. If not provided, then the default value "true" is used. True indicates that the page will have the script embedded in it, thus forcing the browsers to download the script text as part of every page they request. False indicates that your page will link to the script (similar to how images are linked to), which will then be served separately from the page and cached by the browser.

The parameter "extension" is optional. If not provided, then the default ".js" is used, which will indicate to the browser and to Conversant that the script language is javascript. This parameter is only needed if the embed parameter is "false", AND if the language is anything other than javascript (use ".vbs" for VBScript, for example).

<!--#requireJavascript name="jsname" language="JavaScript" embed="true/false"-->

This macro can be used anywhere in any template, message or resource. It doesn't actually insert anything into your page, but instead causes the javascript macro to link to an additional javascript.

The parameters for this macro are identical to those for the javascript macro.

Some pages on your site may require additional javascripts that you don't use on the rest of your site. For example, you may have a particular script which is only needed on your Advanced Query Page. You could put a javascript macro in the page's wrapper template, but <script> tags are only supposed to appear in the HTML <head> section.

You could create a new "full page template" just for the search page, but then if you redesign part of your site you have to make the same changes in both page templates.

This macro solves problems like that. You can put it anywhere (such as in your AQP's wrapper template), and the javascript macro will link to the script you specify (in additional to whatever it was already going to link to).

Use this macro as often as you like, to link to as many different scripts as you need. It will only link to a particular script one time (so it's ok to ask for the same script from two different templates).

<!--#bodyTag-->

Replaced with the html body tag of the page. It will have the attributes you defined in the MainResponder Interface plugin preferences page:

siteURL/admin
/conversations
/siteName /preferences$conversation=siteName&plugin=mainResponder%20Interface

<!--#navbar msgNum="n" template="s"-->

Replaced with the navigation bar, if the following conditions are true:

  1. the navigation bar is enabled in the Default DG plugin preferences page
  2. the number of the message to use as contents for the navigation bar is set in the Default DG plugin preferences page
  3. this message exists

This can be set from:

siteURL/admin
/conversations
/siteName /preferences$conversation=siteName&plugin=Default%20DG

Additionally, the navbar macro can take two optional parameters, "msgNum" and "template". This allows you to use several navbars at once in your site, with calls like <!--#navbar msgNum="3" template="navbar"-->.

<!--#bookmarks-->

Replaced by the user's bookmarks box, if the Bookmarks plugin is enabled.
See yourSite/members/settings/preferences$plugin=Bookmarks.

<!--#member-->

Replaced with with the email address of the current user. Returns "guest" if the user is not logged in. (It's useful for letting the user know what account he or she is currently logged in under.)

(It's safe to use the email address here, because it's only showing the current user's email, nobody else's.

Live example: "guest" (should show your email address, or the word 'guest')

<!--#memberLinks-->

Replaced with one of the two states of the Members box, as defined in the templates located in the MainResponder Interface preferences. See http://support.free-conversant.com/188 for more details.

<!--#memberName link="true/false"-->

Replaced with the current user's full name, if the user is logged in. If the user has not logged in, "guest" is used instead. If the user is logged in but has not provided a full name, then the email address is used instead.

If the link attribute is "true" (versus false or not provided), AND if the user has logged in, then the user's name will be linked the email address.

(It's safe to use the email address here, because it's only showing the current user's email, nobody else's.

Live example: "guest" (should show your full name with a link to your email, or the word 'guest' if you haven't logged in)

<!--#searchField template="name" action="URL_or_Path"-->

Replaced with the basic search form. You may edit the searchField template in this page:

siteURL/admin
/conversations
/siteName /preferences$conversation=siteName&plugin=Default%20DG


The parameter "template" is optional. If provided, then the named template will be used instead of the template defined in the conversation's preferences. This allows your conversation to have any number of different forms created with the #searchField macro.

The parameter "action" is optional. If provided, it is used as the "action" attribute of the form tag. If not provided, then the URL of the first "Query Page" found on your site is used for the "action" attribute of the form tag.

<!--#copyLine-->

Replaced with the Conversant copyright line. You may put it anywhere in your template, but if you don't, and if you own a Free-Conversant site, the copyright line will be added at the bottom of the page.

<!--#createdTime-->

Replaced with the creation date and time of the page, converted to the reader's timezone if this is a member.

<!--#modifiedTime-->

Replaced with the modification date and time of the page, converted to the reader's timezone if this is a member.

<!--#insertMsg(N, adminLinks)-->

<!--#insertMsg msgNum="N" adminLink="true/false" conversation="conv name"-->

Replaced with the contents of the message whose number is N (see this page for more info).

The adminLinks parameter must be either "true" or "false", and determines if the adminLinks should be shown to site admins when they view the page. See the feature docs for more info on how this works.

The conversation parameter, which is only available in the second form of the macro, allows you to specify a separate conversation to pull the message from. The conversation must be in the same 'zone' as the conversation that is rendering the message.

<!--#insertClip msg="N" length="L" adminLinks="true/false"-->

Similar to insertMsg, but it only uses approximately the first L content characters of message N. A content character is one which is not part of an HTML tag, nor is it part of another macro.

L is approximate because insertClip will always return the entire word that contains character L. So, if L is actually 15 (length="15"), and the 15th character of the message being inserted falls in the middle of the word "Conversant", the clipping will end with the entire word, "Conversant".

The adminLinks parameter is a boolean to determine if the adminLinks should be shown to admins when they view the page. See the feature docs for more info on how this works.

InsertClip will close any HTML tags that are left open in the clipping text. So, for example, if the clipping text from the message contains <b>, the closing </b> tag will be added to the end before the macro is replaced.

<!--#insertStrippedClip msg="N" length="L" adminLinks="true/false"-->

Similar to insertClip, except that all HTML tags are stripped out of the result.

The adminLinks parameter is a boolean to determine if the adminLinks should be shown to admins when they view the page. See the feature docs for more info on how this works.

<!--#randomizer msgNum="N" adminLinks="true/false"-->

Also supported: <!--#randomizer( "N", "adminLinks" )-->

The parameter 'N' is a message number.

This macro is replaced with a randomly-chosen line from the message specified by N (see this page for more information).

The adminLinks parameter is a boolean ("true" or "false") to determine if the Edit and View links should be shown to admins when they view the page. See the feature docs for more info on how this works.

<!--#enclosure filename="f" msgNum="N"-->

This simple macro allows you to insert a variety of enclosures for display in a message. See this How-To for more informations.

<!--#conversantBadge-->

Replaced with the "Site managed with Conversant" badge:
Site Managed with Conversant

<!--#spacer width="n" height="n"-->

Replaced with an image tag that inserts into the page an invisible image whose width and height are defined by the parameters (each of them defaulting to 1). See this message for more information.
View in DG