Russian English German

Template:

Punktlinie
Silber
RSS

Freunde:

This site is valid:

Valid HTML 4.01 Transitional
Letzte Aktualisierung:
Wed, 16 Aug 2006 22:08:51 +0300
Based on SGEngine v. 2.2
© 2006, SGEngine. All rights reserved.

Документация SGEngine 2.2

  1. Введение
  2. Что нового
  3. Установка
    1. Обновление предыдущих версий
    2. Новая установка
    3. Завершение инсталляции
  4. Устройство и основные функции
    1. Структура файлов и директорий
    2. Шаблоны
    3. Модули
    4. Файл конфигураций
    5. Многоязыковая поддержка
    6. Текстовые и html файлы
    7. Администрирование
  5. Модули, входящие в пакет
    1. Общедоступные модули
    2. Административные модули
  6. TO DO

1. Введение

SGEngine - это многофункциональный и гибкий в настройке "движок" для сайта, написанный на языке Web-программирования Perl.

Его основные достоинства - это:

Итак, если Вы только начинающий вэб-мастер, то вполне можете без чей-либо помощи установить движок SGEngine и воспользоваться одним из готовых шаблонов. Если же Вы являетесь гуру HTML, ну или хотя бы немного знакомы с ним, то Вам по силам создать свой дизайн и пользоваться готовыми модулями. Ну а если Вы, кроме того, работаете с языком программирования Perl, то можете сами создавать модули к Вашему новому сайту!

2. Что нового

+ Captcha - защита от спам-роботов в гостевой и комментариях к новостям
+ Обрезаны URL с помощью модуля Apache mod_rewrite
+ Новый модуль "Навигационное меню"
+ Новый шаблон "Серебряный"
* HTML код движка подогнан под стандарт HTML 4.01 Transitional
* Модуль "Создание/Правка текстовых файлов на сервере" переименован в "Файл-менеджер". Изменения: листинг директорий и файлов на сервере и свободное перемещение внутри корневой директории; возможность загрузки файлов на сервер прямо из браузера; и многое другое. См. 5.2 Файл-менеджер
* URL движка унифицированы
* Большое количество мелких исправлений и изменений
- Отменена возможность запуска административной части сайта для неавторизированного пользователя
- Из пакета убран шаблон "Черно-белый"
- Исправлено большое количество мелких багов

Далее в документации:
Изменения по сравнению с предыдущей версией 2.1: Удалено
Изменения по сравнению с предыдущей версией 2.1: Добавлено

3. Установка

3.1 Обновление предыдущих версий

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

  1. Установите движок как это указано в пункте 3.2 Новая установка
  2. Запустите скрипт cbase.pl, набрав его адрес в адресной строке браузера. Этот скрипт конвертирует старые базы в новый формат SGEngine

Если у Вас была установлена версия 2.0 и выше, то необходимо проделать следующие шаги:

  1. Сделайте бэкап-версию всех файлов на сервере, чтобы сохранить все проделанные Вами изменения
  2. Установите движок как это указано в пункте 3.2 Новая установка
  3. Замените все базы из ранее сохраненной бэкап-версии. Учтите, что с версии 2.1 введена поддержка переключения языков, и месторасположение всех файлов баз изменилось!
  4. Если Вы меняли дизайн уже существующих шаблонов, то все изменения не сохранятся, и Вам, скорее всего, придется применять их снова. Если Вы создавали свои шаблоны, то их нужно будет сравнить с новыми. Последнее касается в основном только модульных шаблонов.

3.2 Новая установка

  1. Извлеките содержимое архива на диск.
  2. Соблюдая структуру, перенесите все папки и файлы из директории "www" в директорию на Вашем сервере, где хранятся HTML документы. Скорее всего, она так и будет называться - "www", но не всегда! Возможен вариант "public_html"
  3. Соблюдая структуру, перенесите все папки и файлы из директории "cgi-bin" в директорию на Вашем сервере, где хранятся CGI скрипты. Возможно, она будет называться "cgi".
  4. Всем файлам-скриптам, имеющим расширение .pl, .pm необходимо выставить права 0755 ("drwxr-xr-x"). Это можно осуществить с помощью Вашего FTP-Клиента в свойствах файла. Однако учтите, что некоторые хостинг-провайдеры диктуют свои условия, и Вам придется выставить те права, которые требуются на сервере для запуска скриптов.
  5. Перенесите, соблюдая структуру, все остальные папки и файлы в корневой домашний каталог на Вашем сервере.
  6. Запустите скрипт setup.pl через браузер. Это "Мастер установки", который поможет Вам за несколько шагов завершить инсталляцию

