SharePoint デザイン マネージャー表示テンプレート

  • [アーティクル]

重要

この拡張オプションは、従来の SharePoint エクスペリエンスにのみ使用できます。 コミュニケーション サイトのような、SharePoint Online の最新エクスペリエンスではこのオプションを使用できません。 従来の環境やこれらのブランディング手法を使用することはお勧めしません。

表示テンプレートについて説明します。表示テンプレートが検索 Web パーツとどのように関係しているか、どのようにテンプレートが構成されているか、プロパティのマップ方法および変数と jQuery の使用方法、および SharePoint のカスタム表示テンプレートを作成する方法を説明します。

表示テンプレートの概要

SharePoint の表示テンプレートは、検索テクノロジ (この記事では検索 Web パーツと呼びます) を使用して、検索インデックスに対して実行されたクエリの結果を表示するために使用されるテンプレートです。 表示テンプレートでは、検索結果に表示する管理プロパティと、そのプロパティの Web パーツ内での表示方法を制御します。 各表示テンプレートは、2 つのファイルで構成されています。1 つは、HTML エディターで編集できる HTML バージョンの表示テンプレートです。もう 1 つは、SharePoint で使用される .js ファイルです。

注:

表示テンプレートを使用できるのは Search Web パーツのみです。 コンテンツ クエリ Web パーツは検索駆動型ではないため、表示テンプレートは使用されません。

デザイン マネージャーで既存の表示テンプレートを表示することはできますが、マスター ページおよびページ レイアウトを作成する方法で、表示テンプレートをデザイン マネージャーで作成することはありません。 代わりに、以下の操作を実行します。

  • マスター ページ ギャラリーにマップされたネットワーク ドライブを開きます。.

  • 表示テンプレート フォルダー内にある 4 つのフォルダーのいずれかを開きます。

    注:

    選択するフォルダーは、使用する表示テンプレートの種類によって決まります。 たとえば、サイトでクロスサイト発行を使用する場合は、コンテンツ Web パーツ フォルダーから表示テンプレートをコピーします。 詳細については、「SharePoint の表示テンプレート リファレンス」を参照してください。

  • 目的のものに類似している既存の表示テンプレートの HTML ファイルをコピーします。 ファイルのコピー先は、 マスター ページ ギャラリー内であれば場所は問いません。

  • HTML エディターで、コピーを開いて変更します。

既存の表示テンプレートを新しい表示テンプレートの出発点として使用すると、既定の表示テンプレートのコメントのカスタマイズ プロセスに関する役立つ情報を利用でき、マッピング入力フィールドなどの基本的なタスク用のフレームワークが用意されています。 また、テンプレートが正しい基本的なページ構造を使用することも保証されます。

マスター ページ ギャラリー で Display Templates フォルダー内の既存の表示テンプレートの HTML ファイルをコピーして、表示テンプレートを作成すると、以下の処理が行われます。

  • 同じ名前の .js ファイルが HTML ファイルをコピーした場所に作成されます。

  • 表示テンプレートが正しく表示されるように、SharePoint で必要になるすべてのマークアップが .js ファイルにコピーされます。

  • HTML ファイルと .js ファイルが関連付けられます。これにより、HTML ファイルに対する以降のすべての編集が、HTML ファイルの保存時に .js ファイルに同期されるようになります。

注:

同期は一方向にのみ行われます。 HTML 表示テンプレートに対する変更が、関連付けられた .js ファイルに同期されます。 マスター ページおよびページ レイアウトとは異なり、表示テンプレートを操作する際に、ファイル間の関連付けを解除して .js ファイルのみを操作することを選択することはできません。 HTML ファイルにすべての HTML および JavaScript を入力する必要があります。

表示テンプレートと検索 Web パーツの間のリレーションシップについて

表示テンプレートには、以下の 2 つの主要な種類があります。

  • コントロール テンプレートは、 結果の表示方法の全体的な構造を決定します。 リスト、ページングを含むリスト、スライド ショーが含まれます。

  • 項目テンプレートは、 セット内の各結果の表示方法を決定します。 画像、テキスト、ビデオ、その他の項目が含まれます。

これらの表示テンプレートとその他の表示テンプレートの詳細については、「 SharePoint でのテンプレートの表示リファレンス」を参照してください。

検索 Web パーツ (コンテンツ検索 Web パーツなど) をページに追加した後、Web パーツを構成するには、図 1 に示すように、コントロール表示テンプレートとアイテム表示テンプレートの両方を選択します。

図 1. コンテンツ検索 Web パーツのツール ウィンドウ

コンテンツ検索 Web パーツのツール ウィンドウ

