Руководство по эксплуатации

СNCat 4.1

Редактирование оформления

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

Версия руководства: 1.0.1 (20.05.2008)

© 2002-2008 "CN-Software" Ltd.

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

Содержание

1 Общая информация. 3

2 Файлы темы и шаблоны.. 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 Формат файла шаблонов. 13

3.1 Включение сгенерированного HTML-кода. 13

3.2 Включение другого шаблона. 13

3.2.1 Отображение переменной. 14

3.3 Условия. 14

3.4 Вызов функции. 15

Общая информация

Оформление страниц каталога CNCat 4.1 осуществляется посредством тем оформления. Выбор темы оформления производится в административном интерфейсе каталога (Настройки – Каталог - Тема).

Темы оформления CNCat 4.1 обладают следующими возможностями:

- расположение элементов страниц в произвольном порядке;
- отображение произвольных полей категорий, подкатегорий и ссылок;
- отображение переменных;
- поддержка условий (if-then-else);
- включение шаблонов оформления друг в друга.

Примечание: В темах не поддерживается PHP-код. При необходимости исполнения PHP-кода можно создать файлы _top.php и/или _bottom.php, которые будут отображаться в начале и в конце страницы каталога.

# 2 Файлы темы и шаблоны

Примечание: Не следует изменять файлы стандартных тем оформления: это может повлиять на корректность обновления версий каталога. Если Вы хотите изменить дизайн каталога, то рекомендуется создать новую тему.

Темы оформления находятся в папке /cncat_config/themes/. Каждая тема располагается в отдельной папке.

Для создания новой темы достаточно скопировать одну из стандартных тем в новую папку и задать заголовок темы в файле theme.txt (см. ниже).

Тема состоит из файлов описания шаблонов (*.tpl), файла описания темы (theme.txt) и вспомогательных файлов (style.css, файлы изображений и т.д.).

Файл theme.txt содержит название и описание темы:

- title - заголовок темы (отображается при выборе темы);
- screenshot - имя файла с графическим изображением темы;
- description - описание темы.

В файлах описания шаблонов содержится описание одного или нескольких шаблонов, используемых в зависимости от отображаемой страницы:

Страница | Файлы шаблонов (.tpl)
Страница каталога - страница, содержащая список категорий, ссылок и статей. К страницам каталога относятся главная страница каталога и страницы для всех категорий. | index item article category common
Расширенное описание сайта – страница, доступная по ссылке [+]. | extended extended_article common
Карта каталога – отображает список всех категорий каталога. | map common
Страница результатов поиска | search item article common
Страница добавления ссылки/статьи | add add_article mail common js
Страницы административного интерфейса | admin common mail js

Каждый шаблон оформления описывает один из элементов страницы, либо часть элемента страницы. Далее представлен список шаблонов для каждого tpl-файла.

## 2.1 index.tpl

Шаблон общей структуры страниц каталога

index.tpl
index | Определяет общую структуру главной страницы. С помощью этого шаблона можно задавать порядок основных элементов страницы каталога.

## 2.2 common.tpl

Шаблоны, общие для всех (или большинства) пользовательских страниц.

common.tpl
top | Верхняя часть страницы (header)
bottom | Нижняя часть страницы (footer)
menu | Пункты меню в заголовке (Каталог, Добавить ссылку и т.д.)
searchform | Форма поиска
sort_top | Начало блока сортировки ссылок
sort | Элемент блока сортировки
sort_delim | Разделитель между элементами блока сортировки
sort_bottom | Конец блока сортировки
pagenav_top | Начало блока навигации по страницам
pagenav_curpage | Номер текущей страницы
pagenav_pageitem | Номер страницы, не являющейся текущей
pagenav_delim1 | Разделитель между соседними номерами страниц
pagenav_delim2 | Разделитель между дальними номерами страниц
pagenav_bottom | Конец блока навигации по страницам
filters_top | Начало блока фильтров
filter_top | Начало описания отдельного фильтра
filtval | Значение фильтра
filtval_delim | Разделитель между значениями фильтра
filter_bottom | Конец описания отдельного фильтра
filters_delim | Разделитель между описаниями фильтров
filters_end | Конец блока фильтров

## 2.3 category.tpl

Шаблоны отображения категорий и подкатегорий, а также пути к текущей категории.

category.tpl
cats_top | Начало блока категорий
cats_column_top | Начало столбца блока категорий
cat | Описание категории; включает вызов шаблонов «subcat…» со списком подкатегорий для данной категории.
cats_column_bottom | Конец столбца блока категорий
cats_bottom | Конец блока категорий
subcats_top | Начало блока подкатегорий для текущей категории
subcat | Описание подкатегории
subcats_delim | Разделитель между подкатегориями
subcats_more | Троеточие либо другой символ в конце списка подкатегорий, если их больше, чем может быть отображено на странице.
subcats_bottom | Конец блока подкатегорий
catpath_top | Начало описания пути к текущей категории (Главная->Подкатегория->Подкатегория->Текущая категория)
catpath_rootcat | Корневая категория
catpath_parentcat_delim | Разделитель между родительскими категориями
catpath_parentcat | Одна из родительских категорий
catpath_currentcat_delim | Разделитель перед текущей категорией
catpath_currentcat | Текущая категория
catpath_bottom | Конец блока описания пути к категории

