SSSp.pm

NAME

SSSp.pm - スタイル切替の為のフレームワーク

SYNOPSIS

use SSSp;
$obj = SSSp->new($conf);

$set_cookie = $obj->make_cookie; # Set-Cookie ヘッダ

$meta = $obj->make_cookie(1); # cookie_tmpl より生成
$link = $obj->make_link;      # link_tmpl より生成

$form = $obj->make_form; # スタイル選択フォーム

DESCRIPTION

サーバサイドで Web ページのスタイルを簡単に切り替えられるようにする為のフレームワークです。

PROPERTIES

本クラスのオブジェクトは以下のインスタンス属性を持ちます。

属性名 デフォルト値
default_style undef
header_indent \n\t
selected_style アクセスメソッドの項を参照
style {}
style_order ASCII 順
cookie_domain $ENV{'SERVER_NAME'}
cookie_expires 30
cookie_flag 0
cookie_name SSSSelectedStyle
cookie_path $ENV{'SCRIPT_NAME'} より取得 or /
cookie_tmpl アクセスメソッドの項を参照
form_ctrl_name SSSStyle
form_replace_words アクセスメソッドの項を参照
form_selected_attr selected="selected"
form_select_tmpl アクセスメソッドの項を参照
form_tmpl アクセスメソッドの項を参照
link_alt_enable 0
link_rel_alt_value Alternate Stylesheet
link_rel_value Stylesheet
link_tmpl アクセスメソッドの項を参照

METHODS

特にことわりがない限り、コンストラクタ new 以外は全てインスタンスメソッドです。

make_cookie

make_cookie([FLAG])

選択されたスタイルをブラウザに保存させる為の Cookie を生成して返します。 FLAG とインスタンス属性 cookie_flag に指定されたフラグ値で生成内容が変わります。

bit OFF ON
3 Set-Cookie Set-Cookie2
2 Weekday Wdy
1 HTTP ヘッダ cookie_tmpl を使用 
# Set-Cookie: style=Foo; expires=Tue, 01-Apr-2003 12:40:05 GMT
print $obj->make_cooke(2);

# <meta http-equiv="Set-Cookie2" content="style=Foo; Max-Age=2592000" />
print $obj->make_cooke(5);

make_form

make_form([WORD => VALUE [, WORD => VALUE [...]]])
make_form([EXPR])

スタイル選択フォームを生成して返します。指定できる引数は form_replace_words メソッドと同等で、 make_form メソッドに渡された値が優先的に使われます。

make_link

make_link

選択されたスタイルを文書にリンクさせる要素を生成して返します。

new

new([KEY => VALUE [, KEY => VALUE [...]]])
new([EXPR])

コンストラクタです。生成するインスタンスに持たせる属性値か、 設定ファイルのパスを引数に与える事ができます。

設定ファイルは Perl スクリプトそのもので、最後に返される値が、 属性名とその値のハッシュリファレンスでなければいけません。 各属性のデフォルト値を最大限利用した、最も単純な設定ファイルは以下のようになります; 

#--- sssp.conf ---
{
    default_style => 'Foo',

    style => {
            Foo => { href => '/~you/css/foo.css' },
            Bar => { href => '/~you/css/bar.css' },
            Baz => { href => '/~you/css/baz.css' },
    },
};
#-----------------

ACCESS METHODS

特にことわりがない限り、以下に挙げる関数は、 同名のインスタンス属性に対する読み書き両用のアクセスメソッドです。 

$obj   = $obj->method($value);
$value = $obj->method;

cookie_domain

cookie_domain([EXPR])

Cookie を適用させるドメインです。 デフォルト値は環境変数 SERVER_NAME の値になります。

a.example.org と b.example.org の両方で利用できる Cookie を出力したい場合、 cookie_domain には .example.org を指定して下さい。

cookie_expires

cookie_expires([EXPR])

Cookie の賞味期限で、単位は日です。 デフォルト値は 30 日です。

cookie_flag

cookie_flag([EXPR])

make_cookie メソッドの FLAG に加えられる値です。 デフォルト値は 0 です。

cookie_name