コントロール表示テンプレートは、検索結果を表示する方法の全体的なレイアウトを構成する HTML を提供します。 たとえば、コントロール表示テンプレートには、見出しおよびリストの始まりと終わりの HTML が用意されている場合があります。 コントロール表示テンプレートは、Web パーツで一度だけレンダリングされます。

アイテム表示テンプレートには、結果セット内の各アイテムを表示する方法を決定する HTML があります。 たとえば、アイテム表示テンプレートは、画像、およびそのアイテムに関連付けられたさまざまな管理プロパティにマップされる 3 行のテキストを含んだリスト アイテムの HTML を提供するかもしれません。 アイテム表示テンプレートは、結果セット内の各アイテムに対して 1 回レンダリングされます。 したがって、結果セットに 10 個のアイテムが含まれる場合、アイテム表示テンプレートは HTML のそのセクションを 10 回作成します。

図 2 に示すように、この方法でコントロール表示テンプレートとアイテム表示テンプレートを一緒に使用すると、テンプレートが結合されて、1 つのまとまりある HTML ブロックとして HTWeb パーツにレンダリングされます。

図 2. コントロール表示テンプレートとアイテム表示テンプレートを合わせた HTML 出力

コントロール表示テンプレートとアイテム表示テンプレートを合わせた HTML 出力

表示テンプレートの詳細については、「 SharePoint ページ モデルの概要」の「検索駆動型 Web パーツと表示テンプレート」セクションを参照してください。

表示テンプレートの構造について

表示テンプレートに使用される HTML ファイルは、完全に形成された HTML ドキュメントですが、完全な HTML Web ページを表すものではありません。 SharePoint は、表示テンプレート HTML ファイルの各部分を JavaScript に変換します。 このセクションでは、表示テンプレートの 4 つの主なセクションについて説明します。

Title タグ

表示テンプレート ファイルの <title> タグ内のテキストは、検索 Web パーツが編集モードのときに、Web パーツ編集ウィンドウの [表示テンプレート] セクションの表示名として使用されます。 次に、Item_Picture3Lines.html という名前のアイテム表示テンプレートの場合の例を示します。


<title>Picture on left, 3 lines on right</title>

ヘッダーのプロパティ

<title> タグの直後には、次に示すマークアップで囲まれたカスタム要素のセットが配置されます。

<!--[if gte mso 9]><xml>
<mso:CustomDocumentProperties>
…
</mso:CustomDocumentProperties>
</xml><![endif]-->

これらの要素およびそのプロパティは、表示テンプレートに関する重要な情報を SharePoint 環境に提供します。 表 1 は、表示テンプレートで使用されるカスタム プロパティを示しています。

注:

すべての表示テンプレートですべてのカスタム プロパティが使用されるとは限りません。 また、デザイン マネージャーで表示テンプレート ファイルのプロパティを編集することによって変更できるプロパティもあります。

表 1. CustomDocumentProperties エントリのリスト

プロパティ 説明
TemplateHidden
Web パーツで使用可能なテンプレートの一覧から表示テンプレートを非表示にするかどうかを示すブール値。 この値は、表示テンプレート ファイル プロパティで変更できます。
ManagedPropertyMapping
検索結果アイテムによって公開されるフィールドを、JavaScript で使用可能なプロパティにマップします。 アイテム テンプレートでのみ使用されます。
MasterPageDescription
表示テンプレートのわかりやすい説明を提供します。 これは、SharePoint 編集環境のユーザーに対して表示されます。 この値は、表示テンプレート ファイル プロパティで変更できます。
ContentTypeId
表示テンプレートに関連付けられたコンテンツ タイプの ID。
TargetControlType
表示テンプレートが使用されるコンテキストを示します。 この値は、表示テンプレート ファイル プロパティで変更できます。
HtmlDesignAssociated
表示テンプレート HTML ファイルに .js ファイルが関連付けられているかどうかを示すブール値。
HtmlDesignConversionSucceeded
変換プロセスが正常に完了したかどうかを示します。 この値は、SharePoint によって自動的にファイルに追加され、カスタムの表示テンプレートでのみ使用されます。
HtmlDesignStatusAndPreview
HTML ファイルへの URL、および [ 状態] 列のテキスト ([ 正常に変換されました] または [ 警告とエラーが発生しています]) が含まれます。 この値は、SharePoint によって自動的にファイルに追加され、カスタムの表示テンプレートでのみ使用されます。

スクリプト ブロック

<body> タグの内側には、次に示す <script> タグが配置されています。


