ウェブデザインとプログラムのナインマイルズ

s9yドキュメント

Smarty特有のテンプレート操作・プラグインの機能

※訳者注：このセクションは、訳者の理解度が低いため日本語訳が非常に曖昧です。

  1. このセクションのオリジナルドキュメント
  2. ..（テクニカルドキュメント）
  3. プラグイン
  4. モディファイア
  5. PHPコードの挿入
  6. エントリ内のSmartyとPHPのマークアップ
  7. カスタムフィールド
  8. 外部サイトにエントリを表示させる

プラグイン

あらゆるSmartyの .tlpファイル内で特定のプラグインを手動で実行できます。
使えるSmartyの関数は以下の通りです： 

[FETCHING]
category:
(int 整数型)
取得したいエントリのカテゴリID (";"を使って複数IDを区切れます)

viewAuthor:
(int 整数型)
取得したいエントリの著者ID (";"を使って複数IDを区切れます)

page:
(int 整数型)
ページ分けするエントリのページ数

id:
(int 整数型)
エントリのID。もし指定すればそのエントリひとつだけを取得します。
空のままだと、複数のエントリが取得されます。

range:
(mixed 多様型)
エントリの取得を特定の期間に限定します。
結果はタイプによって変わります：

 Numeric 数値:
  YYYYMMDD - YYYY年MM月DD日のエントリを全て表示します。
  DDが "00" の場合、該当月の全エントリを表示します。
  DDが何か他の数字だった場合、その日にあたるエントリを表示します。

 2-Dimensional Array 2次元配列:
  Key #0   - 取得初めのタイムスタンプ (UNIXタイム)
  Key #1   - 取得終了のタイムスタンプ (UNIXタイム)

 その他 (null、3-dimensional Array 3次元配列 など):
  $modified_since によって取得されるものよりも新しいエントリ。

full
(boolean 論理型)
完全なエントリが取得できるかどうかを示します (本文＋拡張本文：TRUE)
または本文のみ (FALSE)

limit
(string 文字列)
どのエントリを取得すればいいのかを示す文字列 "Y" または "X, Y" が有効です。
X は最初のエントリのオフセット値で、Y はエントリの数です。
セットされなかった場合は、一般的な制限数が適用されます (デフォルトでは15エントリ)。

fetchDrafts
(boolean 論理型)
草稿を取得するかどうかを (TRUE) またはそうでないかで示します。

modified_since
(int 整数型)
$rangeと共に使われるUNIXタイムスタンプを保持していて、
このタイムスタンプよりも新しいエントリを取得します。

orderby
(string 文字列)
SQL文の "ORDER BY" 実行文を保持しています。

filter_sql
(string 文字列)
エントリーをとって来るために主要なSQL実行文に挿入するための
どんなSQLコードも含むことができます。

noCache
(boolean 論理型)
TRUEなら全てのエントリーが最初から取得され、キャッシュは無視されます。

noSticky
(boolean 論理型)
TRUEなら全ての固定エントリは取得されせん。

select_key
(string 文字列)
どのキーを選択するかのSQLステートメントを含むことができます。
プラグインでもこれを設定できますが注意が必要です!

group_by
(string 文字列)
どうグループ分けして問い合わせるかのSQLステートメントを含むことができます。
プラグインでもこれを設定できますが注意が必要です!

returncode
(string 文字列)
"array" にした場合、エントリの配列が返ってきます。
"flat-array" の場合、エントリのプロパティ無しで記事を返すだけです。
"single" の場合一次元配列を返します。
"query" の場合、使われたSQLを返します。

joinauthors
(bool 論理型)
SQL-joinをデータベースのAUTHORSテーブルにするべきか？

joincategories
(bool 論理型)
SQL-joinをデータベースのCATEGORIESテーブルにするべきか？

joinown
(string 文字列)
問い合わせに "JOIN" を付け足すSQLパーツ

