SSI (программирование)

SSI (Server Side Includes — включения на стороне сервера) — несложный язык для динамической «сборки» веб-страниц на сервере из отдельных составных частей и выдачи клиенту полученного HTML-документа. Реализован в веб-сервере Apache при помощи модуля mod_include. Включённая в настройках по умолчанию веб-сервера возможность позволяет подключать HTML-файлы, поэтому для использования инструкций файл должен оканчиваться расширением .shtml, .stm или .shtm

Необходимо помнить, что некоторые сервисы не исполняют команды SSI, если расширение файла будет отличным от приведённых выше, например, .html.

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

Отдельные элементы синтаксиса SSI используются и в других скриптовых языках, например в ASP.

Основные команды SSI

• config — устанавливает формат сообщений об ошибках, дат и размера
• set — устанавливает значение переменной
• printenv — выводит список переменных окружения
• echo — вставляет значение переменной
• flastmod — вставляет дату и время изменения файла
• fsize — вставляет размер файла
• include — вставляет содержимое другого файла
• if, elif, else, endif — условные операторы

Описание

config — контролирует различные аспекты сканирования. Его атрибутами могут быть:

• errmsg — устанавливает сообщение, выводящееся при возникновении ошибки; в большинстве случаев целесообразно установить в пустую строку;
• sizefmt — устанавливает формат, в котором будет выводиться размер файла.
• timefmt — устанавливает формат, в котором будет выводиться дата. Формат соответствует передаваемому библиотечной функции strftime;

Переменные для sizefmt:

<!--#config sizefmt="abbrev"--> Выводит размер файла в килобайтах: (17k)

<!--#config sizefmt="bytes"--> Выводит размер файла в байтах (17,076)

Переменные для timefmt:

Формат	Описание	Пример
%a	Краткое название дня недели	Mon
%A	Полное название дня недели	Monday
%b	Аббревиатура названия месяца	Dec
%B	Полное название месяца	December
%d	День месяца	01 (не 1)
%D	Дата в формате "%m/%d/%y"	12/31/99
%e	День месяца	13
%H	Часы в 24-часовом формате	13
%I	Часы в 12-часовом формате	01
%j	День года	235
%m	Номер месяца	01
%M	Минуты	03
%p	AM/PM (до полудня/после)	AM
%r	Время в формате "I:M:S p"	11:35:46 PM
%S	Секунды	34
%s	Время в секундах с 01.01.1970	957228726
%T	Время в формате "%H:%M:%S"	14:05:34
%U	Неделя года	16
%w	Номер дня недели	4
%y	Год в формате ГГ	99
%Y	Год в формате ГГГГ	1999
%Z	Временная зона	MSK

Обратите внимание на то, что команды #config sizefmt и #config timefmt влияют на все связанные с ними SSI-команды от того места, откуда они были вызваны и до самого конца страницы. Поэтому каждый вызов команд #flastmod и #fsize лучше снабжать своей командой #config.

set — устанавливает значение переменной. Её атрибутами являются var, определяющий имя переменной, и value, определяющий её значение.

• Подстановка переменных

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

<!--#if expr="$a = \$test" -->

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

<!--#set var="Zed" value="${a}bc_${abc}" --> 

В результате такого присвоения переменная Zed будет иметь значение «Xbc_Y», если переменная a равна X, а переменная abc равна Y.

printenv — Выводит список так называемых «переменных окружения» с их значениями. Вызывается без параметров.

Переменные окружения:

• DOCUMENT_ROOT (название основной папки для веб-страниц на сервере, обычно ваша папка public_html и путь к ней)
• USER_AGENT и HTTP_USER_AGENT (название браузера, которым пользуется посетитель)
• REMOTE_ADDR (IP-адрес посетителя)
• REMOTE_HOST (адрес посетителя в нормальной форме — например, adsl53.peterlink.ru)
• SERVER_ADDR (IP-адрес вашего сайта)
• SERVER_NAME и HTTP_HOST (адрес сервера, типа userguide.webservis.ru)
• DOCUMENT_URI, REQUEST_URI и SCRIPT_NAME (запрошенная вами страница, типа /examples/mysqlexample.shtml)
• DOCUMENT_NAME (имя файла (без каталогов) документа, запрошенного пользователем)
• SCRIPT_FILENAME (полный путь к веб-странице на сервере. Например /home/home-webservis/public_html/ и так далее)
• SERVER_SOFTWARE (название сервера, например, Apache/1.3.2 (Unix))
• SERVER_ADMIN (почтовый адрес владельца сервера, указанный при установке)
• DATE_LOCAL (сегодняшние время и дата в вашем часовом поясе (для сервера))
• DATE_GMT (текущее время по Гринвичу)
• LAST_MODIFIED (дата последней модификации документа, запрошенного пользователем. То есть во вложенном SSI эта переменная будет содержать имя «главного» документа, а не вложенного)
• HTTP_COOKIE (строка Cookie, установленная для текущего домена)

