SSI 的指令及參數

SSI 在使用時遵循以下格式：

<!--#directive parameter="value"-->

其中，directive 是向伺服器發送的指令名稱，parameter 是指令的操作對象，而 value 則是使用者希望得到的指令處理結果。

所有的 SSI 指令都是以 "<!--#" 開始，其中 "<!-" 和 "#" 之間不能有任何空格，否則伺服器會把 SSI 指令當稱普通的檔案注釋處理，不會顯示出任何結果，也不會産生錯誤提示。此外，SSI 指令中的 "=" 兩邊不能有空格，右邊的值必須包含在雙引号内，後面可以跟空格，最後是結束标簽 "-->"。

SSI 指令包含六大類指令以及各自的參數，具體如下：

指令及參數

指令名稱 參數清單

Config errmsg, timefmt, sizefmt

include virtual, file

echo var

fsize file

flastmod file

exec cmd, cgi

下面我們将逐一進行介紹。

Config 指令

Config 指令主要用于修改 SSI 的預設設定。其中：

Errmsg：設定預設錯誤資訊。為了能夠正常的傳回使用者設定的錯誤資訊，在 HTML 檔案中 Errmsg 參數必須被放置在其它 SSI 指令的前面，否則用戶端隻能顯示預設的錯誤資訊，而不是由使用者設定的自定義資訊。

<!--#config errmsg="Error! Please email [email protected] -->

Timefmt：定義日期和時間的使用格式。Timefmt 參數必須在 echo 指令之前使用。

<!--#config timefmt="%A, %B %d, %Y"-->

<!--#echo var="LAST_MODIFIED"-->

顯示結果為：

Wednesday, April 12, 2000

也許使用者對上例中所使用的 %A %B %d 感到很陌生，下面我們就以表格的形式總結一下 SSI 中較為常用的一些日期和時間格式。

Sizefmt：決定檔案大小是以位元組、千位元組還是兆位元組為機關表示。如果以位元組為機關，參數值為 "bytes"；對于千位元組和兆位元組可以使用縮寫形式。同樣，sizefmt 參數必須放在 fsize 指令的前面才能使用。

<!--#config sizefmt="bytes"-->

<!--#fsize file="index.html"-->

Include 指令

Include 指令可以把其它文檔中的文字或圖檔插入到目前被解析的文檔中，這是整個 SSI 的關鍵所在。通過 Include 指令隻需要改動一個檔案就可以瞬間更新整個站點！

Include 指令具有兩個不同的參數：

Virtual：給出到伺服器端某個文檔的虛拟路徑。例如：

<!--#include virtual="/includes/header.html"-->

File：給出到目前目錄的相對路徑，其中不能使用 "../"，也不能使用絕對路徑。例如：

<!--#include file="header.html"-->

這就要求每一個目錄中都包含一個 header.html 檔案。

Echo 指令

Echo 指令可以顯示以下各環境變量：

DOCUMENT_NAME：顯示目前文檔的名稱。

<!--#echo var="DOCUMENT_NAME"-->

index.html

DOCUMENT_URI：顯示目前文檔的虛拟路徑。例如：

<!--#echo var="DOCUMENT_URI"-->

/YourDirectory/YourFilename.html

随着網站的不斷發展，那些越來越長的 URL 位址肯定會讓人頭疼。如果使用 SSI，一切就會迎刃而解。因為我們可以把網站的域名和 SSI 指令結合在一起顯示完整的 URL，即：

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

QUERY_STRING_UNESCAPED：顯示未經轉義處理的由用戶端發送的查詢字串，其中所有的特殊字元前面都有轉義符 "\"。例如：

<!--#echo var="QUERY_STRING_UNESCAPED"-->

DATE_LOCAL：顯示伺服器設定時區的日期和時間。使用者可以結合 config 指令的 timefmt 參數，定制輸出資訊。例如：

<!--#config timefmt="%A, the %d of %B, in the year %Y"-->

<!--#echo var="DATE_LOCAL"-->

Saturday, the 15 of April, in the year 2000

DATE_GMT：功能與 DATE_LOCAL 一樣，隻不過傳回的是以格林尼治标準時間為基準的日期。例如：

<!--#echo var="DATE_GMT"-->

LAST_MODIFIED：顯示目前文檔的最後更新時間。同樣，這是 SSI 中非常實用的一個功能，隻要在 HTML 文檔中加入以下這行簡單的文字，就可以在頁面上動态的顯示更新時間。

除了 SSI 環境變量之外，echo 指令還可以顯示以下 CGI 環境變量：

SERVER_SOFTWARE：顯示伺服器軟體的名稱和版本。例如：

<!--#echo var="SERVER_SOFTWARE"-->

SERVER_NAME：顯示伺服器的主機名稱，DNS 别名或 IP 位址。例如：

<!--#echo var="SERVER_NAME"-->

SERVER_PROTOCOL：顯示用戶端請求所使用的協定名稱和版本，如 HTTP/1.0。例如：

<!--#echo var="SERVER_PROTOCOL"-->

SERVER_PORT：顯示伺服器的響應端口。例如：

<!--#echo var="SERVER_PORT"-->

REQUEST_METHOD：顯示用戶端的文檔請求方法，包括 GET，HEAD，和 POST。例如：

<!--#echo var="REQUEST_METHOD"-->

REMOTE_HOST：顯示送出請求資訊的用戶端主機名稱。

<!--#echo var="REMOTE_HOST"-->

REMOTE_ADDR：顯示送出請求資訊的用戶端IP位址。

<!--#echo var="REMOTE_ADDR"-->

AUTH_TYPE：顯示使用者身份的驗證方法。

<!--#echo var="AUTH_TYPE"-->

REMOTE_USER：顯示通路受保護頁面的使用者所使用的帳号名稱。

<!--#echo var="REMOTE_USER"-->

Fsize 指令

Fsize 顯示指定檔案的大小，可以結合 config 指令的 sizefmt 參數定制輸出格式。

<!--#fsize file="index_working.html"-->

Flastmod 指令

Flastmod 顯示指定檔案的最後修改日期，可以結合 config 指令的 timefmt 參數控制輸出格式。

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

這裡，我們可以利用 flastmod 參數顯示出一個頁面上所有連結頁面的更新日期。方法如下：

<!--#config timefmt=" %B %d, %Y"-->

<A HREF="/directory/file.html">File</A>

<!--#flastmod virtual="/directory/file.html"-->

<A HREF="/another_directory/another_file.html">Another File</A>

<!--#flastmod virtual="/another_directory/another_file.html"-->

File April 19, 2000

Another File January 08, 2000

Exec 指令

Exec 指令可以執行 CGI 腳本或者 shell 指令。使用方法如下：

Cmd：使用 /bin/sh 執行指定的字串。如果 SSI 使用了 IncludesNOEXEC 選項，則該指令将被屏蔽。

Cgi：可以用來執行 CGI 腳本。例如，下面這個例子中使用服務端 cgi-bin 目錄下的 counter.pl 腳本程式在每個頁面放置一個計數器：

<!--#exec cgi="/cgi-bin/counter.pl"-->