Token Reference Guide

content

The content token specifies an area where the user can add, edit, or delete modules.

Example use:

<@content name="BodyContent" /@>

or

<@content name="Slideshow" canadd="false" /@>

Available attributes:

Attribute Description
name*

The name of the content area.  Note, no 2 content areas on the same page may have the same name.  Also note, you should include a content area named "BodyContent" in your main content area on each template.

canadd

Set this to "false" if you wish to disallow the adding of modules to this particular content area.  This can be helpful, for example, with a particular content area dedicated to a Photo Slideshow.  Note: users can still delete modules, and if they have deleted all modules from this content area, they will still be allowed to add one module.  Default:  true

global

Set this to "true" and all modules in this content area will be shared across all pages with this specific content area name.  This can be helpful in setting up sidebar content, for example.  Default:  false

 

page

The page token displays information about the current page.

Example use:

< @page field="mainmenuname" /@ >

Available attributes:

AttributeDescription
field*

The name of the field you wish to show.  Use "name" to show the page name and "url" to show the url for this page. Use "layout" to display the name of the html layout file used by that page. You can also use "mainmenuname" to show the parent page name and "mainmenuurl" to show the url for the parent page.

 

site

The site token displays information about your site.

Example use:

<@site field="name" /@>

Available attributes:

Attribute Description
field*

The name of the field you wish to show.  Use "name" to show your site's name, "url" to show the short url (folder) for your site, and "fullurl" to show the final url of your site.

 

menu

The menu token displays a list of pages on your site (as a 'ul'), based on your sitemap.

Example use:

 

<@menu name="mainmenu" /@>

or

<@menu name="sidenav" showchildren="true" hideparent="true" /@>

Available attributes:

AttributeDescription
name*

The name of the menu - is also added as a CSS class on the ul.  Note: There are few reserved names for specific menus: "mainmenu" is a reserved menu name that displays the pages on your site's main menu. 

showall

Set this to "true" to show all pages on your site in this menu.  You could then use CSS to hide pages if you wanted.  Default:  false

showchildren

Set this to "true" to show child pages on this menu.  Default:  false

showparent

Set this to "true" to show the parent page on this menu.  Default:  false

hidehome

Set this to "true" to hide your home page on this menu.  Default:  false

 

include

The include token allows you to include other files into your template file.  You can use other tokens in your include file (except the include token).  If you are using a "content" token, be sure to set global="true".

Example use:

<@include path="include/header.html" /@>

Available attributes:

Attribute Description
path*

The path to your include file.  Note the include file must have the .html extension - however it does not need to be a full html file - this means you don't need to specify a doctype, etc. 

 

form

The form token allows you to output an email subscription form or a website search form.

Example use:

or

Available attributes:

AttributeDescription
type*

Type of form to display, can be either "email" or "search"

searchtype

For "search" forms only, allows you to choose a specific type of search.  Search types are "all" (search the whole site: pages, blogs, events, etc.), "author" (search only authors of blogs on your site), "tag" (search only tags within your site), "item" (for searching Convergence Item-Lists - this will only search favorited item-lists), or "product" (for Convergence Commerce sites, search the products on your site).  Default:  all

inputtext

Set the text that appears in the form input box (before a user clicks to type).  Default:  email address | search

buttontext

Set the text that appears on the button for the form.  Default:  Subscribe | Search

labeltext

Set the text that appears as a label before the form input.  Default:  ""

showname

Set this to "true" for Email forms to capture the visitor's Name as well as Email Address. Default: "false"

thankyou

Set this to the text you would like to appear after the form is submitted.  thankyou="Thank you! We will be in touch soon!"

 

date

The date token prints out the current date.

Example use:

<@date format="Y" /@>

Available attributes:

Attribute Description
format

Uses the php date function to format the date - for date formatting options, read more here. Default: Y

 

breadcrumb

The breadcrumb token allows you to display a breadcrumb navigation; essentially a list of links to parent pages and the current page. This enables a user to easily navigate back up the sitemap.

Example use:

<@breadcrumb type="page" separator="/" /@>

Available attributes:

Attribute Description
type

The type of breadcrumb you are displaying, can be either "page", "product", or "category". For standard sites, use "page", but for Convergence Commerce stores, you'll want "product" and/or "category".  Default:  page

separator

The symbol that separates the list of links.  Default:  >

 

item

The item token is for sites with Convergence Item Lists enabled.  This token allows you to customize your item template page, placing the fields from your item list exactly where you want them.

Example use:

or

Available attributes:

AttributeDescription
field*

The name of the field you wish to show.  Look below for examples.

field="name"

The name of this item.

field="slug"

The slug (or url identifier) of this item.

field="id"

The unique numerical id for this item.

field="YOURFIELD"

Where YOURFIELD is the slug of a field you've created.  So if you created an Item List of movies and had a field named "Director" (with a field slug of "director") you could set a token with the attribute field="director" to show the name of a movie's director.

width

If the field you entered is an image, this specifies the width of the image in pixels.  Default: 300