entryprops
(string 文字列)
表示されるべきエントリの、カンマで区切られたプロパティの状態一覧
例："ep_CustomField='customVal',ep_CustomField2='customVal2'"
(s9yのバージョン1.3以上で利用可能)

[PRINTING]
template:
(string 文字列)
エントリーを表示するためのテンプレートファイルの名前

preview:
(boolean 論理型)
プレビューであるかどうかを示します。

block
(string 文字列)
パースするSmartyブロックの名前

use_hooks
(boolean 論理型)
フッタとヘッダにイベントフックを適用するかどうかを示します。

use_footer
(boolean 論理型)
ページネーションにフッタを表示するかどうかを示します。

groupmode
(string 文字列)
TRUEの場合、Smartyの$entries出力配列への備えとして、
入力された$entries配列が既にグループ化されているかどうかを示します。
FALSEの場合、日付でグループ化されます。

skip_smarty_hooks
(boolean 論理型)
TRUEの場合、プラグインは全く実行されないでしょう。

skip_smarty_hook
(mixed 多様型)
実行しないプラグインフックの配列に設定できます。

prevent_reset
(boolean 論理型)
TRUEの場合、Smartyの$entries配列は初期化されないでしょう。
(起こり得るエントリの重複出力を防ぐため)

モディファイア

今のところ次のモディファイアが利用できます：

PHPコードの挿入

各テンプレートはそのディレクトリ内に特別なファイルconfig.inc.phpを持つことができます。
このファイルは標準テンプレートには通常存在しません。 ただし、PHPで特別な操作を行うために、あなたのテンプレートディレクトリに追加することができます。
Serendipity 0.7ではコードをlayout.phpの中に直接書くことができましたが、今ではそのファイルは取り除かれたので、今、PHPコードは別の場所 (config.inc.php) に書く必要があります。

Smartyフレームワークが生成された後すぐに、config.inc.phpファイルがSerendipityから実行されます。
これは、あなたがSmartyフレームワークのものを変更するために、あなたの好きなどんなPHPコードもこの時点で入れることができることを意味します。

例えばこのコードで、あなたはSmartyモディファイアを自分で作成できます。 

<?php
$serendipity['smarty']->register_function('my_custom_function',
 'my_custom_function');

function my_custom_function($params, &$smarty) {
    return 'I customized this: ' . $params['stuff'];
}
?>

それを使用することによって、あなたはすべての.tplファイルの中でその登録された機能にアクセスできるでしょう。 SmartyのAPIについてはSmartyのドキュメントを見てください。

config.inc.phpファイルはまた、何か出力が表示される前に実行させたいような、他のいかなるコードのためにも利用できます。

Serendipityページ内に何か外部のPHPスクリプトを挿入したいなら、テンプレートファイルである*.tpl内でSmartyの {include_php} 関数が使えます。
include_php関数はSmartyのSecure Modeでは使えないので、あなたのテンプレートのconfig.inc.phpファイルに以下を加えてSecure Modeを無効にする必要があります： 

<?php
$serendipity['smarty']->security = false;
?>

(<?php ?> タグがあなたのconfig.inc.phpファイルに既に存在しているのなら除外してください)

いったんセキュアモードを無効にすると、使用できます。 

{include_php file="/path/to/your/custom.php"}

例えば、出力が必要なあらゆる場所のindex.tplファイルの中に。

あなたのページに外部のPHPスクリプトを表示させるために挿入したいのなら、スパルタカスを通して利用可能なExternal PHPかWrap URLのイベントプラグインを使うことを考えてください。 または、自分で簡単なプラグインを作るのも、もちろん結構です。 これに関する詳しい情報については、プラグインAPIドキュメントに進んでください。

エントリ内のSmartyとPHPのマークアップ

マークアップ：Smartyプラグインは、Smartyが提供するパワーを使って、エントリにSmartyマークアップを挿入できるようにします。 大きいセキュリティリスクを負うので、エントリ内のPHPは許可されません。