## 2.4 item.tpl

Шаблоны отображения ссылок на пользовательских страницах каталога.

item.tpl
items_top | Начало блока ссылок
item | Описание ссылки
items_bottom | Конец блока ссылок
admin_rating_top | Начало блока оценки администратора (только для администратора)
admin_rating_num | Оценка
admin_rating_num_active | Текущая оценка для ссылки
admin_rating_delim | Разделитель между оценками
admin_rating_bottom | Конец блока оценок администратора
itemcount | Количество ссылок в категории
favitems_top | Начало блока избранных ссылок (блок включается в начало общего списка ссылок)
favitems_bottom | Конец блока избранных ссылок
brokenscript | Скрипт отображения окна подтверждения предупреждения администратора (при нажатии на ссылку [x])
newitems_top | Начало блока новых ссылок
newitem | Описание новой ссылки
newitems_bottom | Конец блока новых ссылок

## 2.5 article.tpl

Шаблоны отображения статей на пользовательских страницах каталога.

article.tpl
article | Анонс статьи
newarticles_top | Начало блока новых статей
newarticle | Анонс новой статьи
newarticles_bottom | Конец блока новых статей

## 2.6 extended.tpl

Шаблоны страницы расширенного описания ссылки.

extended.tpl
ext | Определяет общую структуру страницы расширенного описания ссылки, включая и само описание. Включает вызовы шаблонов «ext…», описывающих список категорий и фильтров для ссылки.
ext_cats_top | Начало блока списка категорий для текущей ссылки
ext_cat | Описание категории
ext_cat_delim | Разделитель между категориями
ext_cats_bottom | Конец блока списка категорий
ext_filter_top | Начало описания фильтра
ext_filtval | Значение фильтра
ext_filter_delim | Разделитель между значениями фильтра
ext_filter_bottom | Конец описания фильтра

## 2.7 extended_article.tpl

Шаблоны страницы, содержащей полный текст статьи.

extended_article.tpl
ext_article | Определяет общую структуру страницы с полным текстом статьи. Включает вызовы шаблонов «ext…», описывающих список категорий и фильтров для статьи.
ext_cats_top | Начало блока списка категорий для текущей статьи
ext_cat | Описание категории
ext_cat_delim | Разделитель между категориями
ext_cats_bottom | Конец блока списка категорий
ext_filter_top | Начало описания фильтра
ext_filtval | Значение фильтра
ext_filter_delim | Разделитель между значениями фильтра
ext_filter_bottom | Конец описания фильтра

## 2.8 map.tpl

Шаблоны страницы «Карта каталога».

map.tpl
map | Определяет структуру страницы карты каталога
map_cat_next_level | Отображается при возрастании уровня вложенности категории
map_cat | Описание категории
map_cat_prev_level | Отображается при уменьшении уровня вложенности категории

## 2.9 search.tpl

Шаблоны страницы результатов поиска. Для отображения ссылок используются шаблоны из файла item.tpl.

search.tpl
search | Определяет структуру страницы с результатами поиска.

## 2.10 add.tpl

Шаблоны страницы добавления ссылки.

