> Main > Products and Services > Purchase > Company
English / Russian

CNCat

The application for web-resources catalogue creation

Download PDF (0.4 Mb)

User Manual

CNCat 4.1

Design Themes

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

Manual version: 1.0.1 (5/20/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;
  • descriptionthe 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          Variables 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).