CMS Help

This help file is intended for the website developer to aid with integration and use of the CMS.

 

Themes & Templates

A theme is a collection of files and folders used by the CMS to control the visual look and layout of the website. Theme files typically consist of html, css and image files just like any website. The html files in an active theme folder are used as page templates by the CMS to display any number of pages.

At the very least a theme should consist of at least one page template file that is named default.php (or .htm/.html). This default page template is used for displaying all pages unless another page template is specified when adding/modifying a category/product etc. in the admin control panel. A theme might also include other page template files, images, style sheets, item template files, custom include files etc.

When creating a new theme it is recommended to copy the existing default theme folder and rename it. This will ensure all required style sheets and images necessary for the CMS to display properly are present in your new theme. If required images and stylesheets do not exist in a custom theme folder then the ones in the default folder are used instead, therefore files in the default theme folder should not be modified or removed as they are used as defaults if a custom theme is missing a critical file.

If you are logged in as admin then new or modified page template files will be imported automatically from the active theme folder as long as Dev Mode is enabled in the admin area. If Dev Mode is disabled you will need to manually update page templates by going to the Theme page in the admin area.

 

Page Template Tags

Special tags can be used in page templates to display dynamic content from the CMS; eg. <div>{cms-page-content}</div>

Special tags can optionally be placed within HTML comment tags eg. <div><!--{cms-page-content}--></div>

Most tags can also be used as class names (without the curly brackets); eg. <div class="cms-page-content">placeholder content</div>

When used as a class name the CMS will replace any existing content in the web page element. This allows you to keep placeholder content in your page template designs that will be replaced by the CMS. Whereas using the special tag with curly brackets will insert directly into content without replacing anything. It is important that there are no broken HTML tags in template files especially when using template tags as class names as content replacement can exacerbate any issues.

All tags names should be lower case. Some tags allow or require extra parameters which are highlighted below with [square brackets].

{cms-page-content} and {cms-page-content-[myText]}
Defines where page content from the CMS will be displayed. You can also add additional content areas by appending extra text eg. {cms-page-content-1}, {cms-page-content-2}, {cms-page-content-mytext} etc.

If the page is a category the selected category display file in the theme will determine how the content and any listing items are displayed.

{cms-page-title}
The page title is usualy displayed via the {cms-page-content} tag however this tag can be used to display the title elsewhere on the page.

{cms-category-items-content}
Displays category item listings. Usualy item listings are displayed via the {cms-page-content} tag however this tag can be used as an alternative.

{cms-category-page-nav}
Displays category pagination links. Usualy pagination is displayed via the {cms-page-content} tag however this tag can be used as an alternative.

{cms-category-total-item-count}
Displays total number of viewable items in the category. Usualy displayed via the {cms-page-content} tag however this tag can be used as an alternative.

{cms-category-page_num}
Displays current page number of the category. Usualy displayed via the {cms-page-content} tag however this tag can be used as an alternative.

{cms-contact-form}
Defines where a contact form will be displayed.

{cms-account-menu}
Displays the user account menu with login and register links.

{cms-search}
Displays the search box.

{cms-cart-menu}
Displays the shopping cart qty, total and checkout links.

{cms-cart-qty}
Displays number of items in the shopping cart. Put tag in a div or span with class name cms-cart-qty to refresh with add-to-cart-popup or just use class name instead of tag.

{cms-cart-total}
Displays total price of all items in the shopping cart (takes any discounts into account). Put tag in a div or span with class name cms-cart-total to refresh with add-to-cart-popup or just use class name instead of tag.

{cms-breadcrumbs}
Displays breadcrumb navigation.

{cms-recently-viewed}
Display recently viewed items.

{cms-terms-content}
Displays the terms and conditions as configured in admin.

Page Links & URLs

When linking to pages in your website you can use absolute URLs or you can use the template tags below to let the CMS automatically insert the appropriate URL. For example when linking to your website's home page you could use it's absolute URL eg. http://www.mysite.com/ or a template tag eg. {cms-site-url}. Using template tags for URLs is recommended as these URLs automatically take into account the domain and CMS folder location (as set on the admin config page) so they'll all work automatically even if the CMS is moved to a new folder or domain.

Make sure the curly brackets {} in template tags are not converted to special characters in the HTML source code.

