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.

http://www.cn-software.com/

Table of Contents

1 Overview.. 3

2 Theme Files and Templates. 4

2.1 index.tpl 5

2.2 common.tpl 5

2.3 category.tpl 6

2.4 item.tpl 7

2.5 article.tpl 7

2.6 extended.tpl 8

2.7 extended_article.tpl 8

2.8 map.tpl 9

2.9 search.tpl 9

2.10 add.tpl 9

2.11 add_article.tpl 11

2.12 admin.tpl 11

2.13 js.tpl 11

2.14 mail.tpl 11

3 Templates File Format 13

3.1 Inclusion of Generated HTML-Code. 13

3.2 Inclusion of Another Template. 13

3.2.1 Variables Display. 14

3.3 Conditions. 14

3.4 Function Call 15

Overview

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:

- arrangement of pages elements in optional order;
- display of optional fields for categories, subcategories, links and articles;
- variables display;
- support of conditions (if-then-else);
- templates nesting.

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.

# 2 Theme Files and Templates

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:

- title – the theme title (displayed upon selection of a theme);
- screenshot – the file name with the theme screenshot;
- description – the theme description.

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 item article category common
Detailed description of the site – the page, available by clicking the icon [+]. | extended extended_article common
The catalogue map – displays the list of all categories of the catalogue. | map common
Search results page | search item article common
Link addition page | add add_article mail common js
The administrative interface pages | admin common mail js

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.

## 2.1 index.tpl

Template for general structure of the catalogue pages.

index.tpl
index | Defines general structure of the main page. One can specify the order of the main elements on a page.

## 2.2 common.tpl

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

## 2.3 category.tpl

Templates for displaying categories and subcategories, as well as path to the current category.

category.tpl
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

## 2.4 item.tpl

Templates for displaying links at user pages of the catalogue.

item.tpl
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

## 2.5 article.tpl

Templates for displaying articles on user pages of the catalogue.

article.tpl
article | Article description
newarticles_top | Beginning of new articles block
newarticle | Description of a new article
newarticles_bottom | End of new articles block

## 2.6 extended.tpl

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

## 2.7 extended_article.tpl

Templates for a page containing the article text.

extended_article.tpl
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

## 2.8 map.tpl

Templates for the page «Catalogue map».

map.tpl
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

## 2.9 search.tpl

Templates for search results page. Templates from item.tpl file are used for links displaying.

search.tpl
search | Defines structure of search results page.

## 2.10 add.tpl

Templates for link addition page.

add.tpl
add | Defines general structure of all pages of link addition
form | Defines structure of link addition form (for «One-step» mode)
step1 step2 step3 | Defines structure of link addition forms (for «Wizard» mode)
final | Defines information, displayed upon link addition
field_link_url field_back_link field_site_title field_cats field_email field_descr field_descr_full field_meta_keywords field_meta_descr field_captcha field_submit | Define elements of link fields
extfield_ext_int1 extfield_ext_double1 extfield_ext_varchar1 extfield_ext_datetime1 extfield_ext_text1 extfield_ext_text2 extfield_ext_text3 | 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

## 2.11 add_article.tpl

Templates for a page to add articles on.

add_article.tpl
add_article_form | Defines the structure of a form for adding articles

## 2.12 admin.tpl

Templates for displaying links in the administrative interface.

admin.tpl
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

## 2.13 js.tpl

Description of JavaScript scripts.

js.tpl
js_calendar | Options for displaying built-in calendar (in the administrative interface)

## 2.14 mail.tpl

Templates of notification letters for administrators and users.

mail.tpl
mail_admin_to mail_admin_from mail_admin_subject mail_admin_body | Description of a template for letters notifying the administrator and moderators
mail_add_from mail_add_reply_to mail_add_subject mail_add_body | 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 mail_approve_reply_to mail_approve_subject mail_approve_body | Description of a template for letters notifying users about link submission in the catalogue
mail_decline_from mail_decline_reply_to mail_decline_subject mail_decline_body | Description of a template for letters notifying users about link refusal

# 3 Templates File Format

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:

- inclusion of generated HTML-code;
- inclusion of another template;
- variable display;
- condition of the type “if-then”;
- condition of the type “if-then-else”;
- function call (from the limited list).

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.

## 3.1 Inclusion of Generated HTML-Code

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.

## 3.2 Inclusion of Another Template

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.

### 3.2.1 Variable s Display

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:

1. $CNCAT – array, containing all information about a page and displayed data;
2. $THEMEURL – root URL for theme files;
3. $CNCAT_ENGINE – CNCat engine object.

## 3.3 Conditions

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.

## 3.4 Function Call

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:

- cn_str(string) – prepares a string for display on a page (analogue of htmlspecialchars());
- cn_date(mysql_date) – formats data;
- intval();
- ceil();
- floor();
- round();
- cn_copyright() – displays Copyrights (mandatory for CNCat Free).