cookie_name([EXPR])

Cookie に保存するスタイル名のキーです。 デフォルト値は SSSSelectedStyle です。

cookie_path

cookie_path([EXPR])

Cookie を適用させるパスです。 デフォルト値は環境変数 SCRIPT_NAME からプログラム名を除いたものか / になります。

cookie_tmpl

cookie_tmpl([EXPR])

Cookie をエンティティボディ内に出力する際のテンプレートです。 デフォルト値は以下のような XHTML テキストです; 

<meta http-equiv="__NAME__" content="__COOKIE__" />

テンプレート中に含まれる文字列 __NAME__ はインスタンス属性 cookie_name の値に、 __COOKIE__ は生成された Cookie テキストにそれぞれ置換されます。

default_style

default_style([EXPR])

陽に指定されなかった時に適用されるスタイル名です。

form_ctrl_name

form_ctrl_name([EXPR])

クライアントからスタイル名を受け取る際のコントロール名です。 デフォルト値は SSSStyle です。

form_replace_words

form_replace_words([WORD => VALUE [, WORD => VALUE [...]]])
form_replace_words([EXPR])

スタイル選択フォームのテンプレート中に含まれる、 __ で挟まれた文字列 WORD と、 それを置換するテキスト VALUE の設定です。

WORD に使える文字はアルファベットと _ (アンダーバー) のみです。大文字小文字を区別しませんが、 テンプレート中には大文字で記述しなければいけません。 また、アンダーバーは先頭及び末尾には使えず、連続してもいけません。

デフォルトで以下のペアが設定されます;

WORD VALUE
ACTION $ENV{'SCRIPT_NAME'}
METHOD post
CTRL_NAME インスタンス属性 form_ctrl_name
PATH $ENV{'DOCUMENT_URI'}

form_selected_attr

form_selected_attr([EXPR])

スタイル選択フォームでの選択肢で、「選択」状態にする為の文字列です。 デフォルト値は selected="selected" です。

form_select_tmpl

form_select_tmpl([EXPR])

スタイル選択フォームでの選択肢のテンプレートです。 デフォルト値は以下のような XHTML テキストです; 

<option__SELECTED__>__NAME__</option>

テンプレート中に含まれる文字列 __SELECTED__ はインスタンス属性 form_selected_attr の値か空文字列に、 __NAME__ はスタイル名にそれぞれ置換されます。

form_tmpl

form_tmpl([EXPR])

スタイル選択フォームのテンプレートです。 デフォルト値は以下のような XHTML (1.0 Transitional) テキストです; 

<form action="__ACTION__" method="__METHOD__">
    <div>
            <select id="__CTRL_NAME__" name="__CTRL_NAME__">
                    __SELECT__
            </select>
            <input type="hidden" id="from" name="from" value="__PATH__" />
            <input type="submit" value="Apply" />
    </div>
</form>

テンプレート中に含まれる __ で挟まれた文字列は、基本的に インスタンス属性 form_replace_words に指定されたテキストで置換されます。 __SELECT__ はインスタンス属性 form_selected_attr 及び form_select_tmpl の値から生成されたテキストで置換されます。

header_indent

header_indent([EXPR])

インスタンス属性 link_alt_enable の値が真の時、make_link メソッドで複数生成されるリンク要素の間に挟まれる文字列です。 デフォルト値は \n\t です。

link_alt_enable

link_alt_enable([EXPR])

選択されなかったスタイルを、 代替スタイルとしてリンクするか否かの真偽値フラグです。 デフォルト値は 0 (代替スタイルを出力しない) です。

link_rel_alt_value

link_rel_alt_value([EXPR])

スタイルシートをリンクさせる要素で、 代替スタイルシートである事を宣言する為の文字列です。 デフォルト値は Alternate Stylesheet です。

link_rel_value

link_rel_value([EXPR])

スタイルシートをリンクさせる要素で、 適用されるスタイルシートである事を宣言する為の文字列です。 デフォルト値は Stylesheet です。

link_tmpl

link_tmpl([EXPR])

スタイルシートをリンクさせる要素のテンプレートです。 デフォルト値は以下のような XHTML テキストです; 