3.3 Завершение инсталляции

Если установка прошла удачно, то не забудьте удалить скрипты cbase.pl и setup.pl, или переместить их в каталог, откуда никто другой кроме Вас не сможет их запустить. Если же возникли проблемы, то обращайтесь на наш форум.

4. Устройство и основные функции

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

Шаблоны состоят только из контентных файлов. Модули, в свою очередь, это скрипты, которые используют модульные шаблоны для вывода информации.

4.1 Структура файлов и директорий

4.2 Шаблоны

Каждый шаблон движка SGEngine представляет собой набор текстовых файлов написанных на языке html, а также файла каскадных таблиц. Файл каскадных таблиц находится в каталоге /www/css. Файлы html лежат в подкаталоге, имеющим уникальное имя и являющимся названием шаблона, каталога tmpl, и делятся на две группы:

  1. "структурные" имеющие расширение .html - это шаблоны, отвечающие за структуру сайта и определяющие его общий внешний вид и содержание
  2. "модульные" имеющие расширение .tmpl - это шаблоны, используемые модулями

Структурные

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

<engine main{txt/file.html}> Этот тег указывает, что сюда будет выводиться динамическая часть сайта, т.е. результат работы модулей, вызванных из адресной строки. В фигурных скобках указывается имя модуля с параметрами, который будет использоваться по умолчанию. В данном случае вызывается модуль обработки текстовых файлов и ему передается файл file.html
<engine run{modul}> Вместо этого тега будет вставляться результат работы модуля modul
<engine tmpl{file.html}> Вставляет содержимое файла file.html из папки актуального шаблона
<engine txt{file.html}> Вставляет содержимое файла file.html из папки с тестовыми, html файлами, используемыми движком.
<engine print lng{xxx}>
<engine print conf{xxx}>		 Вставляет строку с ключом "xxx" из файла языкового пакета или конфигурационного файла.
<engine print lng{copyrights}> Выводит тег защиты прав. Он обязательно должен находиться в шаблоне.

Модульные

Эти шаблоны используются модулями и имеют расширение .tmpl, их основная задача облегчить создание и правку дизайна сайта. С ними не нужно каждый раз залезать в код модулей и выискивать html строки. Каждый модуль может использовать по несколько шаблонов и даже иметь общие с другими, что опять же экономит время на исправление. Модульный шаблон также как и структурный представляет собой текст с разметкой html, в определенные части которого вставляются переменные модуля. Все эти переменные описаны в начале модульного шаблона и имеют вид: [%VARIABLE%]. Важные области шаблона активно используемые модулями выделены <!--AREA--><!--END:AREA-->.

Установка шаблона

Посетитель сайта может выбрать один из шаблонов для постоянного пользования. Шаблон устанавливается по ссылке, построенной следующим образом:

http://www.your_domain.zone/cgi-bin/index.pl/set_template/template
http://www.your_domain.zone/language/set_template/template

Где,

language - вид языка(ru, en, de) Данное слово абсолютно идентично с названием каталога, где хранятся базы и логи движка, зависимые от языка, а также каталога с текстовыми и HTML файлами;
template - имя шаблона(dotted, black-white silver), одновременно являющееся названием каталога, где хранятся файлы шаблона;

Имя этого шаблона записывается в файл cookie, которые должны быть разрешены браузером. Это дает возможность каждому посетителю установить понравившийся шаблон и видеть сайт в том виде, в котором он ему больше всего приглянулся.

4.3 Модули