echo — выводит значение установленной переменной SSI. Допустимые атрибуты:

• var (обязательный) — имя выводимой переменной;
• encoding (необязательный) — перекодировка значения переменной перед выводом. Действует в версиях Apache 1.3.12 и выше. В версиях Apache 2.2.6 и выше по умолчанию символы кодируются в windows-1252 из-за чего ssi переменные окружения с русскими символами при отображении в документе портятся и выглядят как кракозябры, во избежание этого всегда указывайте encoding="none". Обратите внимание, что будучи заданным, этот атрибут должен предшествовать атрибуту var. Варианты значений атрибута encoding:
  • entity (по умолчанию) — будет произведено преобразование специальных HTML-символов в сущности;
  • url — будет произведено т.н. %-преобразование, то есть пригодное для указания в строке URL;
  • none — не будет производиться никаких преобразований.

flastmod — выводит дату последней модификации файла в определённом с помощью timefmt формате. Атрибуты аналогичны атрибутам fsize.

fsize — выводит размер файла в определённом с помощью sizefmt формате. Допустимые атрибуты:

• file — определяет путь к файлу, относительно сканируемого документа;
• virtual — определяет стандартный кодированный URL, относительно сканируемого документа, или, при наличии в начале слеша (/) — относительно корня документов узла.

include — включает текст другого документа или файла в сканируемый файл. К включаемому файлу применяются все установленные правила ограничения доступа. Если для каталога, из которого включается файл, установлена опция IncludesNOEXEC, и включение данного документа привело бы к запуску программы, то документ не включается, и выводится сообщение об ошибке. CGI сценарии вызываются, как обычно с помощью URL, который может содержать кодированную строку запроса (query string). Положение файла указывается с помощью атрибутов:

• file — указывает путь, относительно сканируемого документа; путь не может содержать ../ и не может быть абсолютным путём; всегда предпочтительнее использовать атрибут virtual;
• virtual — содержит кодированный URL, относительный или абсолютный; URL не может содержать имя протокола или имя хоста, и может содержать строку запроса.

Условные операторы

Базовыми элементами контроля являются:

<!--#if expr="test_condition" -->
<!--#elif expr="test_condition" -->
<!--#else -->
<!--#endif -->

Элементы elif и else являются необязательными.

Элемент endif заканчивает элемент if и является обязательным.

test_condition может быть одним из следующих:

• string — истинно, если string не пуста;
• string1 = string2
• string1 != string2
• string1 < string2
• string1 <= string2
• string1 > string2
• string1 >= string2
• всё вышеперечисленное истинно, если выполняется условие сравнения;
• string1 ~ string2 — истинно, если string1 содержит в себе string2;
• string1 ~= /string2/ — истинно, если string1 содержит в себе string2, а string2 — регулярное выражение Unix (см. ниже).

Если string2 имеет форму /string/, то тогда она интерпретируется, как регулярное выражение. Их синтаксис аналогичен синтаксису регулярных выражений в Unix команде egrep;(см. Регулярные выражения)
(test_condition) — истинно, если test_condition истинно;
! test_condition — истинно, если test_condition ложно;
test_condition1 && test_condition2 — истинно, если как test_condition1, так и test_condition2 истинны;
test_condition1 || test_condition2 — истинно, если хотя бы test_condition1 или test_condition2 истинно.
«=" и "!=" имеют больший приоритет, чем "&&» и «||», а «!» имеет наивысший приоритет.

Все, что не распознаётся, как переменная, считается строкой. Если строка имеет пробелы или символы табуляции, то её надо заключать в кавычки.
О чём стоит помнить, так это о том, что лучше не использовать SSI-команды при создании страниц в редакторах типа Front Page — они их обычно не понимают и выкидывают, и о том, что одну SSI-команду нельзя вызвать из другой (как нельзя вызвать SSI-команду из скрипта, и скрипт из скрипта).

Примеры

Задание сообщения обработчика ошибок

<!--#config errmsg="[При открытии страницы произошла ошибка. Пожалуйста, сообщите об этом владельцу сайта.]" -->

Задание формата вывода даты и времени

<!--#config timefmt="%d/%m/%y" -->           Выведет:  03/07/06
<!--#config timefmt="%d/%m/%Y, %H:%M:%S" --> Выведет:  03/07/2006, 20:16:33

Задание переменных

http://<!--#echo var="HTTP_HOST"--><!--#echo var="DOCUMENT_URI"-->

Выведет: 
http://ru.wikipedia.org/w/index.php?title=SSI_(программирование)

Вставка даты модификации файла

<!--#flastmod file="file.html"-->

Вставка содержимого файла

<!--#include file="footer.html"-->
<!--#include virtual="header.asp"-->
<!--#include virtual="/right.links.txt"--> 

Проверка условия

<!--#if expr="test_condition"-->
<!--#elif expr="test_condition"-->
<!--#else-->
<!--#endif-->