add.tpl
add | Определяет общую структуру всех страниц добавления ссылки
form | Определяет структуру формы добавления ссылки (для режима «Одна форма»
step1 step2 step3 | Определяют структуру форм добавления ссылки по шагам (для режима «Мастер добавления»)
final | Определяет информацию, отображаемую после добавления ссылки
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 | Определяют элементы ввода соответствующих полей ссылки
extfield_ext_int1 extfield_ext_double1 extfield_ext_varchar1 extfield_ext_datetime1 extfield_ext_text1 extfield_ext_text2 extfield_ext_text3 | Определяют элементы ввода соответствующих расширенных полей ссылки
add_filter_top | Начало блока выбора значений фильтра (включает название фильтра)
add_filtval | Элемент выбора значения фильтра
add_filter_bottom | Конец блока выбора значений фильтра
add_backlinks_top | Начало блока списка предлагаемых обратных ссылок
add_backlink | Описание обратной ссылки
add_backlinks_bottom | Конец блока обратных ссылок
add_errors_top | Начало блока списка ошибок
add_error | Описание ошибки
add_errors_bottom | Конец блока списка ошибок
add_cat_next_level | Отображается при возрастании уровня вложенности категории в списке категорий
add_cat | Элемент выбора категории
add_cat_prev_level | Отображается при уменьшении уровня вложенности категории в списке категорий

## 2.11 add_article.tpl

Шаблоны страницы добавления статьи.

add_article.tpl
add_article_form | Определяет общую структуру формы добавления статьи

## 2.12 admin.tpl

Шаблоны отображения ссылок в административном интерфейсе.

admin.tpl
admin_items_begin | Начало блока ссылок административного интерфейса
admin_item | Описание ссылки
admin_items_end | Конец блока ссылок
admin_item_cat | Описание категории, в которую входит ссылка
admin_item_cat_delim | Разделитель между категориями
admin_item_rating | Элемент рейтинга ссылки

## 2.13 js.tpl

Описание скриптов JavaScript.

js.tpl
js_calendar | Функции отображения всплывающего календаря (в административном интерфейсе)

## 2.14 mail.tpl

Шаблоны писем с уведомлениями для администраторов и пользователей.

mail.tpl
mail_admin_to mail_admin_from mail_admin_subject mail_admin_body | Описание шаблона писем для уведомления администратора и модераторов
mail_add_from mail_add_reply_to mail_add_subject mail_add_body | Описание шаблона писем для уведомления пользователей о предварительном добавлении ссылки в каталог на рассмотрение администратора
mail_approve_from mail_approve_reply_to mail_approve_subject mail_approve_body | Описание шаблона писем для уведомления пользователей об утверждении ссылки в каталоге
mail_decline_from mail_decline_reply_to mail_decline_subject mail_decline_body | Описание шаблона писем для уведомления пользователей об отклонении ссылки

# 3 Формат файла шаблонов

Файл шаблона содержит описание одного или нескольких шаблонов. Каждый шаблон имеет следующий формат:

{TEMPLATE имя_шаблона}

HTML-код шаблона

{/TEMPLATE}

Для некоторых шаблонов после имени задается список используемых полей базы данных. Данная опция предусмотрена для повышения производительности. Например:

{TEMPLATE newitem (ITEM[item_id, item_title, item_descr, link_url, link_target])}

В данном случае из базы данных для переменной ITEM запрашиваются только поля item_id, item_title, item_descr, link_url, link_target.

HTML-код шаблона может содержать следующие специальные элементы:

- включение сгенерированного HTML-кода;
- включение другого шаблона;
- отображение переменной;
- условие типа if-then;
- условие типа if-then-else;
- вызов функции (из ограниченного списка).

Примечание. HTML-код шаблона отображается «как есть», за исключением специальных элементов. Это означает, что отображаются также все переносы строк, пробелы и пр. При необходимости весь шаблон можно записать в одну строку.

Ниже приведено подробное описание специальных элементов.

## 3.1 Включение сгенерированного HTML-кода

Формат: {DISPLAY имя_кода}

Пример: {DISPLAY CATEGORIES}

Используется для включения уже сгенерированных блоков страницы в шаблон. Генерация каждого блока производится ядром CNCat на основе нескольких шаблонов. Например, в файле index.tpl таким образом включаются блоки категорий, ссылок, сортировки и т.д.

## 3.2 Включение другого шаблона

Формат: {INCLUDE имя_шаблона}

Пример: {INCLUDE top}

Применяется для простого включения одного шаблона в другой; например, для подключения верхней и нижней частей страницы.

### 3.2.1 Отображение переменной

Формат 1: {$имя_переменной}

Формат 2: {$имя_массива[индекс1] }

Формат 3: {$имя_массива[индекс1][индекс2]}

Пример 1: {$CNCAT[item][link_url]}

Пример 2: {cn_str($CNCAT[item][item_title])}

Используется для отображения переменных и элементов массивов. В частности, в примере 1 показано отображение URL ссылки.

В примере 2 дополнительно используется функция cn_str(), аналогичная PHP-функции htmlspecialchars(). Данная функция предотвращает вставку вредоносного JS и HTML-кода. Рекомендуется использовать эту функцию для отображения всех строковых переменных.

Примечание: Индексы массивов указываются без кавычек.

В целях безопасности в настоящее время в шаблонах доступны следующие переменные:

1. $CNCAT – массив, содержащий всю информацию о странице и выводимых данных;
2. $THEMEURL – корневой URL для файлов темы;
3. $CNCAT_ENGINE – объект ядра CNCat.

## 3.3 Условия

Формат 1: {IF условие} HTML-код {ENDIF}

Формат 2: {IF условие} HTML-код {ELSE} HTML-код {ENDIF}

Пример:

{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}

В данном примере проверяется условие: если количество ссылок на странице больше 0 – то следует вывести количество; в противном случае следует вывести сообщение об отсутствии ссылок.

В условиях допустимо использование переменных и констант (число либо строка в одинарных кавычках).

Поддерживаются следующие операторы:

== != > < >= <= || && % + - * /

Поддерживаются вызовы функций (см. ниже).

Скобки не поддерживаются.

## 3.4 Вызов функции

Формат 1: {имя_функции ()}

Формат 2: {имя_функции (параметр, ….)}

Пример 1: {cn_str($CNCAT[item][item_title])}

Пример 2: {cn_date($CNCAT[item][item_insert_date])}

В качестве параметра функции может использоваться выражение (переменные, константы, операции, без использования скобок).

В целях безопасности доступны только следующие функции:

- cn_str(string) – подготавливает строку к выводу на страницу (аналог htmlspecialchars());
- cn_date(mysql_date) – форматирует дату;
- intval();
- ceil();
- floor();
- round();
- cn_copyright() – отображает Copyrights (обязательна для CNCat Free).