Модули - это написанные на языке программирования Perl исполняемые скрипты. Они придают сайту, работающему на движке SGEngine, динамичность. По сути, модули не являются автономными программами, это лишь кусок кода, который вызывается из основного скрипта index.pl. Поэтому, чтобы создать свой модуль нужно знать следующее:

  1. Модуль должен начинаться со строк:
    use strict;
    use vars qw(%conf %lng @query $template);
    my $tmp = '';
    Где,
    %conf - глобальный хэш-массив с конфигурациями;
    %lng - глобальный хэш-массив со строками языкового пакета;
    @query - глобальный массив с параметрами модуля, переданными через ссылку;
    $template - глобальная переменная с именем актуального шаблона;
    $tmp - локальная переменная для вывода результата.
  2. В модуле может содержаться любой программный код, включая подпрограммы, вызов других модулей и т.д., за исключением прямого вывода в STDOUT. Прямой вывод в STDOUT должен быть заменен выводом в переменную $tmp.
  3. Модуль должен возвращать переменную $tmp строкой:
    return $tmp;
  4. Оканчиваться модуль должен, как положено любой внешней подпрограмме в Perl, строкой:
    1;

Параметры могут быть переданы модулю через ссылку. Например:

http://www.your_domain.zone/cgi-bin/index.pl/module/param_1/param_2/.../param_n
http://www.your_domain.zone/language/module/param_1/param_2/.../param_n

Где,

language - вид языка(ru, en, de) Данное слово абсолютно идентично с названием каталога, где хранятся базы и логи движка, зависимые от языка, а также каталога с текстовыми и HTML файлами;
module - модуль, который будет работать в данный момент;
param_1/param_2/.../param_n - параметры для данного модуля;

4.4 Файл конфигураций

Файл конфигураций config.ini хранит основные настройки движка. Он будет создан "Мастером установки"(setup.pl) во время инсталляции. Этот файл состоит из игнорируемых движком строк комментариев, начинающихся со знака #, а также строк, определяющих переменные конфигурации. Такие строки имеют вид:

имя_переменной          значение_переменной

Кроме того, в конфигурационном файле работают "альясы", которые обозначены %alias%. Это переменные, определенные раньше. Например:

path          /home/sgengine2
log_dir          %path%/log

В этом случае переменная log_dir будет иметь значение /home/sgengine2/log

4.5 Многоязыковая поддержка

Файл языкового пакета построен по подобию файла конфигураций см. 4.4 Файл конфигураций.

Посетитель сайта имеет возможность выбрать, на каком языке будет отображаться содержимое сайта. Язык устанавливается по ссылке, построенной следующим образом:

http://www.your_domain.zone/cgi-bin/index.pl/set_lng/language
http://www.your_domain.zone/old_language/set_lng/new_language

Где,

language old_language, new_language - вид языка(russian, english, german)(ru, en, de). Данное слово абсолютно идентично с названием каталога, где хранятся базы и логи движка, зависимые от языка, а также каталога с текстовыми и HTML файлами;

Для того чтобы выбранный язык language был активен во всех частях сайта необходимо исполнение следующих условий:

  1. Должен существовать соответствующий языковой пакет /cgi-bin/mylib/ language.lng, а также языковой пакет меню /cgi-bin/mylib/menu/language.lng
  2. Должны существовать все базы и логи в каталоге /log/language см. 4.1 Структура файлов и директорий
  3. Должны существовать все текстовые и HTML файлы в каталоге /txt/language см. 4.1 Структура файлов и директорий

Однако если условие 2 и 3 не выполнено или выполнено не полностью, сайт будет все-равно работать корректно и без ошибок! Например, Вы решили не писать новости на немецком языке, тогда Вы не кладете базу новостей в каталог /log/german /log/de. Во время обработки файлов, движок не найдет немецкую базу и будет использовать файл находящийся в каталоге языка, выставленного по умолчанию /log/russian /log/ru. То же самое действительно для текстовых и HTML файлов.

Важно! Относительные ссылки внутри структурных и модульных шаблонов не должны содержать вид языка, так как движок сам подставляет его во время обработки. Обычные html файлы тоже могут использовать эту возможность. Например, ссылаясь на модуль гостевой книги, достаточно указать /guestbook.