height

If the field you entered is an image, this specifies the height of the image in pixels.  Default: 300

pathonly

If the field you entered is an image or a file, setting this to true will give you a relative path to the image or file. Note that by default, images are rendered with an img tag and files are shown as a link to the file.  Default: false

linktext

If the field you entered is a file, use this attribute to set the text for the link to the file.  Default: the name of the field in the ITEM LIST settings

 

product

The product token is for sites with E-Commerce enabled.  This token allows you to customize your product template page, placing the fields for your product exactly where you want them.

Example use:


/templates/photos/screen-shot-2012-01-09-at-1.28.51-pm.png

or

 

Available attributes:

AttributeDescription
field*

The name of the field you wish to show.  Look below for examples. 

field="edit"

Creates a module bar that will allow a logged-in user to edit the product (without having to go to the Products backend). This bar will not appear for non-logged-in users.

field="name"

The name of this product.

field="id"

The unique numerical id for this product.

field="link"

The link for this product.

field="description"

The description for this product.

field="image"

The main image for this product. Note: You can use the width and height attributes to set this image's dimensions.

field="images"

The main image for this product and this product's other images as thumbnails. These images are automatically added to a slideshow that allows you to click each thumbnail to see it as a large image. Note: You can use the width and height attributes to set this image's dimensions. You can also set the thumbwidth and thumbheight attributes to set the thumbnail dimensions.

field="price"

The price for the first variant of this product. Note: if there are multiple variants, this value will automatically update when the user chooses a different variant.

field="sku"

The SKU for the first variant of this product. Note: if there are multiple variants, this value will automatically update when the user chooses a different variant.

field="weight"

The weight for the first variant of this product. Note: if there are multiple variants, this value will automatically update when the user chooses a different variant.

field="quantity"

An input box to allow the user to choose a quantity of this product to add to his/her cart.

field="buy"

