User Manual
CNCat 4.1
Design Themes
http://www.cn-software.com/cncat/
Manual version: 1.0.1 (5/21/2008)
© 2002-2008 "CN-Software" Ltd.
Table of Contents
3.1 Inclusion of Generated HTML-Code
3.2 Inclusion of Another Template
Design of CNCat 4.1 catalogue pages is configured with the help of special themes. Selection of a theme is performed in the administrative interface of the catalogue (Settings – Catalogue – Theme).
CNCat 4.1 design themes have the following features:
Note: PHP-code is not supported in themes. In case it is necessary to execute PHP-code, one should create files _top.php and/or _bottom.php, which will be displayed at the beginning and at the end of the catalogue page.
Note: We do not recommend changing files of standard themes: it may influence correctness of the catalogue update. To change the catalogue design, you should create a new theme.
Design themes are located at the folder /cncat_config/themes/. Each theme is placed into a separate folder.
To create a new theme one should copy any standard theme to a new folder and specify the theme title in theme.txt file (see below).
A theme consists of template description files (*.tpl), theme description file (theme.txt) and secondary files (style.css, image files etc.).
The file theme.txt contains the name and description of the theme:
Template description files contain description of one or more templates, which are used depending on the displayed page:
Page |
Template Files (.tpl) |
The catalogue page – the page, containing the list of categories and links. The main page and all categories pages belong here. |
index |
Detailed description of the site – the page, available by clicking the icon [+]. |
extended |
The catalogue map – displays the list of all categories of the catalogue. |
map |
Search results page |
search |
Link addition page |
add |
The administrative interface pages |
admin |
Each design template describes one of the page elements or a part of the element. Below is the list of templates for each tpl-file.
Template for general structure of the catalogue pages.
index |
Defines general structure of the main page. One can specify the order of the main elements on a page. |
General templates for all (or most part) user pages.
common.tpl |
|
top |
Top of the page (header) |
bottom |
Bottom of the page (footer) |
menu |
Menu items (Catalogue, Add a link etc.) |
searchform |
Search form |
sort_top |
Beginning of links sorting block |
sort |
Sorting block element |
sort_delim |
Delimiter between elements of sorting block |
sort_bottom |
End of links sorting block |
pagenav_top |
Beginning of pages navigation block |
pagenav_curpage |
Current page number |
pagenav_pageitem |
Page number |
pagenav_delim1 |
Delimiter between adjacent page numbers |
pagenav_delim2 |
Delimiter between distant page numbers |
pagenav_bottom |
End of pages navigation block |
filters_top |
Beginning of filters block |
filter_top |
Beginning of filter description |
filtval |
Filter value |
filtval_delim |
Delimiter between filter values |
filter_bottom |
End of filter description |
filters_delim |
Delimiter between filters descriptions |
filters_end |
End of filters block |
Templates for displaying categories and subcategories, as well as path to the current category.
cats_top |
Beginning of categories block |
cats_column_top |
Beginning of categories block column |
cat |
Description of a category; includes calling of «subcat…» templates with the list of subcategories for this category. |
cats_column_bottom |
End of categories block column |
cats_bottom |
End of categories block |
subcats_top |
Beginning of subcategories block for the current category |
subcat |
Description of a subcategory |
subcats_delim |
Delimiter between subcategories |
subcats_more |
Ellipsis or any other symbol at the end of subcategories list in case they are more than can be displayed on a page. |
subcats_bottom |
End of subcategories block |
catpath_top |
Beginning of description of the path to the current category (Main->Subcategory->Subcategory->Current category) |
catpath_rootcat |
Root category |
catpath_parentcat_delim |
Delimiter between parent categories |
catpath_parentcat |
One of parent categories |
catpath_currentcat_delim |
Delimiter between the current category |
catpath_currentcat |
Current category |
catpath_bottom |
End of description of the path to the current category |
Templates for displaying links at user pages of the catalogue.
items_top |
Beginning of links block |
item |
Link description |
items_bottom |
End of links block |
admin_rating_top |
Beginning of the administrator’s vote block (only for the administrator) |
admin_rating_num |
Rating |
admin_rating_num_active |
Current rating of a link |
admin_rating_delim |
Delimiter between rating marks |
admin_rating_bottom |
End of the administrator’s vote block |
itemcount |
Number of links in a category |
favitems_top |
Beginning of favourite links block (the block is included into the beginning of general list of links) |
favitems_bottom |
End of favourite links block |
brokenscript |
Script for displaying a dialog box confirming broken link warning (when pressing [x] icon) |
newitems_top |
Beginning of new links block |
newitem |
Description of a new link |
newitems_bottom |
End of new links block |
Templates for displaying articles on user pages of the catalogue.
article |
Article description |
newarticles_top |
Beginning of new articles block |
newarticle |
Description of a new article |
newarticles_bottom |
End of new articles block |
Templates for a page with detailed description of a link.
extended.tpl |
|
ext |
Defines general structure of a page with detailed description of a link, including the description itself. Contains calling of «ext…» templates, describing the list of categories and filters for the link. |
ext_cats_top |
Beginning of categories list block for the current link |
ext_cat |
Description of a category |
ext_cat_delim |
Delimiter between categories |
ext_cats_bottom |
End of categories list block |
ext_filter_top |
Beginning of filters description |
ext_filtval |
Filter value |
ext_filter_delim |
Delimiter between filter values |
ext_filter_bottom |
End of filter description |
Templates for a page containing the article text.
ext_article |
Defines general structure of a page which contains the text of an article. Contains calling of «ext…» templates, describing the list of categories and filters for the article. |
ext_cats_top |
Beginning of categories list block for the current article |
ext_cat |
Description of a category |
ext_cat_delim |
Delimiter between categories |
ext_cats_bottom |
End of categories list block |
ext_filter_top |
Beginning of filters description |
ext_filtval |
Filter value |
ext_filter_delim |
Delimiter between filter values |
ext_filter_bottom |
End of filter description |
Templates for the page «Catalogue map».
map |
Defines structure of the catalogue map page |
map_cat_next_level |
Displayed upon increasing of the category nesting level |
map_cat |
Description of a category |
map_cat_prev_level |
Displayed upon decreasing of the category nesting level |
Templates for search results page. Templates from item.tpl file are used for links displaying.
search |
Defines structure of search results page. |
Templates for link addition page.
add |
Defines general structure of all pages of link addition |
form |
Defines structure of link addition form (for «One-step» mode) |
step1 |
Defines structure of link addition forms (for «Wizard» mode) |
final |
Defines information, displayed upon link addition |
field_link_url |
Define elements of link fields |
extfield_ext_int1 |
Define elements of extended link fields |
add_filter_top |
Beginning of filter value selection block (includes filter name) |
add_filtval |
Element of filter value selection |
add_filter_bottom |
End of filter value selection block |
add_backlinks_top |
Beginning of backward links block |
add_backlink |
Description of a backward link |
add_backlinks_bottom |
End of backward links block |
add_errors_top |
Beginning of errors list block |
add_error |
Description of an error |
add_errors_bottom |
End of errors list block |
add_cat_next_level |
Displayed upon increasing of categories nesting level in the list of categories |
add_cat |
Categories selection element |
add_cat_prev_level |
Displayed upon decreasing of categories nesting level in the list of categories |
Templates for a page to add articles on.
add_article_form |
Defines the structure of a form for adding articles |
Templates for displaying links in the administrative interface.
admin_items_begin |
Beginning of links block in the administrative interface |
admin_item |
Description of a link |
admin_items_end |
End of links block |
admin_item_cat |
Description of a link category |
admin_item_cat_delim |
Delimiter between categories |
admin_item_rating |
Element of a link rating |
Description of JavaScript scripts.
js_calendar |
Options for displaying built-in calendar (in the administrative interface) |
Templates of notification letters for administrators and users.
mail.tpl |
|
mail_admin_to |
Description of a template for letters notifying the administrator and moderators |
mail_add_from |
Description of a template for letters notifying users about preliminary addition of a link to the catalogue at the administrator’s consideration |
mail_approve_from |
Description of a template for letters notifying users about link submission in the catalogue |
mail_decline_from |
Description of a template for letters notifying users about link refusal |
Template file contains description of one or more templates. Each template has the following format:
{TEMPLATE template_name}
HTML-template code
{/TEMPLATE}
For certain templates the list of used database fields is defined after the name. This option is intended for increasing of efficiency. For instance:
{TEMPLATE newitem (ITEM[item_id, item_title, item_descr, link_url, link_target])}
In this case only fields item_id, item_title, item_descr, link_url, link_target are requested for ITEM variable.
HTML-code of the template can contain the following special elements:
Note. HTML-code of the template is displayed «as is», except for special elements. It means that all line foldings, space symbols etc. are displayed. If necessary, the whole template can be written in one line.
Below is the detailed description of special elements.
Format: {DISPLAY code_name}
Example: {DISPLAY CATEGORIES}
It is used for inclusion of generated page block into the template. Generation of each block is performed by CNCat engine on the basis of several templates. For example, thus blocks of categories, links, sorting etc, are included into index.tpl file.
Format: {INCLUDE template_name}
Example: {INCLUDE top}
It is used for simple inclusion of one template into another; for example, for inclusion of the page top and bottom.
Format 1: {$variable_name}
Format 2: {$array_name[index1] }
Format 3: {$array_name[index1][index2]}
Example 1: {$CNCAT[item][link_url]}
Example 2: {cn_str($CNCAT[item][item_title])}
It is used for displaying variables and arrays elements. For instance, Example 1 shows display of a link URL.
Example 2 uses additional function cn_str(), equal to PHP-function htmlspecialchars(). This function prevents from insertion of harmful JS and HTML-code. It is recommended to use this function for displaying of all string variables.
Note: Arrays indexes are defined without inverted commas.
For the sake of safety the following variables are available in templates at present:
Format 1: {IF condition} HTML-code {ENDIF}
Format 2: {IF condition} HTML-code {ELSE} HTML-code {ENDIF}
Example:
{IF $CNCAT[page][cat_item_count]>0}
{$CNCAT[lang][items_in_category]}:
<strong>{$CNCAT[page][cat_item_count]}</strong>
{ELSE}
{$CNCAT[lang][no_items_in_category]}
{ENDIF}
In this example the following condition is checked: if a number of links on a page is more than 0 – then the number should be displayed; otherwise a message notifying about links absence should be displayed.
It is possible to use variables and constants in conditions (a number of a line in single inverted commas).
The following operators are supported:
== != > < >= <= || && % + - * /
Function calls are supported (see below).
Brackets are not supported.
Format 1: {function_name()}
Format 2: {function_name(parameter, ….)}
Example 1: {cn_str($CNCAT[item][item_title])}
Example 2: {cn_date($CNCAT[item][item_insert_date])}
An expression can be used as the function parameter (variables, constants, operations, without brackets).
For the sake of safety only the following functions are available: