Длинное вступление
Перед любым мало-мальски серьезным сайтостроителем рано (гораздо лучше) или поздно (опыт - сын ошибок трудных) встает проблема уменьшения ручной работы, унификации кода сайта и вообще... Вполне резонное желание делать поменьше, а результат получать быстрее упирается только в возможность - как это сделать?
И тут на помощь может придти довольно простой, но в то же время чрезвычайно мощный инструмент. Имя ему - Server Side Includes, сокращенно - SSI. Наиболее естественно и полно поддержка SSI традиционно реализована в web-сервере Apache, впрочем и во всех остальных Web-серверах (Netscape, MS IIS и проч.) она тоже наличествует.
Для чего может быть полезен SSI? Самый простой пример. Предположим, решил ты, знатный наш перец, удивить мир своим сайтом. Все бы хорошо, да вот только FrontPage издох, хомяк (HomeSite) умер с перепоя и остался ты один в этом мире, одинешенек. Одна надежда, что ручки шаловливые выведут. И они таки выведут. Но только в том случае, если сайт не большой или обновления на сайте - раз в пятилетку. Правда, это уже не сайт, а похоронная контора, но об этом позже. Сайт должен быть большим, интересным, живым и обновляемым.
Довольно распространенной (притом очень вежливой и разумной) считается манера размещать управляющее меню сайта на каждой странице. Естественно, что вид этого меню может быть сколько угодно прихотливым - главное, чтобы это меню присутствовало на всех страницах! Кроме того, очень бы хорошо еще и баннерную рекламку крутить, да еще кнопочки дружественных сайтов забабахать, да еще... короче - не перечесть.
А теперь представь себе кошмар, когда один раздел добавился, а другой умер, баннерную сеть надо срочно менять, а с другом ты разругался в дребадан и его поганую кнопку (чтоб он всю жизнь во FrontPage Express сайты ваял) ты хочешь выкинуть с сайта раз и навсегда. При этом на сайте, ну, хотя бы с 50 страниц есть. Вопрос - сколько файлов в каждом случае придется изменять?
Неправильный ответ - 50. Правильный ответ - 1. Но только в том случае, если используются SSI.
Наверное, пора перестать темнить и рассказать, что к чему. :)
Да будет свет!
Все дело в том, что технология SSI позволяет вставлять в гипертекстовый документ "внешние" файлы. Т.е. - я делаю шаблон страницы, а в нем, с помощью однотипных команд, идет отсылка на несколько блоков - кирпичиков. Один блок служит - для заголовка, один - для меню, еще один - для кнопок, да еще два (побольше, побольше) - на рекламу. И так из этих кирпичиков страница и собирается.
Файлы, сделанные с применением SSI, обычно имеют расширение .shtml. "Лишняя" "S" в начале расширения говорит серверу, что в документе могут быть SSI инструкции. И сервер тогда их в состоянии грамотно обработать.
Таким образом получается, что к тому, кто страницы смотрит, уходит точно такой же объем кода, но при этом трудоемкость модификации и создания новых страниц для их автора заметно уменьшается.
Что ж, я нарисовал замечательную перспективу, но настырные голоса вопиют - "Show me the money", т.е. объясни, как же это все делается. Рассказываю...
Синтаксис 1
Главный оператор, которым придется пользоваться чаще всего - это "include". В общем случае SSI директива имеет вид: <!--#include virtual="myfile.txt"-->.
<!-- --> - это стандартный комментарий (если вдруг сервер не сможет распознать команду или не поддерживает ее, то она просто будет пропущена);
#include - собственно сама команда;
virtual - указывает на "вид" пути к файлу;
myfile.txt - имя вставляемого файла.
Естественно, что имя у включаемого файла может быть любым - с любым расширением (или без оного). Главное, - это "начинка" файла. Совершенно понятно, :) что это должен быть HTML.
Касательно "вида" пути (команда virtual). Если сервер проектируется для Web'a (скорее всего), то эта команда именно так и выглядит. Это, конечно, накладывает некоторые ограничения на то, чтобы удобно разместить вкладываемый файл. В этой команда нельзя применять гиперссылки (хотя это в любом случае дурной тон).
Однако иногда бывает полезно показать работу сайта непосредственно на "рабочем" компьютере, и тогда можно (нужно) использовать вместо virtual команду file. При этом адрес можно задавать в виде абсолютного адреса (C:VasyaPupkinSiteXXXmyfile.txt). Но это все-таки экзотика.
В общем случае на команде virtual и заканчивается общепринятое использование Server Side Includes - Включений на стороне сервера. И, наверное, это справедливо - что еще нужно знать, чтобы собирать сайт из кусочков?
Но для тех, кто понимает толк в сайтостроительстве, самое интересное начинается там, где останавливаются все остальные.
Так давайте на всю катушку использовать те возможности, которые дает SSI (а их, поверьте мне, не мало).
Синтаксис 2
Условно говоря, у SSI есть две большие области применения: первая - это вставлять внешние файлы, а вторая - вставлять так называемые "переменные окружения".
Делается это командой вида: <!--#echo var="echo_command"-->, где echo_command - переменная величина и может принимать порядка 30 значений. Все я толковать не буду (справочник по SSI можно найти на Web'е без труда), но самые важные - обязательно:
<!--#echo var="DOCUMENT_NAME"--> - выдаст на экран локальное имя текущего документа, к примеру: "ya_garni_peretz.htm" (очень полезен для тех, у кого частый склероз);
<!--#echo var="DOCUMENT_URL"--> - покажет локальный путь к документу, считая от корневой директории Web-сервера, т.е. адрес типа: /win/mydocs/ssi-tutor/baklan.htm.
<!--#echo var="DATE_LOCAL"--> - выведет текущие, локальные дату и время;
<!--#echo var="LAST_MODIFIED"--> - покажет дату последней правки текущего файла;
<!--#echo var="REMOTE_ADDR"--> - выведет ip вошедшего на страницу;
<!--#echo var="REMOTE_HOST"--> - выведет имя компьютера гостя. Очень простой трюк для определения - работает ли компьютер с использованием в настройках proxy: зайти на свою собственную страницу и прочитать адрес, полученный в ответ на команду REMOTE_HOST.
<!--#echo var="SERVER_SOFTWARE"--> - имя используемого провайдером HTTP сервера; иногда это бывает очень полезно знать; :)
<!--#echo var="SERVER_NAME "--> - имя компьютера, на котором работает web-сервер; тоже небезынтересно знать; :)
<!--#echo var="HTTP_USER_AGENT"--> - одна из самых любимых команд - позволяет определить тип браузера посетителя;
<!--#echo var="HTTP_REFERER"--> - показывает URL, откуда "клиент" пришел (иногда может быть полезна для того, чтобы определить "скрытый" адрес);
<!--#echo var="GATEWAY_INTERFACE"--> - фактически дает версию CGI ПО провайдера.
С помощью SSI, не прибегая к скриптам на Яве и прочим Общим Шлюзовым (cgi) прибамбасам, можно легко и непринужденно делать на странице сообщения типа:
Всем большой хай!
Сегодня у нас Sunday, 27-Feb-2000 20:30:07 Московское время (зима).
Последний раз этот документ был изменен Monday, 21-Feb-2000 23:00:00 MSK.
Твой IP адрес, незнакомец: 193.233.5.100
На моем сервере используется такое ПО, как: Apache/1.3.9 (Unix) PHP/3.0.6 mod_perl/1.16_02
Для просмотра ты, странник, используешь Mozilla/4.0 (compatible; MSIE 4.02; Windows NT). Must DIE! / Rulezzz forever!
А пришел ты сюда со странички: ribca.net
Стоит показать такую страницу всем своим друзьям, как они тут же тебя убоятся. Шутка ли, столько о них узнать. :)
Для особо пытливых приведу полный список echo-команд (в алфавитном порядке): "ACCEPT_LANGUGE", "AUTH_TYPE", "DATE_GMT", "DATE_LOCAL", "DOCUMENT_NAME", "DOCUMENT_URI", "CONTENT_LENGTH", "CONTENT_TYPE", "GATEWAY_INTERFACE", "HTTP_ACCEPT", "HTTP_COOKIE", "HTTP_FORWARDED", "HTTP_FROM", "HTTP_REFERER", "HTTP_USER_AGENT", "LAST_MODIFIED", "PATH_INFO", "PATH_TRANSLATED", "QUERY_STRING", "QUERY_STRING_UNESCAPED", "REMOTE_ADDR", "REMOTE_HOST", "REMOTE_IDENT", "REMOTE_USER", "REQUEST_METHOD", "SCRIPT_NAME", "SERVER_NAME", "SERVER_PORT", "SERVER_PROTOCOL", "SERVER_SOFTWARE".
Кто-то скажет, - "и это все?". Нет! На этом чудеса SSI еще не заканчиваются.
Приведу еще несколько любопытных и полезных команд.
Email. В простейшем варианте позволяет отправить заранее составленное сообщение на заранее определенный адрес.
Пример: <!--#email tohost="xakep.ru" message="You made the coolest magazine, that people ever made!" toaddress="test@xakep.ru" subject="SSI is coolest tool in the world, ya-ba-da-ba-doo!"-->.
Параметров у этой команды, конечно, больше, чем приведенные здесь. Здесь указаны только 4 необходимых (обязательных) команды: tohost - на какой хост (почтовый сервер) отправить письмо, message - текст самого послания, toaddress - почтовый адрес, на какой слать письмо, и последнее - subject, легко догадаться - тема письма.
Понятно, что при таком синтаксисе команды письмо будет отправляться каждый раз при заходе посетителя на страницу с этой командой.
Точно таким же образом можно использовать эту команду в ответе на заполнение формы (форму можно отправлять на анонимный адрес, а письмо с уведомлением на более реальный. :)
Fsize. Команда выводит в текущий документ размера указанного файла.
Пример: <!--#fsize virtual="../log-file.txt"-->.
Может быть полезна для удаленного контроля размера лога или еще для каких целей.
Flastmod. Эта команда позволяет включить в документ дату последней модификации любого доступного файла.
Пример: <!--#flastmod virtual="mysuperfile.htm"-->.
В отличие от echo-команды, команда Flastmod скажет "всю правду" о любом интересующем файле!
Очень хороший способ для начальников контролировать их нерадивых подчиненных (шучу). Но на самом деле очень удобно - делаешь себе одну страничку, где идет список всех файлов, и после обновлений на сайте смотришь - не перепутал ли чего. :) Оно ведь всяко может быть.
Break. Как легко понять из имени команды, она занимается прерыванием. :) Эта команда, как только она встречается, немедленно и безусловно останавливает дальнейший вывод документа.
Пример: <!--#break -->.
Чрезвычайно проста в использовании и не менее чрезвычайно полезна при отладке важных страниц. Я думаю, ни у кого не возникает сомнений, что страницу на гипертексте тоже можно (и нужно!) отлаживать.
Безусловно, это не все тэги, доступные в синтаксисе SSI. К примеру, за скобками остались такие команды, как exec (позволяет выполнять внешние программы и cgi-скрипты), или сonfig (изменяет вывод таких, к примеру, команд, как fsize, flastmod, позволяя настроить нужный формат выдачи сообщений.
Немного программирования
Конечно, в SSI кое-что есть от программирования. Но все же большинство команд - статичны. Тем не менее, для тех, кто хочет делать по-настоящему динамически изменяемые страницы, придутся по душе несколько "чисто программистских" операторов, содержащихся в SSI.
Из всех операторов программирования самым важным для нас, безусловно, является оператор IF. В SSI тег IF позволяет осуществлять вывод определенного текста в зависимости от условий.
В общем виде синтаксис команды выглядит так:
if' "<operand1>" <operator> "<operand2>" <operation>.
На месте последней команды "operation" может быть один из операторов: 'goto', 'print', 'error', 'break', 'errorbreak' или 'printbreak'.
Очень простой пример - допустим, нужно показывать что-то использующим определенный браузер и не показывать это остальным - не хрена им не в свое дело лезть.
Пишем:
<!--#if "&&HTTP_USER_AGENT&&" hasstring "Mozilla" goto Mozilllalabel-->
<P>Ты, пацан попал, у тебя неправильный браузер, и здесь ты ничего не увидишь
<!--#goto ="defaultlabel" -->
<!--#label ="Mozilllabel" -->
<P>А ты пацан клевый, и мне очень нравится твой браузер :).
<!--#label ="defaultlabel" -->
(Здесь уже можно ничего не писать). :)
Все просто, просто до безобразия.
Можно использовать IF для того, чтобы сравнивать текст в формах. Т.е. можно проверить идентичность заполнения форм (а вдруг человек ошибся) или напоминать гостю, что какую-то позицию формы он не заполнил. Вежливо и элементарно. :)
В примере выше я использовал два стандартных оператора - goto и label. Надо "осветить" их чуть более подробно.
Goto. Используется в связке с меткой label (см. ниже).
Синтаксис команды: <!--#goto ="<label>"-->
Пример. <!--#goto ="secretlabel" -->
<P>Это увидят только те, кому положено видеть
<!--#label ="secretlabel" -->
<P>А этот текст увидят все, без разбора.
Важное замечание: между символами <!--#goto и знаком "=" обязательно должен стоять пробел.
Label. Соответственно устанавливает метку, которую так щедро используют операторы goto или if..goto.
Синтаксис команды: <!--#label ="<label>"-->
Причем <label> строка из не более чем 51 символ без пробелов.
Наличие метки никак не влияет на форматирование документа.
Важное замечание: так же, как и у оператора goto, между символами <!--#goto и знаком "=" обязательно должен стоять пробел.
Дополнительные замечания
Для отладки сайта самое милое дело - это установить собственный web-сервер. Наиболее естественно это реализовано под юниксами, но и под Вынью есть жизнь. Понятное дело, не стоит устанавливать IIS, какие бы златые горы ни сулила за это Micro$soft. Наиболее рулезным сервером всех времен и народов был и остается Apache. Скачать дистрибутив для Win32 можно зайдя на www.apache.org и выбрав там ближайшее зеркало. Дистрибутив снабжен инсталляшкой, и справиться с его установкой легче легкого.
Все файлы сайта необходимо положить в каталог htdocs внутри директории с Апачем (по умолчанию в этой директории лежат файлы справки к Web-серверу). После этого остается самый "трудный" этап - необходимо сконфигурировать и запустить сервер. Поскольку Апач для win32 кровный брат Апача для юниксов, то вся конфигурация заключается в изменении нескольких текстовых файлов. Всего таких файлов 6, но менять придется 1-2. В любом случае, чтобы подогнать сервер под свои конкретные нужды, лучше почитать разные help'ы, faq'и и manual'ы. Это никогда не повредит.
Для того чтобы включить поддержку SSI в Apache, необходимо проделать следующие манипуляции (все файлы конфигурации лежат внутри директории conf и имеют одноименное расширение):
В файл httpd.conf необходимо будет добавить следующие строки (скорее всего их там нет): :)
AddType text/html .shtml
AddHandler server-parsed .shtml
Это наиболее стандартный ход. Впрочем, вместо .shtml можно написать .html или .phtml - главное, чтобы расширение было идентично расширению, которые использует для обозначения использующих SSI файлов провайдер.
И, естественно, нужно будет включить сам "механизм" вложения, а для этого добавить во все тот же httpd.conf к команде Options слово Includes.
Тогда строка с командой Options может принять вид:
Options Indexes FollowSymLinks Includes.
После всего этого шаманства остается лишь запустить сервер (запустить .bat'ничек под 95-98), либо (NT & Win2000 - читайте инструкцию) сделать Apache службой и запускать его, по мере надобности, как сервис.
Адрес локального сервера имеет вид: <noindex>http://localhost/</noindex>, что эквивалентно ip-адресу 127.0.0.1.
Ну и хватит
Так что дело за малым - скачать web-сервер, настроить его, запустить и... - начать ваять свой сайт. Не забывая при этом вовремя его отлаживать и пользоваться при этом всеми современными фичами, которые только есть. Я полагаю, что SSI далеко не устаревшая вещь, так что она нам еще послужит.
Удачи
Андрей Князев (kniazev@xakep.ru)
Полная версия этой страницы: Server Side Includes - SSI
еще чуток с другой стороны, в другой последовательности 
Описание SSI на русском языке
Server Side Includes
Структура команд SSI+
Основные команды SSI+
Примеры использования SSI+
Команда echo
Команда include
Команда fsize
Команда flastmod
Команда exec
Команда if
Команда goto
Команда label
Команда break
Технология создания активных документов SSI+ -- Server Side Includes предложена фирмой Questar Microsystems. Эту технологию поддерживают такие WWW сервера как Apache, Netscape, Spry Web и Microsoft Internet Information Server.
Поддержка этой технологии связанна с специальной конфигурацией WWW сервера и протокола HTTP.
Технология Server side includes (SSI) позволяет использовать в HTML документах такие возможности как: опрос текущего времени и даты, условного выполнения форматирования в зависимости от логических сравнений, формировать запросы или модифицировать базы данных, посылать электронную почту, вызывать программы или CGI scripts.
Возможности технологии SSI+ задают механизм совместного использования языка HTML и программ CGI Script.
Структура команд SSI+
Формат команды SSI+: '<!--#'<tag><variable set >'-->'
где:
'<!--#' начало обращения к SSI команде (tag).
<tag> одна из следующих команд: 'echo', 'include',
'fsize', 'flastmod', 'exec', 'config', 'odbc', 'email', 'if',
'goto', 'label', 'break'
<variable set> параметры (атрибуты) команды, значения которых зависят от командой <tag>. Формат задания переменных такой же как и формат задания атрибутов для команд языка HTML: <variable name> '=' '"' variable data '"' <variable name2> '=' '"' variable data2 '"'
<variable name n> '=' '"' variable datan '"'
'-->' конец обращения к SSI команде.
Отметим, что в отличии от обычных команд языка HTML для команд SSI+ задание значений переменных-атрибутов должно обязательно заключаться в "двойные кавычки" (") (для языка HTML значения атрибутов заключаются в двойные кавычки только в случае когда они содержат служебные символы или пробелы).
Заметим, что если сервер и просмотрщик не поддерживают режима работы SSI, то команды SSI воспринимаются просто как коментарии и не выводятся на экран просмотрщика.
Чать команд SSI имеют подкоманды, управляющие их работой, например, команды if, odbc, email, и exec. Формат подкоманды следующий: '&&'<subtag>'&&'
где:
'&&' зарезерированный символ для обозначения начала и конца подкоманды.
<subtag> имя подкоманды.
Замечание о SSI документах
SSI+ документ по умолчанию имет префикс (расширение) '.SHT' или '.SHTM' для их отличия от обычных HTML документов, которые имеют префикс '.HTML' или .HTM.
Хотя при конфигурации сервера можно обявить все документы как SSI, но это снижает его эффективность.
[В начало документа].
Основные команды SSI+ 'echo' Включение значений CGI переменых в HTML документ.
'include' Включение файла в HTML документ.
'fsize' Включение размера файла в HTML документ.
'flastmod' Включение даты последней модификации файла в HTML документ.
'exec' Выполнение внешнего исполняемого файла (CGI программы). Выходной поток данных (стандартный вывод) этой программы включается в документ.
'config' Установка параметров для SSI+ команд.
'odbc' Оращение к внешней ODBC СУБД.
'email' Отправка электронной почты или представление формы.
'if' Условный оператор, управляющий выполнением других команд SSI и вывода документа.
'goto' Оператор перехода на определенную SSI метку ('label').
'label' Метка в документе.
'break' Остановка вывода документа.
[В начало документа].
Примеры использования SSI
'echo'
Включение значений переменных окружения в HTML документ. Команда echo имеет только одну переменную var
Пример:
Вы используете просмотрщик <!--#echo var="HTTP_USER_AGENT"-->
Если данный документ просматривается через просмотрщик MS Internet Explorer 3.0 for Windows 95, то эта команда даст следующий результат
Вы используете просмотрщик Mozilla/2.0 (compatible; MSIE 3.0; Windows 95)
А для просмотрщика, через который вы сейчас читаете этот текст, получим
Вы используете просмотрщик Mozilla/4.0 (compatible; MSIE 4.01; Windows NT)
WWW сервер, соторый понимает технологию SSI, как правило, использует описанные ниже переменные окружения. Кроме того, если на сервере разрешено выполнение испольнаяемых модулей (CGI Script программы), то в документе могут быть использованы и переменные окружения CGI.
"DOCUMENT_NAME" локальное имя документа.
"DOCUMENT_URI" локальный путь к документу от базовой директории WWW сервера.
"QUERY_STRING_UNESCAPED" Строка, полученная от клиента, содежащая все shell-special characters escaped with %
"DATE_LOCAL" Текущая локальная дата и время.
"DATE_GMT" Дата и время по Гринвичу (Greenwich).
"LAST_MODIFIED" Дата последней модификации текущего документа.
"REMOTE_ADDR" IP адрес удаленного клиента.
"QUERY_STRING" Строка, полученная от клиента.
"SERVER_SOFTWARE" Имя HTTP server software.
"SERVER_NAME" Имя компьютера, на котором работает WWW сервер.
"GATEWAY_INTERFACE" Имя и версия Common Gateway Interface served WWW (HTTP) сервера (name/version).
"SERVER_PROTOCOL" Имя и версия HTTP сервера (name/version).
"SERVER_PORT" IP порт WWW (HTTP) сервера.
"REQUEST_METHOD" Тип метода запроса к серверу.
"PATH_INFO" Виртуальный путь, указанный в запросе (путь от базовой диретории WWW сервера).
"PATH_TRANSLATED" Полный путь, указанный в запросе.
"SCRIPT_NAME" Имя программы для выполнения в CGI запросе.
"REMOTE_HOST" Имя компьютера удаленного клиента.
"AUTH_TYPE" Переменная для определения авторизованного метода доступа к серверу (authentication method).
"REMOTE_USER" Имя пользователя для авторизованного метода доступа.
"REMOTE_IDENT" Имя удаленного клиета, используемое для идентификации пользователя, согласно спецификации RFC931.
"CONTENT_TYPE" Тип передачи данных от клиета по методам POST или PUT.
"CONTENT_LENGTH" Длина в байтах переданных данных по методам POST или PUT.
"HTTP_ACCEPT" Список, разделенный запятыми, MIME типов, понимаемых просмотрщиком клиента.
"HTTP_USER_AGENT" Имя просмотрщика клиента (browser software).
"HTTP_REFERER" ULR адрес HTML документа из которого сделан запрос клиентом.
"HTTP_FROM" Имя (подобное имени Е-mail address) удаленного клиента.
"HTTP_FORWARDED" Имя Proxy Server, через который общается клиент.
"ACCEPT_LANGUGE" Список языков доступных для копьютера клиента.
"HTTP_COOKIE" Содержение ответа клиента на запрос от сервера (см. ниже).
[В начало документа].
'include'
По команде 'include' на место этой команды подставляется содержимое файла, на который она указывает.
Команда имеет два параметра-переменных:
virtual для задания относительного адреса файла на WWW сервере.
file для задания абсолютного адреса файла на компьютере, на которм установлен WWW сервер.
Пример:
<!--#include virtual="include.txt"-->
Далее между двумя горизонтальными чертами следут вставленный в документ файл include.txt из текущей директории.
Начало вставки
Данный текст вставлен в документ из файла include.txt
Конец вставки
[В начало документа].
fsize Вывод размера файла в документ.
Команда имеет два параметра-переменных:
virtual для задания относительного адреса файла на WWW сервере.
file для задания абсолютного адреса файла на компьютере, на которм установлен WWW сервер.
Пример:
<!--#fsize virtual="ssi.shtml"-->
Выдача размера файла, который вы в данный момент читаете:
Размер файла ssi.shtml = 35k
Формат выдачи размера соответсвует установке сервера и может быть изменен командой config.
[В начало документа].
'flastmod'
Команда flastmod включает дату последней модификациии файла.
Команда имеет два параметра-переменных:
virtual для задания относительного адреса файла на WWW сервере.
file для задания абсолютного адреса файла на компьютере, на которм установлен WWW сервер.
Пример:
<!--#flastmod virtual="ssi.shtml"-->
Включение даты последней модификации файла 'ssi.shtml' в документ:
Дата последней модификации файла ssi.shtml = Monday, 10-Mar-1997 00:00:00 NS.
Формат выдачи даты и времени соответсвует установке сервера и может быть изменен командой config.
[В начало документа].
'exec'
Выполнене внешних программ и программ CGI Script.
Парамеры:
'cmd' задане командной строки параметров для выполнения UNIX shell исполняемых программ. Формат командной строки:
cmd="<exename> <argument list>"
где: <exename> полное имя исполняемой программы или команды, и <argument list> список аргументов, посылаемых исполняемой программе в командной строке.
Замечание: на сервере должны быть заданы пути к исполняемой программе в переменной окружения 'PATH'.
В случае отсутвия пути программу можно запустить, используя shell или CGI Script. Стандартный вывод программы направляется в HTML документ. Вывод может быть модифицирован командой 'config..cmdecho'.
'cgi' вызов программы CGI Script. Вызываемая программа должна находится в директории CGI-BIN WWW сервера или иметь префикс, например, .cgi, который задан для Shell программ в конфигурационном файле сервера. Формат команды:
cgi="<exename>"
где <exename> полное имя программы CGI Script.
Стандартный вывод программы подставляется в документ.
[В начало документа].
'config' tag
Команда config модифицирует вывод в HTML документ.
Парамеры-атрибуты команды:
'errmsg' The errmsg variable is used to set the error message that gets printed when the SSI+ engine encounters a parsing error or unavailable required data. This variable is retained for compatability with standard SSI, you may wish to use the onerr variable instead.
'timefmt' Установка формата выдачи времемени в команде echo..time SSI+ token output.
'sizefmt' The sizefmt variable is used to set the format ofecho..size SSI+ token output.
'cmdecho' The cmdecho variable is used to set the output option of subsequent exec..cmd tokens. The format is 'cmdecho'='"<onoroff>"'where <onoroff> is either 'ON' or 'OFF'. When the SSI+ parsing engine encounters an exec..cmd token it executes the command. If the command returns output then that output may be echoed into the HTML document or it may be ignored. The format of the data echoed is dependent on the presence or absence of config..cmdprefix and config..cmdpostfix tokens in the document. In the absence of config..cmdprefix and config..cmdpostfix tokens the output will be echoed exactly as returned with no formatting and no special character interpretation. In the presence of config..cmdprefix and/or config..cmdpostfix tokens the output will be formatted and interpreted. To activate echoing set cmdecho to 'ON' otherwise set it to 'OFF'. The default is 'OFF'.
'cmdprefix' The cmdprefix variable is used to set the string prefixed to each line out output from subsequent exec..cmd tokens. The format is 'cmdprefix="'<string>"'where <string> is any character string and/or HTML format tags. When the SSI+ parsing engine encounters an exec..cmdtoken it executes the command. If the command returns output then that output may be echoed into the HTML document or it maybe ignored. If the output is echoed (see 'cmdecho' above),then each line output from the executable will be prefixed with the string supplied before being echoed into the HTML document.
'cmdpostfix' The cmdpostfix variable is used to set the string appended to the end of each line out output from subsequent exec..cmd tokens. The format is 'cmdpostfix="'<string>"'where <string> is any character string and/or HTML format tags. When the SSI+ parsing engine encounters an exec..cmdtoken it executes the command. If the command returns output then that output may be echoed into the HTML document or it maybe ignored. If the output is echoed (see 'cmdecho' above),then each line output from the executable will be appended with the string supplied before being echoed into the HTML document.
'onerr' The onerr variable is used to set the action to be taken when the SSI+ engine encounters an error. The format is 'onerr="'<action>"'where <action> is one of the following tags.
'goto' causes a jump to a label token (see below). The format of the goto tag is:
'goto' <label>
where <label> is the name of a label defined in a subsequent label tag (see below).
'print' causes text to be printed. The format of the print tag is:
'print "'<text>"'
where <text> is any HTML text or tag.
'error' causes the current config..error message to be printed.
'break' causes termination of the HTML document transmission to the client.
'errorbreak' causes the current config..error message to be printed, and then causes termination of the HTML document transmission to the client.
'printbreak' causes text to be printed, and then causes termination of the HTML document transmission to the client. The format of the printbreak tag is the same as the format of the print tag.
Example. The following token on an HTML document sets the SSI+ error message to '*** ERROR ***'. From this point on down when an error occurs in the SSI+ parsing engine the message '*** ERROR ***'will be inserted into the HTML document at the location of the offending SSI+ statement.
<!--#config errmsg="*** ERROR ***" -->
Example. The following token on an HTML document sets the SSI+ error action to print a message and terminate the document. From this point on down when an error occurs in the SSI+ parsing engine the message will be inserted into the HTML document at the location of the offending SSI+ statement, and the document will be terminated
<!--#config onerr="printbreak "Sorry, we encountered an error while processing your document."" -->
Example. Suppose you wish to create an HTML document that performs a 'PING' operation on address '204.96.64.171' and then echo the results back to the client browser, with each line echoed as an element in an unnumbered list.
Insert the following lines into your HTML document:
<UL>
<!--#config cmdecho="ON" -->
<!--#config cmdprefix="<LI>" -->
<!--#exec cmd="ping 204.96.64.171 -w 20000" -->
</UL>
When the document is accessed by a remote browser the output would look something like this:
Pinging 204.96.64.171 with 32 bytes of data:
Reply from 204.96.64.171: bytes=32 time<10ms TTL=32
Reply from 204.96.64.171: bytes=32 time<10ms TTL=32
Reply from 204.96.64.171: bytes=32 time<10ms TTL=32
Reply from 204.96.64.171: bytes=32 time<10ms TTL=32
'odbc' tag
Notice! Due to some problems with the MS ODBC drivers we are phasing out the support of the SSI+ ODBC tags. To impliment ODBC with WebQuest we are using CScript with our WQODBC.DLL. For more information on CScript and ODBC, check out the Guestbook tutorial. The SSI+ ODBC tags will not exist in WebQuest 3.0.
The odbc tag provides for querying and updating odbc databases. Four variables are defined for the odbc token; 'debug', 'connect', 'statement', and 'format'.
'debug' variable
The debug variable is used to set the SSI+ engine into debug mode. Debug mode provides diagnostics of a highly detailed nature from both the SSI engine itself and the local ODBC engine. Debug messages appear on the returned HTML document at the position at which the errors occur. The debug variable should be used only for development and must be removed before production. When the debug variable is present a warning message will appear indicating it's presence, this message is benign and will not affect any other aspect of the SSI+ engine. The format of the debug variable is : 'debug='"<debugstring>"' where;
<debugstring> is any string and is reserved for future use.
'connect' variable
The connect variable is used to connect to a pre-existing odbc data source, to allow for subsequent statement tag operations on that data source. The format of the connect variable is 'connect="'<datasource>','<username>','<password>'"'where ;
<datasource> is the name odbc data source as defined on the local system in the odbc configuration utility. CAUTION! the account under which the server is run must be granted permission to access the data source.
<user name> is the name which to log into the data source.
<password> is the password with which to access the data source.
Example. To connect to a data source called 'odbcsht' as user 'dufus' and password 'dorkboy', one would use the following statement: <!--#odbc connect="odbcsht,dufus,dorkboy"-->.
'statement' variable
The statement variable is used to submit a Transact SQL statement to the odbc data source. The format of a statement variable is as follows: 'statement="'<SQLStatement>'"',where:
<SQL Statement> is any Transact SQL statement as defined in odbc and SQL reference text and help files.
Example. Suppose one wanted to query the 'CUSTOMERS' table from the above connected 'odbcsht' database to return all rows and display each row on a separate line. One may use the following sequence of statements:
Connect to the database with a connect token as described above.
Setup the output format with a statement token as described below.
Execute the query: <!--#odbc statement="SELECT NAME, AGE, VISCOSITY FROM CUSTOMERS ORDER BY 3, 2, 1" -->
Each row of the database will the be inserted into the HTML page per the format statement as demonstrated below.
'format' variable
The format variable is used to provide a template for the format of data that is returned from and odbc query. Use this variable to set up the appearance of data that will be returned from subsequent statement tag operations that return data from a database (i.e. the SQL statement 'SELECT'). The format of the format variable is 'format="'<cprintfstatement>'"'where;
<cprintfstatement> is a standard C language printf format string with the restriction of only allowing string (%s) insertions. The user is referred to any C language text for a description of this format. The number of instances of %s must be equal to the number of fields selected in a the subsequent SQL SELECT statement token.
Example. Suppose one wanted to query the 'CUSTOMERS' table from the above connected 'odbcsht' database to display the columns 'name', 'age', and 'viscosity' with each row on a separate line. One may use the following sequence of statements:
Connect to the database with a connect token as described above.
Setup the output format: <!--#obdc format="<P>Thecustomer's name is %s, and he is %s years old, he prefers a motor oil with SPF %s viscosity" -->.
Execute the query with a statement token as described above.
Each row of the database will the be inserted into the HTML page per the format statement. For example if the database has 3 rows the HTML output would look something like this:
Customer's name is Conan, and he is 29 years old, he prefers a motor oil with SPF 15 viscosity
Customer's name is Kevin, and he is 45 years old, he prefers a motor oil with SPF 30 viscosity
Customer's name is Alan, and he is 43 years old, he prefers a motor oil with SPF 50 viscosity
[В начало документа].
'email'
Отправка элктронной почты.
Пример:
<!--#email tohost="www.ict.nsk.su" message="Thanks for the HTML" toaddress="www@www.ict.nsk.su" subject="The SSI"-->
При отработке данного примера будет отправлено электроное письмо (e-mail), содержание которого задано атрибутом message, по адресу, определенному атрибутом toaddress, если данный адрес и host, заданный атрибутом tohost (данный атрибут может отсутсвовать), реально существует.
The email tag provides for sending an Email whenever an HTML page is accessed or an HTML form submitted. The nature of the variables below is defined in RFC 733. The variables 'fromhost', 'tohost', 'fromaddress' and 'toaddress' are required, all others are optional.
'debug' enables advanced diagnostics. This variable should only be used during development. The format of this variable is 'debug=" '<OnOrOff>'"' where
<OnOrOff> := 'ON' to enable debugging
<OnOrOff> := 'OFF' to disable debugging, this is the default action if the debug variable is omitted.
'fromhost' defines the name of the smtp host sending the mail.
'tohost' defines the name of the smtp host the mail will be sent to.
'fromaddress' defines the email address from party.
'toaddress' defines the email address of the recipient party.
'message' defines the message body to be sent.
'subject' defines the subject field of the message to be sent.
'sender' defines the email address sending party.
'replyto' defines the email address to which replies should be sent.
'cc' defines the courtesy copy email addresses.
'inreplyto' defines the inreplyto field of the message to be sent.
'id' defines the id field of the message to be sent.
Example. The following document send an email with debugging enabled. Supposewe have a form with datum : [First, Last, Middle Initial, Company,Address1, Address2, City, State, Zip, Country, Phone, Fax, Request,Urgency, ReplyMethod; Email, Subject, Message] we may post thatform to an HTML document containing the following fragment tosend an email.
<!--#email debug="ON" fromhost="www.theworld.com" tohost="mailbox.theworld.com" message="First -&&First&&, Last - &&Last&&,MI- &&Middle Initial&&, Company - &&Company&&, Address - &&Address1&&, &&Address2&&, &&City&&, &&State&&, &&Zip&&, &&Country&&, Phone - &&Phone&&,Fax - &&Fax&&, Request &&Urgency &&via&& ReplyMethod&&, Message - &&Message&& "fromaddress="&&EMail&&" toaddress="markw@mailbox.theworld.com" subject="WebMan - &&Subject&&" sender="&&EMail&& "replyto="&&EMail&&" cc=" " inreplyto="A WebMan Automated E-Mail" id="WebManEMail" -->
[В начало документа].
'if'
The if tag provides for conditional execution of SSI operations, and conditional printing of HTML text, based on logical comparisons. The format of the if tag is :
'if' '"'<operand1>'"' <operator> '"'<operand2>'"'<operation>
where:
<operand1> is the first operand of a logical comparison statement
<operand2> is the second operand of a logical comparison statement
<operator> is the logical comparison method ['==', '!=','<', '>', '!<', '!>']
<operation> is the action to take if the logical comparison evaluates to TRUE ['goto', 'print', 'error', 'break', 'errorbreak', 'printbreak']
The operands may be any string or number (integer or floating point). In the event that both operands are numbers the comparison will be based on the value of the numbers. In the event that one or both of the operands and not numbers, the comparison will be based on the alphabetic order of the operands.
The special case of the NULL operand is defined by two quotes with no characters between them. The NULL operand may used to check for the existence of form data from the remote client (see example below).
The operator defines what kind of comparison is performed on the operands:
'==' The equalto operator evaluates to TRUE if the operands are equal to each other.
'!=' The notequalto operator evaluates to TRUE if the operands are not equal to each other.
'<' The lessthan operator evaluates to TRUE if operand1 is less than operand2.
'>' The greaterthan operator evaluates to TRUE if operand1 is greater than operand2
'!<' The notlessthan operator evaluates to TRUE if operand1 is not less than operand2
'!>' The notgreaterthan operator evaluates to TRUE if operand1 is not greater than operand2
'hasstring' The hasstring operator returns TRUE is the text string in operand2 is found in the operand1 string.
In the event that the logical comparison evaluates to FALSE, nothing happens, If the logical comparison evaluates to TRUE then one of the following operations may be performed:
'goto' causes a jump to a label token (see below).The format of the goto tag is:
'goto' <label>
where <label> is the name of a label defined in a subsequent label tag (see below).
'print' causes text to be printed. The format of the print tag is:
'print' <text>
where <text> is any HTML text or tag.
'error' causes the current config..error message to be printed.
'break' causes termination of the HTML document transmission to the client.
'errorbreak' causes the current config..error message to be printed, and then causes termination of the HTML document transmission to the client.
'printbreak' causes text to be printed, and then causes termination of the HTML document transmission to the client. The format of the printbreak tag is the same as the format of the print tag.
Example. The following document fragment compares two numbers, if the operands are not equal then a goto will jump to a label.
<!--#if "10" != "20" goto testlabel-->
<P>This should not print
<!--#label ="testlabel" -->
<P>This should print
Example. The following document fragment demonstrates conditional execution based on data delivered from an HTML form. Suppose we have two form datum called 'formdata1' and 'formdata2' and we wish to compare them. The following document fragment compares the two operands, if the operands are equal then a goto will jump to a label. Otherwise the next line will print and the document will terminate on a break token (see below).
<!--#if "&&formdata1&&" == "&&formdata2&&" goto testlabel -->
<P>The operands are not equal.
<!--#break -->
<!--#label ="testlabel" -->
<P>operands are equal.
Example. The following document fragment prints two different statements depending on whether or not the client agent is NCSA Mosaic.
<!--#if "&&HTTP_USER_AGENT&&" hasstring "Mosaic" goto mosaiclabel -->
<P>You are not using Mosaic
<!--#goto ="defaultlabel" -->
<!--#label ="mosaiclabel" -->
<P>You are using Mosaic
<!--#label ="defaultlabel" -->
Example. Suppose we have a form with amongst other things a field named "BOO" and we wish to make sure that the remote client user enterted data into the "BOO" field before submitting the form. The following document fragment checks for the presence of data in the "BOO" field, if data exists then nothing happens, if data does not exist then a message will be displayed and the document will terminate.
<!--#if "&&BOO&&" == "" printbreak "<P>You must provide data for the BOO field, please resubmit." -->
[В начало документа].
'goto'
Команда goto оператор перехода на маетку label.
Формат команды: <!--#goto ="<label>"-->
где <label> имя метки, определенное командой label.
Пример.
<!--#goto ="testlabel" --> <P>This line will not print. <!--#label ="testlabel" --> <P>This line will print.
Замечание: Между сиволами <!--#goto и знаком = обязательно должен стоять пробел.
[В начало документа].
'label'
Команда label устанавливает метку в документе, которая используется командами goto или if..goto
Формат команды: <!--#label ="<label>"-->
где <label> строка из не более чем 51 символа без пробелов, идентиифицирующая место в документе.
Задание метки не влияет на форматирование документа.
Замечание: Между сиволами <!--#label и знаком = обязательно должен стоять пробел.
[В начало документа].
'break'
Команда break останавливает вывод документа как только встречается.
Пример. Следующий документ демонстрирут работу команды break.
<P>This line will print. <!--#break --> <P>This line will not print because the document has been truncated and transmission to the client is terminated.
Описание SSI на русском языке
Server Side Includes
Структура команд SSI+
Основные команды SSI+
Примеры использования SSI+
Команда echo
Команда include
Команда fsize
Команда flastmod
Команда exec
Команда if
Команда goto
Команда label
Команда break
Технология создания активных документов SSI+ -- Server Side Includes предложена фирмой Questar Microsystems. Эту технологию поддерживают такие WWW сервера как Apache, Netscape, Spry Web и Microsoft Internet Information Server.
Поддержка этой технологии связанна с специальной конфигурацией WWW сервера и протокола HTTP.
Технология Server side includes (SSI) позволяет использовать в HTML документах такие возможности как: опрос текущего времени и даты, условного выполнения форматирования в зависимости от логических сравнений, формировать запросы или модифицировать базы данных, посылать электронную почту, вызывать программы или CGI scripts.
Возможности технологии SSI+ задают механизм совместного использования языка HTML и программ CGI Script.
Структура команд SSI+
Формат команды SSI+: '<!--#'<tag><variable set >'-->'
где:
'<!--#' начало обращения к SSI команде (tag).
<tag> одна из следующих команд: 'echo', 'include',
'fsize', 'flastmod', 'exec', 'config', 'odbc', 'email', 'if',
'goto', 'label', 'break'
<variable set> параметры (атрибуты) команды, значения которых зависят от командой <tag>. Формат задания переменных такой же как и формат задания атрибутов для команд языка HTML: <variable name> '=' '"' variable data '"' <variable name2> '=' '"' variable data2 '"'
<variable name n> '=' '"' variable datan '"'
'-->' конец обращения к SSI команде.
Отметим, что в отличии от обычных команд языка HTML для команд SSI+ задание значений переменных-атрибутов должно обязательно заключаться в "двойные кавычки" (") (для языка HTML значения атрибутов заключаются в двойные кавычки только в случае когда они содержат служебные символы или пробелы).
Заметим, что если сервер и просмотрщик не поддерживают режима работы SSI, то команды SSI воспринимаются просто как коментарии и не выводятся на экран просмотрщика.
Чать команд SSI имеют подкоманды, управляющие их работой, например, команды if, odbc, email, и exec. Формат подкоманды следующий: '&&'<subtag>'&&'
где:
'&&' зарезерированный символ для обозначения начала и конца подкоманды.
<subtag> имя подкоманды.
Замечание о SSI документах
SSI+ документ по умолчанию имет префикс (расширение) '.SHT' или '.SHTM' для их отличия от обычных HTML документов, которые имеют префикс '.HTML' или .HTM.
Хотя при конфигурации сервера можно обявить все документы как SSI, но это снижает его эффективность.
[В начало документа].
Основные команды SSI+ 'echo' Включение значений CGI переменых в HTML документ.
'include' Включение файла в HTML документ.
'fsize' Включение размера файла в HTML документ.
'flastmod' Включение даты последней модификации файла в HTML документ.
'exec' Выполнение внешнего исполняемого файла (CGI программы). Выходной поток данных (стандартный вывод) этой программы включается в документ.
'config' Установка параметров для SSI+ команд.
'odbc' Оращение к внешней ODBC СУБД.
'email' Отправка электронной почты или представление формы.
'if' Условный оператор, управляющий выполнением других команд SSI и вывода документа.
'goto' Оператор перехода на определенную SSI метку ('label').
'label' Метка в документе.
'break' Остановка вывода документа.
[В начало документа].
Примеры использования SSI
'echo'
Включение значений переменных окружения в HTML документ. Команда echo имеет только одну переменную var
Пример:
Вы используете просмотрщик <!--#echo var="HTTP_USER_AGENT"-->
Если данный документ просматривается через просмотрщик MS Internet Explorer 3.0 for Windows 95, то эта команда даст следующий результат
Вы используете просмотрщик Mozilla/2.0 (compatible; MSIE 3.0; Windows 95)
А для просмотрщика, через который вы сейчас читаете этот текст, получим
Вы используете просмотрщик Mozilla/4.0 (compatible; MSIE 4.01; Windows NT)
WWW сервер, соторый понимает технологию SSI, как правило, использует описанные ниже переменные окружения. Кроме того, если на сервере разрешено выполнение испольнаяемых модулей (CGI Script программы), то в документе могут быть использованы и переменные окружения CGI.
"DOCUMENT_NAME" локальное имя документа.
"DOCUMENT_URI" локальный путь к документу от базовой директории WWW сервера.
"QUERY_STRING_UNESCAPED" Строка, полученная от клиента, содежащая все shell-special characters escaped with %
"DATE_LOCAL" Текущая локальная дата и время.
"DATE_GMT" Дата и время по Гринвичу (Greenwich).
"LAST_MODIFIED" Дата последней модификации текущего документа.
"REMOTE_ADDR" IP адрес удаленного клиента.
"QUERY_STRING" Строка, полученная от клиента.
"SERVER_SOFTWARE" Имя HTTP server software.
"SERVER_NAME" Имя компьютера, на котором работает WWW сервер.
"GATEWAY_INTERFACE" Имя и версия Common Gateway Interface served WWW (HTTP) сервера (name/version).
"SERVER_PROTOCOL" Имя и версия HTTP сервера (name/version).
"SERVER_PORT" IP порт WWW (HTTP) сервера.
"REQUEST_METHOD" Тип метода запроса к серверу.
"PATH_INFO" Виртуальный путь, указанный в запросе (путь от базовой диретории WWW сервера).
"PATH_TRANSLATED" Полный путь, указанный в запросе.
"SCRIPT_NAME" Имя программы для выполнения в CGI запросе.
"REMOTE_HOST" Имя компьютера удаленного клиента.
"AUTH_TYPE" Переменная для определения авторизованного метода доступа к серверу (authentication method).
"REMOTE_USER" Имя пользователя для авторизованного метода доступа.
"REMOTE_IDENT" Имя удаленного клиета, используемое для идентификации пользователя, согласно спецификации RFC931.
"CONTENT_TYPE" Тип передачи данных от клиета по методам POST или PUT.
"CONTENT_LENGTH" Длина в байтах переданных данных по методам POST или PUT.
"HTTP_ACCEPT" Список, разделенный запятыми, MIME типов, понимаемых просмотрщиком клиента.
"HTTP_USER_AGENT" Имя просмотрщика клиента (browser software).
"HTTP_REFERER" ULR адрес HTML документа из которого сделан запрос клиентом.
"HTTP_FROM" Имя (подобное имени Е-mail address) удаленного клиента.
"HTTP_FORWARDED" Имя Proxy Server, через который общается клиент.
"ACCEPT_LANGUGE" Список языков доступных для копьютера клиента.
"HTTP_COOKIE" Содержение ответа клиента на запрос от сервера (см. ниже).
[В начало документа].
'include'
По команде 'include' на место этой команды подставляется содержимое файла, на который она указывает.
Команда имеет два параметра-переменных:
virtual для задания относительного адреса файла на WWW сервере.
file для задания абсолютного адреса файла на компьютере, на которм установлен WWW сервер.
Пример:
<!--#include virtual="include.txt"-->
Далее между двумя горизонтальными чертами следут вставленный в документ файл include.txt из текущей директории.
Начало вставки
Данный текст вставлен в документ из файла include.txt
Конец вставки
[В начало документа].
fsize Вывод размера файла в документ.
Команда имеет два параметра-переменных:
virtual для задания относительного адреса файла на WWW сервере.
file для задания абсолютного адреса файла на компьютере, на которм установлен WWW сервер.
Пример:
<!--#fsize virtual="ssi.shtml"-->
Выдача размера файла, который вы в данный момент читаете:
Размер файла ssi.shtml = 35k
Формат выдачи размера соответсвует установке сервера и может быть изменен командой config.
[В начало документа].
'flastmod'
Команда flastmod включает дату последней модификациии файла.
Команда имеет два параметра-переменных:
virtual для задания относительного адреса файла на WWW сервере.
file для задания абсолютного адреса файла на компьютере, на которм установлен WWW сервер.
Пример:
<!--#flastmod virtual="ssi.shtml"-->
Включение даты последней модификации файла 'ssi.shtml' в документ:
Дата последней модификации файла ssi.shtml = Monday, 10-Mar-1997 00:00:00 NS.
Формат выдачи даты и времени соответсвует установке сервера и может быть изменен командой config.
[В начало документа].
'exec'
Выполнене внешних программ и программ CGI Script.
Парамеры:
'cmd' задане командной строки параметров для выполнения UNIX shell исполняемых программ. Формат командной строки:
cmd="<exename> <argument list>"
где: <exename> полное имя исполняемой программы или команды, и <argument list> список аргументов, посылаемых исполняемой программе в командной строке.
Замечание: на сервере должны быть заданы пути к исполняемой программе в переменной окружения 'PATH'.
В случае отсутвия пути программу можно запустить, используя shell или CGI Script. Стандартный вывод программы направляется в HTML документ. Вывод может быть модифицирован командой 'config..cmdecho'.
'cgi' вызов программы CGI Script. Вызываемая программа должна находится в директории CGI-BIN WWW сервера или иметь префикс, например, .cgi, который задан для Shell программ в конфигурационном файле сервера. Формат команды:
cgi="<exename>"
где <exename> полное имя программы CGI Script.
Стандартный вывод программы подставляется в документ.
[В начало документа].
'config' tag
Команда config модифицирует вывод в HTML документ.
Парамеры-атрибуты команды:
'errmsg' The errmsg variable is used to set the error message that gets printed when the SSI+ engine encounters a parsing error or unavailable required data. This variable is retained for compatability with standard SSI, you may wish to use the onerr variable instead.
'timefmt' Установка формата выдачи времемени в команде echo..time SSI+ token output.
'sizefmt' The sizefmt variable is used to set the format ofecho..size SSI+ token output.
'cmdecho' The cmdecho variable is used to set the output option of subsequent exec..cmd tokens. The format is 'cmdecho'='"<onoroff>"'where <onoroff> is either 'ON' or 'OFF'. When the SSI+ parsing engine encounters an exec..cmd token it executes the command. If the command returns output then that output may be echoed into the HTML document or it may be ignored. The format of the data echoed is dependent on the presence or absence of config..cmdprefix and config..cmdpostfix tokens in the document. In the absence of config..cmdprefix and config..cmdpostfix tokens the output will be echoed exactly as returned with no formatting and no special character interpretation. In the presence of config..cmdprefix and/or config..cmdpostfix tokens the output will be formatted and interpreted. To activate echoing set cmdecho to 'ON' otherwise set it to 'OFF'. The default is 'OFF'.
'cmdprefix' The cmdprefix variable is used to set the string prefixed to each line out output from subsequent exec..cmd tokens. The format is 'cmdprefix="'<string>"'where <string> is any character string and/or HTML format tags. When the SSI+ parsing engine encounters an exec..cmdtoken it executes the command. If the command returns output then that output may be echoed into the HTML document or it maybe ignored. If the output is echoed (see 'cmdecho' above),then each line output from the executable will be prefixed with the string supplied before being echoed into the HTML document.
'cmdpostfix' The cmdpostfix variable is used to set the string appended to the end of each line out output from subsequent exec..cmd tokens. The format is 'cmdpostfix="'<string>"'where <string> is any character string and/or HTML format tags. When the SSI+ parsing engine encounters an exec..cmdtoken it executes the command. If the command returns output then that output may be echoed into the HTML document or it maybe ignored. If the output is echoed (see 'cmdecho' above),then each line output from the executable will be appended with the string supplied before being echoed into the HTML document.
'onerr' The onerr variable is used to set the action to be taken when the SSI+ engine encounters an error. The format is 'onerr="'<action>"'where <action> is one of the following tags.
'goto' causes a jump to a label token (see below). The format of the goto tag is:
'goto' <label>
where <label> is the name of a label defined in a subsequent label tag (see below).
'print' causes text to be printed. The format of the print tag is:
'print "'<text>"'
where <text> is any HTML text or tag.
'error' causes the current config..error message to be printed.
'break' causes termination of the HTML document transmission to the client.
'errorbreak' causes the current config..error message to be printed, and then causes termination of the HTML document transmission to the client.
'printbreak' causes text to be printed, and then causes termination of the HTML document transmission to the client. The format of the printbreak tag is the same as the format of the print tag.
Example. The following token on an HTML document sets the SSI+ error message to '*** ERROR ***'. From this point on down when an error occurs in the SSI+ parsing engine the message '*** ERROR ***'will be inserted into the HTML document at the location of the offending SSI+ statement.
<!--#config errmsg="*** ERROR ***" -->
Example. The following token on an HTML document sets the SSI+ error action to print a message and terminate the document. From this point on down when an error occurs in the SSI+ parsing engine the message will be inserted into the HTML document at the location of the offending SSI+ statement, and the document will be terminated
<!--#config onerr="printbreak "Sorry, we encountered an error while processing your document."" -->
Example. Suppose you wish to create an HTML document that performs a 'PING' operation on address '204.96.64.171' and then echo the results back to the client browser, with each line echoed as an element in an unnumbered list.
Insert the following lines into your HTML document:
<UL>
<!--#config cmdecho="ON" -->
<!--#config cmdprefix="<LI>" -->
<!--#exec cmd="ping 204.96.64.171 -w 20000" -->
</UL>
When the document is accessed by a remote browser the output would look something like this:
Pinging 204.96.64.171 with 32 bytes of data:
Reply from 204.96.64.171: bytes=32 time<10ms TTL=32
Reply from 204.96.64.171: bytes=32 time<10ms TTL=32
Reply from 204.96.64.171: bytes=32 time<10ms TTL=32
Reply from 204.96.64.171: bytes=32 time<10ms TTL=32
'odbc' tag
Notice! Due to some problems with the MS ODBC drivers we are phasing out the support of the SSI+ ODBC tags. To impliment ODBC with WebQuest we are using CScript with our WQODBC.DLL. For more information on CScript and ODBC, check out the Guestbook tutorial. The SSI+ ODBC tags will not exist in WebQuest 3.0.
The odbc tag provides for querying and updating odbc databases. Four variables are defined for the odbc token; 'debug', 'connect', 'statement', and 'format'.
'debug' variable
The debug variable is used to set the SSI+ engine into debug mode. Debug mode provides diagnostics of a highly detailed nature from both the SSI engine itself and the local ODBC engine. Debug messages appear on the returned HTML document at the position at which the errors occur. The debug variable should be used only for development and must be removed before production. When the debug variable is present a warning message will appear indicating it's presence, this message is benign and will not affect any other aspect of the SSI+ engine. The format of the debug variable is : 'debug='"<debugstring>"' where;
<debugstring> is any string and is reserved for future use.
'connect' variable
The connect variable is used to connect to a pre-existing odbc data source, to allow for subsequent statement tag operations on that data source. The format of the connect variable is 'connect="'<datasource>','<username>','<password>'"'where ;
<datasource> is the name odbc data source as defined on the local system in the odbc configuration utility. CAUTION! the account under which the server is run must be granted permission to access the data source.
<user name> is the name which to log into the data source.
<password> is the password with which to access the data source.
Example. To connect to a data source called 'odbcsht' as user 'dufus' and password 'dorkboy', one would use the following statement: <!--#odbc connect="odbcsht,dufus,dorkboy"-->.
'statement' variable
The statement variable is used to submit a Transact SQL statement to the odbc data source. The format of a statement variable is as follows: 'statement="'<SQLStatement>'"',where:
<SQL Statement> is any Transact SQL statement as defined in odbc and SQL reference text and help files.
Example. Suppose one wanted to query the 'CUSTOMERS' table from the above connected 'odbcsht' database to return all rows and display each row on a separate line. One may use the following sequence of statements:
Connect to the database with a connect token as described above.
Setup the output format with a statement token as described below.
Execute the query: <!--#odbc statement="SELECT NAME, AGE, VISCOSITY FROM CUSTOMERS ORDER BY 3, 2, 1" -->
Each row of the database will the be inserted into the HTML page per the format statement as demonstrated below.
'format' variable
The format variable is used to provide a template for the format of data that is returned from and odbc query. Use this variable to set up the appearance of data that will be returned from subsequent statement tag operations that return data from a database (i.e. the SQL statement 'SELECT'). The format of the format variable is 'format="'<cprintfstatement>'"'where;
<cprintfstatement> is a standard C language printf format string with the restriction of only allowing string (%s) insertions. The user is referred to any C language text for a description of this format. The number of instances of %s must be equal to the number of fields selected in a the subsequent SQL SELECT statement token.
Example. Suppose one wanted to query the 'CUSTOMERS' table from the above connected 'odbcsht' database to display the columns 'name', 'age', and 'viscosity' with each row on a separate line. One may use the following sequence of statements:
Connect to the database with a connect token as described above.
Setup the output format: <!--#obdc format="<P>Thecustomer's name is %s, and he is %s years old, he prefers a motor oil with SPF %s viscosity" -->.
Execute the query with a statement token as described above.
Each row of the database will the be inserted into the HTML page per the format statement. For example if the database has 3 rows the HTML output would look something like this:
Customer's name is Conan, and he is 29 years old, he prefers a motor oil with SPF 15 viscosity
Customer's name is Kevin, and he is 45 years old, he prefers a motor oil with SPF 30 viscosity
Customer's name is Alan, and he is 43 years old, he prefers a motor oil with SPF 50 viscosity
[В начало документа].
'email'
Отправка элктронной почты.
Пример:
<!--#email tohost="www.ict.nsk.su" message="Thanks for the HTML" toaddress="www@www.ict.nsk.su" subject="The SSI"-->
При отработке данного примера будет отправлено электроное письмо (e-mail), содержание которого задано атрибутом message, по адресу, определенному атрибутом toaddress, если данный адрес и host, заданный атрибутом tohost (данный атрибут может отсутсвовать), реально существует.
The email tag provides for sending an Email whenever an HTML page is accessed or an HTML form submitted. The nature of the variables below is defined in RFC 733. The variables 'fromhost', 'tohost', 'fromaddress' and 'toaddress' are required, all others are optional.
'debug' enables advanced diagnostics. This variable should only be used during development. The format of this variable is 'debug=" '<OnOrOff>'"' where
<OnOrOff> := 'ON' to enable debugging
<OnOrOff> := 'OFF' to disable debugging, this is the default action if the debug variable is omitted.
'fromhost' defines the name of the smtp host sending the mail.
'tohost' defines the name of the smtp host the mail will be sent to.
'fromaddress' defines the email address from party.
'toaddress' defines the email address of the recipient party.
'message' defines the message body to be sent.
'subject' defines the subject field of the message to be sent.
'sender' defines the email address sending party.
'replyto' defines the email address to which replies should be sent.
'cc' defines the courtesy copy email addresses.
'inreplyto' defines the inreplyto field of the message to be sent.
'id' defines the id field of the message to be sent.
Example. The following document send an email with debugging enabled. Supposewe have a form with datum : [First, Last, Middle Initial, Company,Address1, Address2, City, State, Zip, Country, Phone, Fax, Request,Urgency, ReplyMethod; Email, Subject, Message] we may post thatform to an HTML document containing the following fragment tosend an email.
<!--#email debug="ON" fromhost="www.theworld.com" tohost="mailbox.theworld.com" message="First -&&First&&, Last - &&Last&&,MI- &&Middle Initial&&, Company - &&Company&&, Address - &&Address1&&, &&Address2&&, &&City&&, &&State&&, &&Zip&&, &&Country&&, Phone - &&Phone&&,Fax - &&Fax&&, Request &&Urgency &&via&& ReplyMethod&&, Message - &&Message&& "fromaddress="&&EMail&&" toaddress="markw@mailbox.theworld.com" subject="WebMan - &&Subject&&" sender="&&EMail&& "replyto="&&EMail&&" cc=" " inreplyto="A WebMan Automated E-Mail" id="WebManEMail" -->
[В начало документа].
'if'
The if tag provides for conditional execution of SSI operations, and conditional printing of HTML text, based on logical comparisons. The format of the if tag is :
'if' '"'<operand1>'"' <operator> '"'<operand2>'"'<operation>
where:
<operand1> is the first operand of a logical comparison statement
<operand2> is the second operand of a logical comparison statement
<operator> is the logical comparison method ['==', '!=','<', '>', '!<', '!>']
<operation> is the action to take if the logical comparison evaluates to TRUE ['goto', 'print', 'error', 'break', 'errorbreak', 'printbreak']
The operands may be any string or number (integer or floating point). In the event that both operands are numbers the comparison will be based on the value of the numbers. In the event that one or both of the operands and not numbers, the comparison will be based on the alphabetic order of the operands.
The special case of the NULL operand is defined by two quotes with no characters between them. The NULL operand may used to check for the existence of form data from the remote client (see example below).
The operator defines what kind of comparison is performed on the operands:
'==' The equalto operator evaluates to TRUE if the operands are equal to each other.
'!=' The notequalto operator evaluates to TRUE if the operands are not equal to each other.
'<' The lessthan operator evaluates to TRUE if operand1 is less than operand2.
'>' The greaterthan operator evaluates to TRUE if operand1 is greater than operand2
'!<' The notlessthan operator evaluates to TRUE if operand1 is not less than operand2
'!>' The notgreaterthan operator evaluates to TRUE if operand1 is not greater than operand2
'hasstring' The hasstring operator returns TRUE is the text string in operand2 is found in the operand1 string.
In the event that the logical comparison evaluates to FALSE, nothing happens, If the logical comparison evaluates to TRUE then one of the following operations may be performed:
'goto' causes a jump to a label token (see below).The format of the goto tag is:
'goto' <label>
where <label> is the name of a label defined in a subsequent label tag (see below).
'print' causes text to be printed. The format of the print tag is:
'print' <text>
where <text> is any HTML text or tag.
'error' causes the current config..error message to be printed.
'break' causes termination of the HTML document transmission to the client.
'errorbreak' causes the current config..error message to be printed, and then causes termination of the HTML document transmission to the client.
'printbreak' causes text to be printed, and then causes termination of the HTML document transmission to the client. The format of the printbreak tag is the same as the format of the print tag.
Example. The following document fragment compares two numbers, if the operands are not equal then a goto will jump to a label.
<!--#if "10" != "20" goto testlabel-->
<P>This should not print
<!--#label ="testlabel" -->
<P>This should print
Example. The following document fragment demonstrates conditional execution based on data delivered from an HTML form. Suppose we have two form datum called 'formdata1' and 'formdata2' and we wish to compare them. The following document fragment compares the two operands, if the operands are equal then a goto will jump to a label. Otherwise the next line will print and the document will terminate on a break token (see below).
<!--#if "&&formdata1&&" == "&&formdata2&&" goto testlabel -->
<P>The operands are not equal.
<!--#break -->
<!--#label ="testlabel" -->
<P>operands are equal.
Example. The following document fragment prints two different statements depending on whether or not the client agent is NCSA Mosaic.
<!--#if "&&HTTP_USER_AGENT&&" hasstring "Mosaic" goto mosaiclabel -->
<P>You are not using Mosaic
<!--#goto ="defaultlabel" -->
<!--#label ="mosaiclabel" -->
<P>You are using Mosaic
<!--#label ="defaultlabel" -->
Example. Suppose we have a form with amongst other things a field named "BOO" and we wish to make sure that the remote client user enterted data into the "BOO" field before submitting the form. The following document fragment checks for the presence of data in the "BOO" field, if data exists then nothing happens, if data does not exist then a message will be displayed and the document will terminate.
<!--#if "&&BOO&&" == "" printbreak "<P>You must provide data for the BOO field, please resubmit." -->
[В начало документа].
'goto'
Команда goto оператор перехода на маетку label.
Формат команды: <!--#goto ="<label>"-->
где <label> имя метки, определенное командой label.
Пример.
<!--#goto ="testlabel" --> <P>This line will not print. <!--#label ="testlabel" --> <P>This line will print.
Замечание: Между сиволами <!--#goto и знаком = обязательно должен стоять пробел.
[В начало документа].
'label'
Команда label устанавливает метку в документе, которая используется командами goto или if..goto
Формат команды: <!--#label ="<label>"-->
где <label> строка из не более чем 51 символа без пробелов, идентиифицирующая место в документе.
Задание метки не влияет на форматирование документа.
Замечание: Между сиволами <!--#label и знаком = обязательно должен стоять пробел.
[В начало документа].
'break'
Команда break останавливает вывод документа как только встречается.
Пример. Следующий документ демонстрирут работу команды break.
<P>This line will print. <!--#break --> <P>This line will not print because the document has been truncated and transmission to the client is terminated.
Для просмотра полной версии этой страницы, пожалуйста, пройдите по ссылке.