もちろん、あなたのPHPコードを記入するには、上述のようにconfig.inc.phpファイルのメソッドを使用できます! これでエントリーの中でコードを再度使用できます。

ですからあなたが実行したいPHPコードの my_magic_function() は宣言できますし、もしconfig.inc.phpファイルに関数を登録していれば、エントリの中で再度使用できます。

カスタムフィールド

Serendipity 0.9では、エントリ内に表示可能なカスタムフィールドを定義することができます。

例えば、Listening、Playingという名の二つのカスタムフィールドを作ることができるということです (フィールド名に空白や特殊文字を使わないで下さい)。
エントリを作成し、これら二つのフィールドに値を入れてください。 そして entries.tpl を編集し、Smartyのコードを書きます。

listeningにはこう：{$entry.properties.ep_Listening}

Playingにはこう：{$entry.properties.ep_Playing}

エントリのループ内の好きなところで結構です。
プロパティのキー名にはプレフィクスとして ep_ を忘れずにつけます。 これで、あなたが設定した場所にこれらのフィールドがあるのを確認できるでしょう。
また、変数が空かどうかをチェックするためにSmartyマークアップを適用することもできますし、出力部分を囲むDIVなどのタグを追加することもできます。

あなたが実際に作ったカスタムフィールドを表示したくなく、でも代わりにそこに自作のプラグインで中身を挿入したい場合、前述のようにカスタム関数を呼び出すか、またはあなたのプラグインで $entry['properties'] 配列を新しいコンテンツに挿入してください。

あなたのプラグインは、取得されたエントリ ('entry_display' か 'frontend_display' か、または 'frontend_entryproperties') のイベントの一つにだけフックできるので、$eventDataプロパティのインデックスをあなたが後で表示させたい部分に設定してください。
あなたのテンプレートが既に上記のディスプレイコードを含むとき、ただあなたのカスタムプラグインからの新しい $entry['properties'] のデータを選んで、それを表示するでしょう。 まるであなたがエントリー作成画面で入力したように。

外部サイトにエントリを表示させる

外部にあるあなたのウェブサイトでPHPが有効になっていて、Serendipityがファイルシステムにアクセスできるのなら、その一部をSrendipityのエントリに表示させるのは非常に簡単にできます。

次のようなPHPコードを使って、Serendipityフレームワークにインクルードすれば、エントリを表示するためにSerendipityのAPIを使うことができます： 

<?php
// 1: Serendipityへのパスに移動します。
// s9yフレームワークが相対的に呼び出しできるようにchdirを使う必要があります。
chdir('/home/www/public_html/blog/');

// 2: Serendipity APIを起動します。
include 'serendipity_config.inc.php';

// 3: Smartyのテンプレートを起動します。
serendipity_smarty_init();

// 4: 最終エントリを取得します。
$entries = serendipity_fetchEntries(null, true,1);

// 5: 全ての変数をSmartyに挿入します。
serendipity_printEntries($entries);

// 6: テンプレートファイルを取得します。
$tpl = serendipity_getTemplateFile('entries.tpl', 'serendipityPath');

// 7: エントリ出力を成形します。
$serendipity['smarty']->display($tpl);

// 8: 最初の地点に戻ります。
chdir('/home/www/public_html/');
?>

あなたのニーズに合わせて、serendipity_fetchEntries()か serendipity_printEntries()のそれぞれコールを使い分けることができます。
もちろん serendipity_getTemplateFile()コールのために、entries.tplではなく他のテンプレートファイルを渡すこともできます。 PHPアプリケーション内であなたのエントリ用のカスタムレイアウトを持てたり、Serendipity内でデフォルトのentories.tplを使ったりできるのと同じです。

可能なコマンドについては、Srendipityのインストールファイルの include/functions_entries.inc.phpを開いて、あなたが使うことができるパラメータがどれなのか、関数の上部に書いてあるphpDocコメントを見て調べてください。

Serendipity