4.6 Текстовые и html файлы

Движок SGEngine позволяет выводить обычные текстовые и html файлы в динамической части сайта с помощью модуля 5.1 Вывод текстовых и HTML файлов, либо через соответствующий внутренний тэг <engine txt{file.html}>. При этом html файлы будут выведены в соответствии с html разметкой, а вот текстовые файлы, которые должны обязательно иметь расширение .txt, так как есть! То есть, если в текстовом файле стоит абзац, пробел или перевод строки, то на сайте будет отображен абзац, пробел и перевод строки.

4.7 Администрирование

Для управления движком SGEngine предусмотрена специальная административная часть сайта со своими модулями. Она закрыта для обычного посетителя паролем. Доступ к этой области имеют только следующие виды пользователей:

Администратор может добавлять, удалять модераторов, понижать и повышать их в ранге, а также определяет, какие именно модули те имеют право запускать. Также он видит все новости выложенные на сайте. Модератору же доступны только те новости, которые он добавил сам.

Административная часть обязательно должна быть защищена паролем. Не авторизированные пользователи не имеют доступ к этой части движка. Для организации доступа используется файл /cgi-bin/.htaccess

5 Модули, входящие в пакет

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

5.1 Общедоступные модули

Эта группа модулей доступна всем посетителям сайта

Новостная лента

Этот модуль выводит новости в виде ленты. Количество выводимых новостей настраивается в конфигурационном файле. Если в новости присутствует тэг <cut> <!--cut-->, то после него текст выводиться не будет, а будет выведена ссылка "Читать дальше". Это позволяет обрезать очень длинные новости, чтобы не "раздувать" ленту.

Просмотр новости

Выводит полный текст новости, уникальный номер которой передается параметром. Тэг <cut> <!--cut--> этим модулем игнорируется.

Архив новостей

Выводит новости в виде более сокращенной ленты. Новость обрезается по тэгам <cut> <!--cut--> и <br /> <br>. Внизу выводится линейка со страницами. Из этого модуля доступны все новости.

Комментарии к новости

Выводит новость полностью и все комментарии к нему. С помощью формы, этот модуль позволяет посетителям оставлять комментарии к новости на сайте. Форма использует смайлы, которые можно отключить, изменив соответствующую переменную в файле конфигураций. Модуль записывает также IP адрес автора каждого сообщения. Если посетитель будет обнаружен в бан-листе, то оставлять комментарии он не сможет. Если в сообщении будет найдено запрещенное слово, то сообщение не будет отправлено.

Комментарии защищены модулем 5.1 Captcha - защита от спам-роботов

RSS - лента новостей

Выводит новостную ленту в формате RSS. URL запроса выглядит следующим образом:

http://www.your_domain.zone/cgi-bin/index.pl/rss/language.xml
http://www.your_domain.zone/language/rss

Где,

language - вид языка(russian, english, german)(ru, en, de), на котором будет выводиться лента новостей. Условие - наличие базы новостей в языковой папке;

Вывод текстовых и HTML файлов

Этот модуль позволяет выводить текстовые и html файлы. Путь к текстовому файлу передается параметром. Если текстовый файл не будет найден в директории языка, который выбрал посетитель, то модуль выведет файл, находящийся в директории языка по умолчанию. Важно! Передаваемый путь не должен включать в себя сам каталог языка! Также см. 4.5 Текстовые и html файлы

Форма обратной связи

Выводит форму, которая позволяет посетителям сайта отправить Е-Мэйл на адрес администратора, указанного в файле конфигураций. Это надежный способ скрыть электронный адрес от спам-роботов.

Загрузка файлов с сервера

Этот модуль позволяет посетителям скачивать файлы с сайта и при этом вести лог с количеством скачиваний. При этом сам каталог, откуда происходит загрузка, остается невидимым для скачивающего и определяется в файле конфигураций. Ссылка на файл, например archiv.zip, должна выглядеть следующим образом:

/cgi-bin/index.pl/dl/archiv.zip

Последняя дата обновления

Выводит последнюю дату обновления, которая записывается модулем добавления новостей в отдельный лог-файл.

Гостевая книга

