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