高度なカスタマイズ
動画用DBフィールドとリストフィルタ
はじめに
INTER-STREAMでは動画用のカスタムデータベースフィールドとリストフィルタを使用できます。これにより、より高度なカスタマイズが可能です。特定のプロジェクトのために追加の動画データ構造を処理する必要があるユーザーに最適です。
新しいフィールドがデータベースの"clips"テーブルに追加されたら、それに対応するリストフィルタを定義する必要があります。これには設定ファイル(config/Config.inc.php)を編集して、変数を追加しなければなりません。
実際の例を使用して説明します。
1. データベースの修正
例えばDBの動画テーブルにカスタムの"country"というフィールドを追加したい場合、追加フィールド名には"x_"などのセキュリティ接頭辞を付けてください。これはINTER-STREAMの今後のバージョンとの"衝突"を避けるためです。
今回の場合、追加する新しいカスタムフィールドは"x_country"という名前になります。
2. フィールドの指定
カスタムフィールドが動画テーブルに追加されたら、DBを操作するときにカスタムフィールドを処理する必要があることをシステムに通知しなくてはなりません。
これは、フィールド名をインデックス、データ配列を値として持つ新しい連想配列を追加することによって、変数（連想配列）$CUSTOM_DB_FIELDS["clips"]を通しておこなわれます。
例）
"clips"テーブルに "x_country"という名前の文字列/テキストフィールド(CHAR, VARCHAR, TEXT, etc.)を追加したとします。この場合、設定ファイル(config/Config.inc.php)で以下のように指定する必要があります。
$CUSTOM_DB_FIELDS["clips"]["x_country"] = array ( "data_type" => "plain_text", // フィールドに格納されているデータの種類。オプション："number"(数字),"plain_text"(通常テキスト),"html"(HTMLテキスト),"timestamp"(タイムスタンプ) "default_val" => "", // フィールドが定義されていない場合、または動画の作成/編集/更新時に指定されていない場合のデフォルト値（必要に応じて"NULL"にできます） 。DBにデータを挿入するために必要です。 "output_formatting" => "no", // テンプレートに表示する際フォーマットする必要があるかどうかを地域設定に従って指定します。オプション："no"(そのまま表示),"date"(時間なしの日付),"number"(10進数ではない数字),"decimal"(10進数の数字),"time"(時間),"datetime"(日時) );
新しいフィールドが定義されるとバックエンドの動画編集ページ/テンプレート、及び動画の表示に使用されるフロントエンドのページ/テンプレートで使用できるようになります。
以下のラベルを使用してください。
{k.html.x_country_formatted} -> フォーマットされた値を表示
{k.html.x_country_escaped} -> 値をそのまま出力しますが、（二重）引用符をエスケープします（avascript文字列変数内で値を使用する必要がある場合など）。
さらに、新しいフィールドは"clips > get"のAPI関数の結果にも含まれるようになります。
3. バックエンドのフォーム項目の編集
新しいフィールドを入力して保存できるようにするため、バックエンドの動画編集テンプレートを変更して新しいフォーム要素を追加します。
例）
新しい項目「国（"country"）」を選択するためのドロップダウンメニュー（<select>タグ）を追加し、それを「説明文」フィールドの上に表示させたい場合、 public/backend/admin_clip_edit.tplテンプレートファイルを以下のように編集します。
<div class="formRow">
<label for="x_country">Country:</label>
<select name="x_country" id="x_country" class="formField fieldSelect">
<option value="">-Select-</option>
<option>France</option>
<option>Portugal</option>
<option>Spain</option>
<option>United Kingdom</option>
<option>United States</option>
</select>
</div>
<script>
$("#x_country").val("{k.html.x_country_escaped}");
/* DBに格納されている値がドロップダウンリストで選択されます */
</script>
<!-- ここまで追加 -->
<!-- ここから説明文フィールド -->
<div class="formRow">
<label for="item_description">...
重要：追加されたフォームコンポーネントの検証
手動で追加したフィールドは、組み込みのJavascript検証機能の処理対象外となります。その為、同じテンプレートで定義されている必要があるカスタムJavascript関数を使用して、ユーザー入力を検証する必要があります。
「ユーザーが[保存する]ボタンをクリックしたときに最終検証を実行し、新しいフィールドが検証されなれければ送信を停止する」という処理をおこなう場合、"validateCustomFields()"というJavaScript関数を定義してtrueまたはfalseを返す必要があります。その戻り値に関して、メインフォームは送信を続けるか停止します。
この処理を補完するものとして、検証関数は検証されていないフォーム要素(input,textarea,select...)に"error"というCSSクラスを追加できます。これはフォーム要素を赤で強調表示するようにします。また、更にエラーメッセージを表示する必要がある場合は組み込み関数"showResultMessage()"を使用できます。
検証機能の例）
<script>
function validateCustomFields()
{
$("#x_country").removeClass("error");
if($("#x_country").val()=="")
{
$("#x_country").addClass("error");
showResultMessage("Oops, you must select a country","error",5000); // 数値はメッセージがページ内で表示される時間（ミリ秒）
return false;
}
return true;
}
</script>
これで動画を編集して「国（"country"）」を割り当てることができるようになりました。
注：
1.ページやテンプレートに表示される値はJavascript文字列の中の値になります。念の為、ラベル"{k.html.x_country_escaped}"を使用することをお勧めします。
2.チルダ(~)などの特殊文字が正しく表示されない場合はテンプレートファイルのエンコードをUTF-8に変換してください。
3.テンプレートファイル"public/backend/admin_clip_edit_auto_encoding.tpl"（オートエンコーディング動画に適用）に対しても上記の手順を繰り返す必要があります。
4. 動画ページにフィールドの値を表示する（フロントエンド）
新しいフィールドの値を表示するために、動画を表示する際に使用するフロントエンドテンプレートを変更します。
例）
動画のカテゴリーの上、説明の下の部分に「国（"country"）」を表示させたい場合は、デフォルトの動画テンプレートファイル（V2テーマの場合は"public/frontend/v2/clip.tpl"）の"<div class="itemCategoriesTitle" ..."の前に以下の行（青色&赤色の文字列）を追加します。
<div class="itemCategoriesTitle" ...
2. 原則として、フィールドの値がHTML/Javascriptの引用符付き文字列内で使用されない場合は、ラベルを表示するために"_formatted"というラベルを使用する必要があります。
5. フィールドの値をリストで表示する（フロントエンド）
1. フィールドの指定
新しいフィールドを検索などのリストとして表示させたい場合は、設定ファイル(config/Config.inc.php)に変数（連想配列）"$CUSTOM_DB_FIELDS_LIST_INCLUSION["clips"]"を追加し、カスタムフィールドのリストを配列に代入します。
$CUSTOM_DB_FIELDS_LIST_INCLUSION["clips"] = array("x_country"); // 動画リストに含まれるカスタムフィールド（1つ以上）
2. フィールド値の表示
フロントエンドテンプレートの対応するループ構造に、適切なラベルを追加します。
例）
動画の検索結果のリストページで「再生数("views")」の下に新たに「国（"country"）」のフィールド値を表示させたい場合、動画/チャンネル/ページを一覧表示するために使用されるテンプレートファイル（V2テーマの場合は"public/frontend/v2/search_results.tpl"）の"<div class = "views ..."の後に以下の行（青色&赤色の文字列）を追加します。
<div class="xCountry custom dim">{k.lang.country}: {k.loop.value.item_x_country_formatted}</div>
</div>
"public/frontend/v2/search_results.tpl"は動画/チャンネル/ページの一覧表示をおこなう際に使用されるテンプレートです。
その為、追加したブロックが動画の場合にのみ表示されるようにするにはWebの先頭にJSおよびCSSコードを追加する必要があります。
以下のコードを管理インタフェースの[一般設定＞一般＞HTMLコード]の「
<script>
if (
window.location.href.indexOf("/searchChannel/")>1 ||
window.location.href.indexOf("portal/channels")>1 ||
window.location.href.indexOf("/channels/")>1 ||
window.location.href.indexOf("/searchPage/")>1 ||
window.location.href.indexOf("portal/pages")>1 ||
window.location.href.indexOf("/pages/")>1
)
{ $("html").addClass("channels"); }
</script>
<style>
.channels .xCountry { display:none; }
</style>
6. 検索フィルタ
カスタムフィールド用の検索フィルタを作成する必要がある場合は設定ファイル(config/Config.inc.php)で定義します。
フィルタ名を指定してから、それぞれに対応する関数を作成します。
1. フィルタの作成：名前の指定
フィルタの名前は変数（連想配列）"$CUSTOM_DB_FIELDS_LIST_FILTERS["clips"]"で指定され、利用可能なフィルタ（名前）のリストを持つ配列を割り当てます。
$CUSTOM_DB_FIELDS_LIST_FILTERS["clips"] = array("xCountryFilter"); // 新しいフィルタの名前のリストを含む配列。これらはPOSTまたはGET変数として渡されます。
2. フィルタの作成：機能の定義
名前が指定されたら、それぞれの機能を定義します。
フィルタ関数は、動画を一覧表示するSQLクエリに含まれる追加のSQL句を生成します。
関数は以下のように定義されています（設定ファイル(config/Config.inc.php)にもあります）。
例）「国（"country"）」フィールド
function custom_db_fields_list_filter_clips_xCountryFilter()
{
// For this example, the filter will restrict the list of Clips according with the country value
// The input value should be found in a GET or POST var
// NOTE: GET and POST vars are automatically "sanitized" by the system
$input_value = "";
if ( isset($_POST["xCountryFilter"])) $input_value = $_POST["xCountryFilter"];
else if ( isset($_GET["xCountryFilter"])) $input_value = $_GET["xCountryFilter"];
// Prepare the return array with default values (all blank)
$clauses=array(
"query_select_field" => "", // Ej. "other_table.x_another_field_name" -> Leave blank if you don't need to select data from other table(s) different from "clips"
"query_select_from" => "", // Ej. "other_table" -> Leave blank if you don't need to operate on other table(s) different from "clips"
"query_select_where" => "" // Ej. "clips.xCountryFilter = '%$input_value%'"
);
// Validate the input value and generate the additional (SQL) query clauses
if ($input_value!='')
{
$clauses["query_select_where"]= " clips.x_country LIKE '%$input_value%' ";
}
return $clauses;
}
注：この関数の名前は「"custom_db_fields_list_filter_clips_"プレフィックス」 + 「フィルタ名」のようになります。
これでフィルタが作成され、"xCountryFilter"のPOSTまたはGET変数が検索フォーム或いはAPI Clip list関数（clips > list）へ渡された時に、フィルタがリストに適用されます。
3. APIでフィルタを使用する
API Clip list関数（clips > list）でフィルタを使用するには、単にPOST変数としてフィルタの名前を渡します。
4. 既存の動画検索フィルタに新しいフィルタを追加する（フロントエンド）
例）
動画検索ページ（フィルタセクション）に新たに「国（"country"）」のフィルタを追加したい場合、フィルタ検索に使用されるテンプレートファイル（V2テーマの場合は"public/frontend/v2/inc_search_filters_clips.tpl"）の"<form name = "filterForm"..."の後（任意の場所）に以下の行（青色&赤色の文字列）を追加します。
{k.lang.fe.country}
<select name="xCountryFilter" id="xCountryFilter" class="filterField">
<option value="">{k.lang.fe.filter_any}</option>
<option>France</option>
<option>Portugal</option>
<option>Spain</option>
<option>United Kingdom</option>
<option>United States</option>
</select>
</div>
<script>
$("#xCountryFilter").val("{k.html.xCountryFilter_escaped}"); /* これにより現在のフィルタ値を選択できます */
</script>
注：
1.ページやテンプレートに表示される値はJavascript文字列の中の値になります。念の為、ラベル"{k.html.xCountryFilter_escaped}"を使用することをお勧めします。
2.チルダ(~)などの特殊文字が正しく表示されない場合はテンプレートファイルのエンコードをUTF-8に変換してください。
3."{k.lang.fe....}"のようなラベルはフロントエンドの言語設定に従ってテキストを表示します。
7. 連想/結合フィールド
連想/結合フィールドは、動画テーブルのフィールドと他のテーブルのフィールドとの間の「結合」の結果であるものです。
例で説明すると、"x_country"フィールドには国コード（ES、FR、GBなど）が格納され、実際の国名はDBの別のテーブルに指定されています。
SQL句の追加についての詳細は、お問い合わせください。