{cms-url}
Insert the URL to the CMS main index.php file, this is normally the homepage URL eg. http://www.mysite.com/

{cms-root-url}
Insert the URL to the cms root directory eg. http://www.mysite.com/cms/

{cms-site-url}
Insert the website URL as set in admin config settings, this is normally the homepage URL eg. http://www.mysite.com/

{cms-theme-url}
Insert the url to the active theme directory. eg. http://www.mysite.com/cms/themes/mytheme/

{cms-category-url-[catId]}
Insert the URL of the specified category. Category 0 is normally the homepage URL.

{cms-article-url-[articleId]}
Insert the URL of the specified news article.

{cms-product-url-[productId]}
Insert the URL of the specified product.

{cms-login-url}
Insert the URL for login page.

{cms-register-url}
Insert the URL for register new user account page.

{cms-myaccount-url}
Insert the URL for myaccount page.

{cms-cart-url}
Insert the URL for login page.

{cms-checkout-url}
Insert the URL for checkout page (if cart is empty will fall back to cart page).

{cms-paynow-url}
Insert the URL for paynow page (this page is shown automatically after the order confirmation page).

{cms-current-page-url}
Inserts the URL for the page currently being viewed.

Nav Menus

{cms-navmenu-[id]-[layout]}
displays a navmenu specified by id with optional layout. Menu apperance and html output determined by the nav menu's content template.

{cms-menu-accordian-[catId]-[effect]}
display a dynamic accordian menu starting from the specified category id, set accordian effect parameter to 0 or 1 (noaacordian keep multiple sub menus expanded). Modify plugins/accordian_menu/styles.css to change menu colours and sizes.

{cms-menu-treeview-[catId]}
display a dynamic treeview menu starting from the specified parent category id.

Product Tags

If you use the {cms-page-content} tag in your template the CMS will automatically generate a product detail page with all the product information, images and buttons. If you need to add particular product information to parts of your template you can also use the tags below.

{cms-product-id}
display id of currently viewed product.

{cms-product-name} / {cms-product-name-[id]}
display name of currently viewed product or that of specified product id.

{cms-product-code} / {cms-product-code-[id]}
display code of currently viewed product or that of specified product id.

{cms-product-price} / {cms-product-price-[id]}
display price of currently viewed product or that of specified product id. Does not display additional price text, only amount and currency symbol eg. €10.00

{cms-product-pricetrim} / {cms-product-pricetrim-[id]}
display price of currently viewed product or that of specified product id. Does not display additional price text, only amount with trailing zeroes trimmed and currency symbol eg. €10

{cms-product-pricedisplay} / {cms-product-pricedisplay-[id]}
display price of currently viewed product or that of specified product id. Does display any discount text and amount with trailing zeroes trimmed and currency symbol eg. €10

{cms-product-pricedisplaytrim} / {cms-product-pricedisplaytrim-[id]}
display price of currently viewed product or that of specified product id. Does display any discount text and amount with trailing zeroes trimmed and currency symbol eg. €10

{cms-product-description} / {cms-product-description-[id]}
display description of currently viewed product or that of specified product id.

{cms-product-gallery} / {cms-product-gallery-[id]}
display image gallery of currently viewed product or that of specified product id.

{cms-product-attr_myattribute} / {cms-product-attr_myattribute-[id]}
display an attribute of currently viewed product or that of specified product id. Replace myattribute with the name of an actual product attribute.

{cms-product-myval} / {cms-product-myval-[id]}
display a value of currently viewed product or that of specified product id. Where myval is a text string or number value. Cannot be used as a class name.

{cms-related-products}
display related products of currently viewed product.

Other Tags

{cms-jquery}
Place anywhere to instruct the CMS to replace any jquery lines in the template with the CMS's default jquery file plugins/jquery/jquery.js (use HTML comment tags if placed in the head section)

{cms-jquery-selectboxes}
use this tag to change normal select boxes in forms into advanced jquery select boxes

{cms-inc-[myFilename]}
This is an advanced tag that allows you to include a custom php file in your template where [myFilename] is the name of the file *without* the file extension. File must be a .php file and needs to be in themes/[theme_name]/includes/

{cms-login-warnings}
This tag will output any login warnings generated by the CMS.

{cms-register-warnings}
This tag will output any user registration warnings generated by the CMS.