<link rel="__REL__" href="__HREF__" title="__TITLE__" type="text/css" />

テンプレート中に含まれる __ で挟まれた文字列は、 基本的にインスタンス属性 style で定義された各スタイルの設定値に置換されます。 __REL__ はインスタンス属性 link_rel_value の値か link_rel_alt_value の値に、 __TITLE__ はスタイル名にそれぞれ置換されます。

style メソッドの項も参照して下さい。

selected_style

selected_style([EXPR])

現在選択されているスタイル名です。 陽に設定する前に読み出すと以下の順番で指定を探し、 得た値を設定して返します;

  1. スクリプトの第一引数 ($ARGV[0])
  2. 環境変数 QUERY_STRING
  3. 環境変数 QUERY_STRING_UNESCAPED
  4. 環境変数 HTTP_COOKIE
  5. インスタンス属性 default_style

style

style([NAME => ATTR [, NAME => ATTR [...]]])
style([EXPR])

各スタイルの設定です。

スタイルの定義には、スタイル名 NAME と、 そのスタイルの設定を収めたハッシュリファレンス ATTR のペアを指定します。 

$obj->style(Foo => { href => '/~you/css/foo.css', media => 'screen' });

キー href の値はインスタンス属性 link_tmpl に指定されたテンプレート中の __HREF__ を、 キー media の値は __MEDIA__ を、というように、 それぞれ対応する文字列に当てはめられます。

キーに使える文字はアルファベットと _ (アンダーバー) のみです。大文字小文字を区別しませんが、 テンプレート中には大文字で記述しなければいけません。 また、アンダーバーは先頭及び末尾には使えず、連続してもいけません。

キーが全くないスタイルを定義する事で、「スタイルを使用しない」 という選択肢を作る事ができます; 

$obj->style('No Style' => {});

スタイル名のみ指定して呼び出すと、そのスタイルの全設定を返します。 

%attr = $obj->style('Foo'); # リストで返される
$attr = $obj->style('Foo'); # ハッシュリファレンスで返される

style_order

style_order([LIST])

スタイルシートをリンクさせる要素や、 スタイル選択フォームで各要素を並べる順番です。 デフォルト値はインスタンス属性 style に定義されているスタイル名を ASCII 順に並べたものです。

NOTES

以下は Apache での挙動です。他の httpd ではどうなるか調べていません。

exec cgi では、プログラムのパスに直接クエリを付ける事ができません。 httpd が SSI 文を解釈する時点でエラーにされてしまいます。 include virtual ではこれが可能で、通常通り環境変数 QUERY_STRING を介してデータを受け取る事ができます。 

<!--#exec cgi="./cmd.cgi?foo=bar"-->        <!-- ERROR -->
<!--#include virtual="./cmd.cgi?foo=bar"--> <!-- OK -->

exec cgi でクエリを使って渡すには、SSI 文が埋め込まれている文書自身の URL にクエリを付ける必要があります;

https://example.org/~you/index.shtml?foo=bar

こう指定すれば、exec cgi でも include virtual でも、 環境変数 QUERY_STRING_UNESCAPED からクエリを受け取る事ができます。

exec cgi では文書の URL にクエリを付けた場合、QUERY_STRING_UNESCAPED だけでなく QUERY_STRING の方にも同じ値が入ります。include virtual では文書の URL に付けたクエリは QUERY_STRING_UNESCAPED だけに、 プログラムのパスに付けたクエリは QUERY_STRING だけに入るので、 両方のクエリを使い分けて柔軟に指定できます。また、include virtual は Options +IncludesNoExec 下でも利用できます。

SEE ALSO

本スクリプトは Piro 氏作の CGI-SSS を参考に作成されました。デフォルト値の幾つかは CGI-SSS を意識しています。

CGI-SSS 配布元: outsider reflex

AUTHOR

Copyright © 2003 Yaminusi. <yn@byor.org> All Rights Reserved.

一次配布元: BYOR

本スクリプトは修正 BSD ライセンスにて公開されています。

HISTORY

2003-05-08: v0.0.1
初版公開。