<script>
     $includeLanguageScript(this.url, "~sitecollection/_catalogs/masterpage/Display Templates/Language Files/{Locale}/CustomStrings.js");
</script>

既定では、この行がすべての表示テンプレートに含まれています。 <script> タグの内側には、メインの表示テンプレート HTML ファイルの外部にある CSS ファイルや別の JavaScript ファイルを参照するためのコード行を追加できます。 「表 2」に、その他のリソースを含める方法の例を示します。

表 2. スクリプト> タグに外部リソースを<含める例

含めるファイル 使用するコード
現在のサイト コレクションに含まれる JavaScript ファイル
 $includeScript(this.url, "~sitecollection/_catalogs/masterpage/Display Templates/Content Web Parts/MyScripts.js");
外部 JavaScript ファイル
 $includeScript(this.url, "http://www.contoso.com/ExternalScript.js");
現在のサイト コレクションに含まれる CSS ファイル
 $includeCSS(this.url, "~sitecollection/_catalogs/masterpage/Display Templates/Content Web Parts/MyCSS.css");
現在の表示テンプレートの相対位置にある CSS ファイル
 $includeCSS(this.url,"../../MyStyles/MyCSS.css");

注:

マスター ページ ギャラリー内のアイテムにコンテンツの承認が必要な場合、すべてのリソース ファイル (CSS ファイルと .js ファイルを含む) をマスター ページとページ レイアウトで使用できるようにするには、まず、それらを発行しておく必要があります。 詳細については、「サイトまたはライブラリのアイテムの承認を必須にする」を参照してください。

DIV ブロック

<script> タグの後ろには、ID を持つ <div> タグがあります。 既定では、この <div> タグの ID は、HTML ファイルの名前と一致します。 表示テンプレートで指定する HTML またはコードは、この <div> タグの内側に含める必要があります。 ただし、このタグ自体は、実行時に Web ページに表示されるマークアップに含まれません。

注:

実行時にページに表示される HTML のブロックに CSS スタイルまたは ID を割り当てる場合は、最初の <div> タグの内側に新しいタグを追加できます。 また、コントロール テンプレートで、変数 _#= ctx.RenderGroups(ctx) =#_ を囲む HTML に CSS スタイルまたは ID を割り当てることもできます。 変数 _#= ctx.RenderGroups(ctx) =#_ は、アイテム テンプレートで表示されるクエリ結果を囲む HTML を表示するために使用されます。

最初<の div> タグには、!--#_ で<始まり、_#-->で終わるコメント ブロック内のコードが表示されます。 このブロックの内側で JavaScript コードを使用し、ブロックの外側で HTML を使用します。 また、このブロックは、条件付きステートメントで HTML を制御するために使用することもできます。 このようにするには、条件ステートメントと左かっこを含むコメント ブロックを使用し、その後に HTML を配置して、その後で右かっこを含む別のコメント ブロックを使用します。 次に示す例では、linkURL オブジェクトの値が空でない場合にのみ、ページにアンカー タグが表示されます。


<!--#_
if(!linkURL.isEmpty)
{
_#-->
     <a class="cbs-pictureImgLink" href="_#= linkURL =#_" title="_#= $htmlEncode(line1.defaultValueRenderer(line1)) =#_" id="_#= pictureLinkId =#_">
<!--#_
}
_#-->

入力プロパティのマッピングとその値の取得

アイテム表示テンプレートのヘッダー セクションには、 ManagedPropertyMapping という名前のカスタムのドキュメント プロパティがあります。 このプロパティは、検索で使用される管理プロパティを受け取り、表示テンプレートで使用できる値にそれらのプロパティをマップします。 このプロパティは、' プロパティ表示名'{ プロパティ名}:' 管理プロパティ' の形式を使用するコンマ区切りの値のリストです。 たとえば、「 'Picture URL'{Picture URL}:'PublishingImage;PictureURL;PictureThumbnailURL' 」のように入力します。

この形式についてさらに詳しく説明します。

  • プロパティ表示名は、表示テンプレートが選択されたときに Web パーツ編集ウィンドウに表示されるプロパティ名です。

  • プロパティ名は、ローカライズされた文字列リソースを使用して管理プロパティの名前を検索する識別子です。 これは、Web パーツ設定メニューの [プロパティ マッピング ] セクションに表示される値でもあります。 Web パーツの設定を編集するときに、この値を変更して、Web パーツに表示されるフィールドに関連付けられている管理プロパティを変更できます。

  • 管理プロパティは、セミコロンで区切られた 1 つ以上の管理プロパティの文字列です。 実行時に、リストが左から右へと評価され、現在の検索アイテムの管理プロパティの名前と一致する最初の値が見つかると、その値がこのスロットにマップされます。 これにより、複数の種類のアイテムを操作でき、互換プロパティが存在する場合に一貫したレンダリングを使用できる、表示テンプレートを記述することができます。

