CMS Help

This help file is intended for the website developer to aid with integration and use of the CMS, in particular when working with themes and templates. For additional help on how to use the CMS please consult the user guide pdf or use the context sensitive Help from the header menu in the CMS admin area.

 

Themes & Templates

A theme is a collection of files used by the CMS to control the visual look and layout of the website. A theme consists of HTML, CSS and image files just like any website. HTML files in the active theme are used as page templates by the CMS to display any number of dynamically created pages on the front-end of the website.

At the very least a theme should consist of at least one page template file that is named default.html (or .htm). 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 area.

A theme also includes PHP files that control how content will be output by the CMS and displayed on the website. These PHP files can be found in the /includes folder of the theme. If this folder or any required file within the theme does not exist then the CMS will atttmpt to fall back to a file of the same name and relative location in the /default theme folder. Therefore it is recommended to duplicate the default theme folder and rename it for any new custom themes you want to create, this way you can customise and modify files in each new theme independently without changing any files in the default theme.

After uploading files to the currently active theme you will need to refresh/update the theme in the CMS admin area. To do this go to the Theme page in the admin area and click the "Update Theme" button. Clicking the "Change Theme" button will change the active theme and update it too automatically. If Dev Mode is enabled you can also update the active theme when viewing a page on the front-end by clicking the refresh icon in the admin panel at the top of the page. It is especially useful to keep Dev Mode enabled when working on the theme. Dev Mode can be toggled from the header menu in the admin area. When editing files such as page templates in the admin area the theme will be updated automatically. If you are editing files through the admin area and also uploading changes by FTP make sure to keep your files synced (local<->server) to avoid undoing changes.

 

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 they automatically take into account the website domain and CMS folder location (as set on the admin config page) and also if friendly URLs are enabled or not so they'll all work automatically even if the CMS is moved to a new folder or domain or if friendly URLs are enabled/disabled.

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. ?login /login

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

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

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

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

{cms-paynow-url}
Insert the URL for paynow page (this page is shown automatically after the order confirmation page). ?paynow specify an order id eg. ?paynow=123456789 or custom amount ?paynow&amount=10

{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. For these forms use action="" method="post" and ensure the appropriate names below are used on the input fields.

Login form:

Use {cms-login-warnings} template tag to display login form warnings.

Registration form:

Use {cms-register-warnings} template tag to display register form warnings.

Forgot password form:

Custom Search Forms

To integrate a search form that is part of a page template apply at least one of the following names to an input:

Note that blank values will be ignored by search. For drop down search options that use a select input the first option can be given a blank value eg. value="" if you want it to be ignored.

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.

 

Newsletter 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 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 form action can be left blank or set to submit to ?subscribe or the equivelent absolute URL. The template tag {cms-subscribe-warnings} can be placed where you want to display newsletter subscribe form warnings.

When an email address is submitted the CMS sends an email with a verification link. Once verified a notification email is sent to the site owner/email requesting the email address be added to mailing list. The site owner can then add the email manually to the CMS as a user account or to a third party newsletter service or they can just ignore it.

 

Sorting Items

Sorting items in categories is done by using the name "sort" in the url or by submitting it via form.

Example URL: https://mysite.com/?cat=123456789&sort=price

Or give a select element the name "sort" and one or more option values from the list below:

Listings can also be sorted by any custom value that is indexed.

The current sort value is stored in session and can be used to preselect a form option: $_SESSION[cms_key]['product_sort']

 

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.
'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.
Specifying custom search keys will use exact match/case insensitive, however; end a search key with "_lax" for a relaxed contains/non-exact search search value eg. search[location_lax]=rela will match ireland.
end a search key with "_range" to search between and including two min/max numbers eg. search[year_range]="2000 2030". To omit from the search process append omit_ eg. search[omit_this] or leave the value blank eg. search[this]="" end a search value with "_ormore" to search if number is greater or equal to eg. "1_ormore" end a search value with "_orless" to search if number is less or equal to eg. "1_orless"

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.