Модуль гостевой книги позволяет посетителям сайта оставлять свои сообщения и пожелания. Сообщения выводятся в виде ленты с линейкой страниц. Количество сообщений на страницу определяется в файле конфигураций. Модуль записывает также IP адрес автора каждого сообщения. Если посетитель будет обнаружен в бан-листе, то писать в гостевую книгу он не сможет. Если в сообщении будет найдено запрещенное слово, то сообщение не будет отправлено.

Гостевая книга защищена модулем 5.1 Captcha - защита от спам-роботов

Поиск по ленте новостей

Этот модуль производит поиск по ленте новостей. Результат выдается в удобной и легко настраиваемой форме. Основные возможности:

Captcha - защита от спам-роботов

Этот модуль защищает формы отправки сообщений от спам-роботов. Посетителю выводится картинка, содержащая случайную комбинацию букв и цифр, которую он должен ввести в соответствующее поле формы.

Навигационное меню

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

5.2 Административные модули

Эта группа модулей доступна только администраторам и модераторам в административной части сайта

Менеджер новостей

Этот модуль позволяет добавить новость на сайт, удалить или изменить существующую. Имеется функция предпросмотра и панель инструментов, в которую входят кнопки вставки тэгов, форма добавления ссылки и форма загрузки файлов-изображений с последующим размещением в новости. Для такого файла можно автоматически создать уменьшенную копию для предпросмотра (необходимо наличие Perl библиотек Image::Magick или GD плюс Image::Size). Модуль определяет, под каким логином зашел пользователь, и перенимает его в качестве имени автора новости. После того как новость будет добавлена, модуль стирает КЭШ поискового модуля.

С помощью этого модуля можно также управлять комментариями к каждой новости. Есть возможность правки, удаления, занесения автора в бан-лист, а также добавления своего комментария от имени пользователя.

Администратор имеет доступ ко всем новостям сайта, а модератор только к своим собственным. Также см. 4.7 Администрирование

Создание/Правка текстовых файлов на сервере

Этот модуль позволяет править и создавать текстовые файлы прямо на сервере. Это очень удобно, когда нет доступа к фтп.

Файл-менеджер

Модуль выводит структурированный список файлов и директорий на сервере, позволяет перемещаться по нему и производить основные действия: создание новых объектов, переименование, удаление, правка. Также имеется возможность загрузки любого количества файлов на сервер.

Управление гостевой книгой

С помощью этого модуля ведется расширенное административное управление гостевой книгой. Администратор может оставить ответ к каждому сообщению, или же удалить/подправить само сообщение. Вместе с записями гостевой книги выводится IP адрес автора и имеется возможность бана по нему и по имени.

Бан-лист / Список запрещенных слов

Этот модуль выводит список забаненных IP адресов и запрещенных слов. Предусмотрено расширенное управления обоими листами: добавление, правка, удаление. При изменении списков проводится дополнительный анализ - существующие слова и адреса добавляться повторно не будут. Присутствует автоматическое определение наличия нескольких адресов в одной подобласти и предложение добавить ее всю.
В список запрещенных слов имеет смысл заносить интернет адреса сайтов, рекламируемые спамерами или, например такие слова как "viagra".

Статистика и управление скачиваемых файлов

Модуль выводит список файлов доступных для скачивания, общее число скачиваний к каждому, а также количество новых скачиваний с момента последнего посещения пользователя. Позволяет обнулить статистику или удалить файл из списка. Сам файл удален не будет!

Лог искомых слов по сайту

Показывает все слова, сохраненные в КЭШе поиска по новостям. Есть возможность ручной очистки КЭШа.

Менеджер доступа к административной части

Позволяет администратору добавлять новых пользователей, удалять старых, а также менять пароли. Кроме того, имеется возможность понижать их до модератора или повышать до администратора.

Модератор может с помощью этого модуля сменить свой пароль.

Также см. 4.7 Администрирование

6. TO DO

Планируется в будущих версиях:

- Новые шаблоны
- Модуль голосования
- Модуль правки меню
- Модуль загрузки файлов с отображением количества скачек
- Требуются Ваши идеи!