{cms-contact-warnings}
This tag will output any contact form warnings generated by the CMS.

{cms-subscribe-warnings}
This tag will output any newsletter subscribe warnings generated by the CMS.

{cms-blank}
This tag is simply replaced with nothing (a blank string). For example you can put this at the start of a url in a src value to make sure the update template process doesn't change it.

<!--{cms-page-meta}-->
Page meta code for the CMS is automatically placed at the end of the <head> section. Only use this tag if you want to position it manually. Must be used with HTML comment tags for placement in the head section.

Template Tags for Category Images

The following tags are used in conjunction with category images. The names are interchangeable so for example you could have a slider and a gallery using the same name and therefore sharing the same category images. This is useful if you have a slider on a desktop template but want to have a gallery instead on the mobile page template.

{cms-slider-[mySlidername]-[catId]-[width]-[height]}
To add an image slider to a page use this special tag. The image slider will pull images from the specified category id or the current one if no id is specified.

{cms-image-[myImagename]-[width]-[height]-[urlOnly]}
This tag can be used to allow adding and changing of images to specific places on the page template. Assign images by modifying the category and seleting the appropriate "Assign to" name. Multiple of these tags can be added with different names if needed. If urlonly is set to 1 it will output only the image url.

{cms-gallery-[myGalleryname]-[catId]-[tnWidth]-[tnHeight]-[cols]}
This tag can be used to display a gallery of images on the page template. The gallery will pull images from the specified category id or the current one if no id is specified. Multiple of these tags can be added with different names if needed.

Other Template Tags

{cms-time-year}
Displays the current year

 

Custom Login/Register Forms

To customise the HTML for the login and registration forms the following files in the active theme directory can be edited..

It is also possible to use login and registration forms that are part of a template. To do so you need to ensure the appropriate names below are used on the input fields.

For login forms..

The template tag {cms-current-page-url} can be used in the form action and the template tag {cms-login-warnings} placed where you want to display login form warnings.

For registration forms..

The template tag {cms-current-page-url} can be used in the form action and the template tag {cms-register-warnings} placed where you want to display register form warnings.

Custom Contact Forms

To customise the HTML for the contact form the following file in the active theme directory can be edited..

Or to integrate a contact form that is part of a page template the appropriate input elements should use the following name attributes:

The template tag {cms-current-page-url} can be used in the form action and the template tag {cms-contact-warnings} placed where you want to display contact form warnings.

The template tag {cms-form-input-name} can be used to display whatever name was entered into the form and name can be substituted for other input names eg. email, phone, message.

 

Custom Subscription Forms

To customise the HTML for the newsletter subscription form the following file in the active theme directory can be edited..

It is also possible to use a subscription form that is part of a template. In this situation you will need to ensure the appropriate names below are used on the input fields.

The template tag {cms-current-page-url} can be used in the form action and the template tag {cms-subscribe-warnings} placed where you want to display newsletter subscribe form warnings.

 

Displaying a Category

Categories are used to display listings which can be products, news items or user listings. A category can also be used for a standard webpage without listings. You can display a category and it's listings on any webpage by using the PHP code below. Remember to also include the required pieces of code above.


$category = new Category();
// on the next line $category_id is the id of the category you want to display eg. '123456789'
if ($category->getData($category_id)){
// You can optionally override the category settings, for example...
$category->heading_visible = 0; // hide/show heading 0/1
$category->listings_visible = 1; // hide/show listings 0/1
$category->ctemplate = 'products_sidebar'; // use a different content template
$category->cols = 2; // set the number of columns
$category->rows = 1; // set the number of rows
$category->tnx = 2; // set the width of thumbnail images
$category->tny = 2; // set the height of thumnail images
$output = displayCategory($category,$page_number,$search,$specific_items,$layout); // only $category is required
echo $output['content']['main']; // ['content']['main'] is the main content area, other custom content areas in the category can be output too
}