プロパティをマップした後、次のコードを使用してスクリプトでその値を取得できます。 var pictureURL = $getItemValue(ctx, "Picture URL");

$getItemValue() に渡される 2 つ目のパラメーターは、 ManagedPropertyMapping 要素で使用される一重引用符内のプロパティ表示名と一致する必要があります。 この例では、 Picture URL が $getItemValue() に渡されるプロパティ名です。

このコードは、値情報オブジェクト ( valueInfoObj) を返します。 このオブジェクトには、入力値の生の表示と、既定のエンコードが適用された値が含まれます。

JavaScript のセクション内の変数を通常どおりに使用して、変数を操作し、実行時にページ上にレンダリングされる HTML 文字列を作成することができます。 ただし、スクリプトで宣言された変数を HTML 内で直接参照するには、形式: #= variableName =# を使用する必要があります。 たとえば、イメージの値として変数 pictureURL を使用する場合、HTML: <img src="_#= pictureURL =#_" /> を使用します。

表示テンプレートでの jQuery の使用

表示テンプレートでは jQuery を使用することができます。 ただし、以下の 2 つの重要な要因に注意してください。

  • 表示テンプレートに jQuery ライブラリを含めるには、この記事で前述した「スクリプト ブロック」セクションの手順に従います。

  • jQuery で ID セレクターを使用する場合は、次のコードを使用して ID の変数を作成します。 var containerQueryId = '#' + '_#= containerId =#_';

    jQuery でセレクターを参照するには、次のコードを使用します。 $('_#= containerQueryId =#_')

表示テンプレートの作成

以下の手順を使用して表示テンプレートを作成するには、まず、 マスター ページ ギャラリーを示すようにマップされたネットワーク ドライブが必要です。 詳細については、「 方法: ネットワーク ドライブを SharePoint マスター ページ ギャラリーにマップする」を参照してください。

表示テンプレートを作成するには

  1. Windows エクスプローラーを使用して、 マスター ページ ギャラリーにマップされたネットワーク ドライブを開きます。

  2. 表示テンプレート フォルダーを開いて、コンテンツ Web パーツ フォルダーを開きます。

  3. 作成するものに近い内容の表示テンプレート用の HTML ファイルをコピーします。 既定の表示テンプレートとその説明の一覧については、「 SharePoint でのテンプレートの表示リファレンス」を参照してください。

    この時点で、SharePoint によって、HTML ファイルが同じ名前の .js ファイルにコピーされます。 たとえば、コピーした HTML ファイルの名前が Item_Picture3Line_copy.html の場合、それに対応する Item_Picture3Lines_copy.js という名前の .js ファイルも作成されます。 ファイルの名前を変更する場合は、対応する .js ファイルの名前も変更します。

  4. 表示テンプレートをカスタマイズするには、HTML エディターを使用して、マップされたドライブ内の HTML ファイルを開いて編集して、サーバー上に置かれている HTML ファイルを編集します。 HTML ファイルを保存するたびに、関連付けられた .js ファイルにすべての変更が同期されます。

  5. 発行サイトに移動します。

  6. ページの右上隅で [ 設定] を選択し、[ デザイン マネージャー] を選択します。

  7. デザイン マネージャーの左側のナビゲーション ウィンドウで、[ 表示テンプレートを編集する] を選択します。 HTML ファイルが表示され、[ 状態] 列には次の 2 つの状態のどちらかが表示されます。

  • 警告とエラーが発生しています

  • 正常に変換されました

    注:

    マスター ページやページ レイアウトとは異なり、プレビュー ページを使用して、表示テンプレートの現在のサーバー側プレビューを表示することはできません。 表示テンプレートをプレビューするには、コンテンツ検索 Web パーツをページに追加し、[コンテンツ検索 Web パーツの編集] ウィンドウで表示テンプレートを適用する必要があります。 表示テンプレートにエラーがある場合は、コンテンツ検索 Web パーツにエラー メッセージが表示されます。 表示テンプレートを正しく表示するには、まずエラーを修正する必要があります。

  1. エラーを修正するには、HTML エディターを使用して、マップされたドライブ上の HTML ファイルを開いて編集することにより、サーバー上に置かれている HTML ファイルを編集します。 表示テンプレートを保存し、表示テンプレートを使用する Content Search Web パーツを含むページを再読み込みします。

関連項目