A link to buy this product (adds the product to the user's cart). This link will automatically be disabled if the product cannot be purchased, if there is no quantity available, or if the user has not specified a correct product variant.  You can use the attribute buttontext to specify the text for this link.

field="buyqty"

Same as above, but also includes a quantity input box.

field="buytable"

Same as above, but outputs a table with rows for each of the variants for this product. In this table, each variant to plug into the admin will show up in the table. Once you style the table, it becomes an easy way to show off lots of product options.

quantitytext

Use with field="buyqty" or field="buytable" to show what text you want to use for "quantity". For example: quantitytext="QTY"

buttontext

Use with field="buy" or field="buytable" to show what text you want to use for your button. For example, buttontext="Buy Now"

field="outofstock"

A message that appears if this product is out of stock. You can use the text attribute to specify the text of the displayed message.

field="new"

A message that appears if this product is new. You can use the text attribute to specify the text of the displayed message.

field="sale"

A message that appears if this product is on sale. You can use the text attribute to specify the text of the displayed message.

field="featured"

A message that appears if this product is featured. You can use the text attribute to specify the text of the displayed message.

field="reviews"

A list of reviews for this product as well as a form to write a product review.

field="numreviews"

The number of reviews of this product.

field="rating"

The average rating (shown out of five stars) based on reviews of this product.

field="recommend"

The percentage value of people who have recommended this product based on reviews of this product.

field="customfield"

The value a product's custom field. You must use the attribute customfield to specify which custom field you are displaying.

field="customfieldfull"

The field name AND the value a product's custom field. You must use the attribute customfield to specify which custom field you are displaying.

field="customfieldlist"

A list of all the field names AND the values for a product's custom fields.

customfield

Used with field="customfield", allows you to specify the slug of the custom field you want to display.

width

If the field you entered is an image, this specifies the width of the image in pixels.  Default: 300

height

If the field you entered is an image, this specifies the height of the image in pixels.  Default: 300

thumbwidth

If the field you entered is "images", this specifies the width of the thumbnail images in pixels.  Default: 50

thumbheight

If the field you entered is "images", this specifies the height of the thumbnail images in pixels.  Default: 50

customfieldcategory

Use with field="buy" or field="buyqty" or field="buytable". Enter the slug of a Custom Field on this product where the value of that Custom Field will be used as this product's category in the cart

 

category

The category token is for sites with E-Commerce enabled.  This token allows you to customize your category template page, placing the fields for your category exactly where you want them.

Example use:

<@category field=\"name\" /@>

or

<@category field=\"productlist\" thumbwidth=\"100\" thumbheight=\"80\" showsubcatnames=\"false\" limit=\"16\" /@>

Available attributes:

AttributeDescription
field*

The name of the field you wish to show.  Look below for examples.

field="name"

The name of this category.

field="id"

The unique numerical id for this category.

field="link"

The link for this category.

field="description"

The description for this category.

field="image"

The main image for this category. Note: You can use the width and height attributes to set this image's dimensions.

field="productlist"

The main image for this product and this product's other images as thumbnails. These images are automatically added to a slideshow that allows you to click each thumbnail to see it as a large image. Note: You can use the width and height attributes to set this image's dimensions. You can also set the thumbwidth and thumbheight attributes to set the thumbnail dimensions.

thumbwidth

Used with field="productlist", this specifies the width of the thumbnail images in pixels.  Default: 100

thumbheight

Used with field="productlist", this specifies the height of the thumbnail images in pixels.  Default: 100

showinfo

Used with field="productlist", shows product names and prices in the product list. Set to "false" hide this product info.  Default: true 

showsubcatnames

Used with field="productlist", shows the names of any subcategories within this category. Set this to "false" to hide these names.  Default: true

limit

Used with field="productlist", this specifies the number of products to display.

 

cart

The cart token is only for sites with E-Commerce enabled and displays information about the user's cart.

Example use:

<@cart field="info" /@>

 

Available attributes:

AttributeDescription
field*

The name of the field you wish to show.  Use "info" to show the full cart info, "shortinfo" to show just the cart link and quantity of products, "link" for the link to the cart, "quantity" for the auto-updating quantity value of items in the cart, and "price" for the auto-updating total price of all items in the cart.

 

user

The user token is for sites with users enabled and displays information about the user. This is the "profile" page that users see when they login to their account (the Page URL's for these pages begin with "profile-"). Note that just as with Item Lists, you can create a different User Layout file for each User Type.

Examples:


Available attributes:

AttributeDescription
field*

The name of the field you wish to show.  Look below for examples.

field="login"

When the user is logged out, the login form for the account. NOTE: This must be placed on the Account Layout File. The account page can be viewed at: http://YOURSITE.convergencecms.co/account

canregister

Used with field="login", can be true or false, this specifies whether a user can use the login form to register for a new account.  Default: false

usertype

Used with field="login" and canregister="true", this specifies the User Type for which the user can register a new account. Use the slug of the User Type like: usertype="wholesale"  Default: none

field="text"

Displays text, can display different text depending on whether the user is logged in or logged out.  Useful for link text, headers, etc.

whenloggedin

Used with field="text", specifies the text to show when the user is logged in. whenloggedin="You are logged in."

whenloggedout

Used with field="text", specifies the text to show when the user is logged out. Like: whenloggedout="Log back in."

field="menu"

When the user is logged in, shows a menu that includes links to Personal Info, Order History, Subscriptions, any pages they have access to (setup with User Types), any Item Lists they can update (setup with User Types), their Login Status, and a link to Logout. To hide one of the sections on a users menu see below.

personal

Used with field="menu", set personal="false" to hide the link to their Personal Info. Or set personal="My Profile" or any other phrase to customize the text that appears in the menu.

orders

Used with field="menu", set orders="false" to hide the link to their Order History. Or set orders="My Orders" or any other phrase to customize the text that appears in the menu.

billing

Used with field="menu", set billing="false" to hide the link to their Billing info. Or set billing="My Payment Option" or any other phrase to customize the text that appears in the menu.

subscriptions

Used with field="menu", set subscriptions="false" to hide the link to their Subscriptions. Or set subscriptions="My Recurring Donations" or any other phrase to customize the text that appears in the menu.

item-lists

Used with field="menu", set item-lists="false" to hide the link to their Item Lists.

status

Used with field="menu", set status="false" to hide their Login Status.

logout

Used with field="menu", set logout="false" to hide the logout link.

default

Used with field="menu", set default="personal" to have the user land on their Personal Info Page when they first login to their Account.

field="personal"

When the user is logged in, shows their Personal Info (name, address) as well as a link to a form that lets the user edit their Personal Info.

field="orders"

On sites with E-commerce, when the user is logged in, shows a table of their order history.

field="billing"

On sites with E-commerce, when the user is logged in, shows their payment method and a link to update it.

field="subscriptions"

On sites with E-commerce, when the user is logged in, shows a table of their current subscriptions. Add canmodify="true" if they can adjust the amount of their subscription (as in a Donation).

field="item-lists"

Outputs the Users' Item Lists (only shows the current one that the User selects from the menu) - with the option to view/edit/add new Items. Alternatively, you can use the slug of an Item List in field="" to specify where that particular Item List will be rendered. Like: field="breakfast"

field="json"

Returns a Javascript variable called "userjson" that contains all of the information on the user in JSON format. You must surround this token with script tags to use it.

field="logout"

When the user is logged in, a logout link.

loggedinuser

Used with all of the fields below, set loggedinuser="true" to get the logged-in user's profile information.

field="id"

Shows the User's ID.

field="name"

Shows the User's name.

field="email"

Shows the User's e-mail.

field="slug"

Shows the User's slug.

field="company"

Shows the User's company.

field="address"

Shows the User's address.

field="address2"

Shows the User's address (2nd line).

field="city"

Shows the User's city.

field="state"

Shows the User's state.

field="zip"

Shows the User's postal code.

field="country"

Shows the User's country.

field="phone"

Shows the User's phone number.

field="image"

Shows the User's profile photo - can also take a width and height. Specify pathonly="true" if you only want the path to the image.