$category_id = the id of the category that you want to display
$page_number = display a categories sub page
$search = null or an array containing search keys and values
special reserved search keys listed below. Specifying custom search keys will use exact match/case insensitive, end a search key with "_lax" for a non exact search/contains search value eg. search[location_lax]=rela will match ireland. To omit from the search process append omit_ eg. search[omit_this] or leave the value blank eg. search[this]=""
'phrase' = search items using a general search phrase, typically for searching item ids, name, keywords - specify negative keywords with a preceding hyphen eg -keyword or perform an exact match with square brackets eg. [exact keyphrase]
'price' = display only items within a specified price range eg. 0,200 for 0 to 200 - or enter a single price to display listings greater or equal to the specified price
$specific_items = provide an array of item ids to display specific items regardless of category or search
$layout = $layout can be used in the category template file to provide different layouts using conditional statements. It can be used as an alternative to changing content template, for example to output the same listings more than once on the same page eg. a 'grid' and 'list' layout that has a show/hide toggle.

Special Category Tags

When adding or modifying a category you can use the following special tags in category descriptions.

Advanced Category Search Filter

A category by default will display only items that are assigned to it. The advanced search filter allows you to override this behaviour and control what items are displayed in the category. Search filters should be separeated with a colon : character.

For example to show items from other categories you need to specify what categories to search otherwise it will by default only search for items within the actual category.

cat=123456789,987654321:phrase=mykeyword:sort=priority

or if you want to disregard category selections altogether..

cat=:phrase=mykeyword

Reserved names are:

Other names can be used in custom scenarios eg. bedrooms=3,location=nass etc.

Category Search, Attribute Filters & Sorting

A category url will contain "search" when the category is displaying search results. Note the search criteria is stored in the session but only "search" is shown in the url.

Attribute filters are a type of search so only "search" will be shown in the URL if attribute filters have been applied.

When adding attribute filter checkboxes or radio buttons the name should be "attr_filter[color]" where color is the attribute id and the value should be what you want to match eg. "red". Both the attribute id and value are case insensitive. So this example would only show items that have an attribute called color that is set to red. Use a button with the name "apply_attr_filter" to submit filters. Use a button with the name "clear_attr_filter" to clear filters.

A category url contains "sort" when the category items are being sorted. eg. sort=price or sort=price_r

Advanced PHP Variables

The following variables can be used in certain php files used by the cms to insert custom html code. eg. product_page.php article_page.php

$page->meta - for inserting html code just before the closing </head> tag
$page->body_start - for inserting html code just after the opening <body> tag
$page->body_end - for inserting html code just before the closing </body> tag

Downloads

You can use the cms to create protected download links that only registered users can download. eg http://www.mywebsite.com/?download=filename.jpg

Images

When an image is added to a product it is stored in the folder for that particular product along with the product details file. If the uploaded image is particularily big it will be resized to a reasonable size. These main image files are not displayed directly on web pages but are instead used to generate copied image files at varying sizes. These copied images are cached in the images folder in the cms root folder. This means when you do a backup only the main image files under the data directory are backed up which keeps backup sizes smaller.

The root images folder is for dynamically created images like product thumbnails. It is essentially an image cache.

Watermarking Images

Images displayed on listings such as news articles and products can be watermarked by enabling the various watermark settings in the sys/config.php file. The watermark image file must be a png file named watermark.png and uploaded into the images directory for the active theme eg. themes/mytheme/images/watermark.png - If the file is not found it will by default try to use themes/default/images/watermark.png - it is recommended to use a png with alpha transparency for best effect.

Backups

Backups made through the cms admin area include only the cms data directory and do not include theme files. As theme files are created on your computer you should always ensure you keep a local backup of them. The cms data backup requires the php function shell_exec to be enabled on the server.

If the default backup method does not work you can try switching to alternate method in sys/config.php

Backing up will create a compressed tar file of the cms data directory.

You can also manually download the cms data directory via an ftp client although the process will be slower. To restore a manually downloaded data directory use a program like 7zip to make a tar file of the downloaded data directory and then compress it with gzip. Upload this new file to the cms/backup directory and you will then be able to restore it as normal from the backup page in cms admin area.

CronJobs

A cron job can be setup on your server so the cms will check automatically for expired subscriptions and send queued emails in the mailer.

eg. wget -q http://www.mysite.com/cms/scripts/cron.php

Updating the CMS

If you are updating to a new version of the CMS you should bear in mind any file modifications you may have made to the CMS files. Check also for any changes in the default theme which may need to be applied to custom theme(s). Make sure to run a backup and download it to your computer before updating the CMS.

Please see the CMS update guide for more information.