Using Application Display Templates on DXP 7.1

アプリケーション表示テンプレート

決議

序章

アプリケーション表示テンプレートは、サイトテンプレートやページテンプレートと似ていますが、ポートレットレベルで動作します。アプリケーション表示テンプレート (ADT) フレームワークは、ポータル管理者がデフォルトの表示テンプレートを上書きして、サイトコンテンツの表示方法の制限を取り除くことを可能にします。 ADTを使用すると、アセット中心のアプリケーションをレンダリングするために使用されるカスタム表示テンプレートを定義することができます。例えば、ブログのエントリーを縦に表示するのではなく横に表示したり、アセットパブリッシャーポートレットのアセットを異なるサイズで一覧表示したりすることができます。

ユーザーが独自のカスタムフックやポートレットを開発して、パーソナライズされたルックアンドフィールを持つという同じ目標を達成することができますが、デフォルトのアプリケーション表示テンプレートは、箱から出し入れしないという利点があります。デフォルトのフレームワークは、既存の資産で使用するために特別に設計されています。開発者は、既存のAPIとソースコードを独自のADTの基礎として使用することができます。

グローバルコンテキストを選択すると、テンプレートはすべてのサイトで利用可能になりますが、ADTはサイトレベルで含めることができます。 ADTを適用するサイトを選ぶこと。

Compass] アイコンをクリックして、[サイト管理] ドロップダウンリストに移動します。
グローバルコンテキストが選択されている場合、 Build Configuration MenuのApplication Display Templatesページには、利用可能なサンプルテンプレートの一覧が表示されます。
これらのサンプルテンプレートは、アプリ内で既に設定されているデフォルトのテンプレートとは異なります。特定のサイトがテンプレートのホストに選ばれた場合、ユーザーはそのサイトのアプリ用に新しいカスタムテンプレートを作成する必要があります。
Liferay DXP版で新しいテンプレートを作成するには、青いプラスボタンをクリックします。

以下のリストでは、ADTsを使ってカスタマイズできるアプリを指定しています。

アセットパブリッシャー
ブログ
パンくず
カテゴリーナビゲーション
言語セレクタ
メディアギャラリー
ナビゲーションメニュー
RSS発行者
サイトマップ
タグナビゲーション
ウィキ

メディアギャラリーのカスタマイズ

このセクションでは、Media Galleryポートレットでのアプリケーション表示テンプレートの使用について説明します。それ自体、メディアギャラリーは、メインのドキュメントポートレットとは明らかに異なるメディアファイルの保存と表示の方法をユーザーに提供します。デフォルトの見た目はアーカイブのような感じです。 ADTを使用すると、メディアギャラリーはより印象的なものになります。

追加 → ウィジェット → コンテンツ管理 → メディアギャラリーに移動して、メディアギャラリーアプリケーションをページに追加します。
アプリの 追加ボタン > 複数メディア をクリックして、表示するカスタム写真を2枚選択します。次に、 をクリックし、を発行して、メインアプリケーションの画面に戻ります。
写真のデフォルトフォーマットに注意してください。このアプリの表示テンプレートを変更するには、 オプション → 設定に移動します。
表示テンプレート] ドロップダウンメニューから、 カルーセルを選択します。
をクリックして を保存し、設定ウィンドウを閉じます。

図4: カルーセルADTを適用すると、写真がカルーセルのスライドショーとして表示されます。
メディア・ギャラリー・アプリケーションがカルーセル・スライド・ショーに変身しました。

Liferay DXPにバンドルされているアプリのユーザー・インターフェースをカスタマイズすることで、Liferayユーザーに究極のカスタマイズ体験を提供します。

APIを使用して

開発者はAPIを使ってADTを作成することもできます。

アプリケーション表示テンプレート (ADT) ポートレットは、ダイナミックデータマッピングおよびテンプレート API の上に構築されています。
固有のAPI。ADT固有のAPIは非常にシンプルです。これは主に後ほど説明する2つのクラス（PortletDisplayTemplateUtilとBasePortletDisplayTemplateHandler）のみをベースにしています。
サービスAPIです。ADTにはサービスAPIがありませんが（したがって、DB内の特定のテーブルはありません）、DDMのサービスAPIを再利用しています。すべての情報はDDMTemplateテーブルに格納されています。 ADTの場合、DDMTemplateテーブルのclassNameIdフィールドはADTによってレンダリングされるエンティティのものであり(例えばBlogs)、classPKフィールドは0である。
DDMサービスAPIは、プラグインやWebサービスからアクセスすることができます。
テンプレートAPI。ADTは、テーマ、レイアウト、ウェブコンテンツにも使用される既存のFreemarkerとVelocityテンプレートレンダリングAPIを再利用しています。

カスタムADTの作成

ADT APIを活用するには、ユーザーが従う必要があるいくつかのステップがあります。これらのステップには、ポートレットを登録して ADT を使用し、権限を定義し、ユーザーに ADT 機能を公開することが含まれます。以下の手順を使用してください。

カスタムの *PortletDisplayTemplateHandler コンポーネントを作成して登録します。 Liferayは、ユーザーが拡張するためのベースとなる実装として、BasePortletDisplayTemplateHandlerを提供しています。各テンプレートハンドラのメソッドについては、JavadocのTemplateHandlerインターフェイスを確認してください。
Component アノテーションは、プロパティ javax.portlet.name をポートレットのポートレット名として設定して、ハンドラを特定のポートレットに結びつけます。ポートレットクラスにも同じプロパティがあるはずです。例えば
```
	@Component(
		immediate = true,
		property = {
			"javax.portlet.name="+ AssetCategoriesNavigationPortletKeys.ASSET_CATEGORIES_NAVIGATION
		},
		service = TemplateHandler.class
	)
	
```
このクラスの各メソッドは、カスタム・ポートレットのADTの定義と実装において重要な役割を持っています。 ADTに特化して定義された各メソッドの詳細な説明は以下のリストをご覧ください。

getClassName(): ポートレットがレンダリングしているエントリのタイプを定義します。
getName(): ADT型の名前を宣言します (典型的にはポートレットの名前)。
getResourceName(): どのリソースが許可チェックにADT(ポートレットなど)を使用しているかを指定します。このメソッドは、ポートレットの完全修飾ポートレット ID (FQPI) を返す必要があります。
getTemplateVariableGroups(): テンプレートエディタで公開されている変数を定義します。

*PortletDisplayTemplateHandler の実装例として、WikiPortletDisplayTemplateHandler.javaを参照してください。

ADTを追加する機能はポートレットには新しいものなので、管理ユーザーが表示テンプレートの作成と管理を許可されるロールに権限を与えることができるように権限を設定します。レガシーポータル 6.2 では、アクション・キー ADD_PORTLET_DISPLAY_TEMPLATE をポートレットの /src/main/resources/resource-actions/default.xml ファイルに追加します。

	<?xml version="1.0"?>
	<!DOCTYPE resource-action-mapping PUBLIC "-//Liferay//DTD Resource Action Mapping 7.0.0//EN" "http://www.liferay.com/dtd/liferay-resource-action-mapping_7_0_0.dtd">
		vresource-action-mapping>

    ...

    		< portlet-resource >
        		<portlet-name> yourportlet </portlet-name>
        		<permissions>
            		<supports>
                		<action-key> ADD_PORTLET_DISPLAY_TEMPLATE </action-key>
                		<action-key>ADD_TO_PAGE </action-key>
                		<action-key>CONFIGURATION </action-keyv
               	 	<action-key>VIEW </action-key>
            	</supports>
            	</permissions>
    		</portlet-resource>

    ...
		</resource-action-mapping>

ポートレットが正式に ADT をサポートするようになった今、他のユーザーに ADT オプションを公開してください。ポートレットの設定を制御するために使用する JSP ファイルにタグを含めるだけです。

例えば、設定JSPファイルにを挿入すると便利かもしれません。
```
	<aui:fieldset>
		<div class="display-template">
        	<liferay-ddm:template-selector
            		classNameId="<%= YourEntity.class.getName() %>"
            		displayStyle="<%= displayStyle %>"
            		displayStyleGroupId="<%= displayStyleGroupId %>"
            		refreshURL="<%= PortalUtil.getCurrentURL(request) %>"
            		showEmptyOption="<%= true %>"
        	/>
		</div>
	</aui:fieldset>
	
```
このJSPでは、タグは、ポートレットの設定メニューで使用する表示テンプレートのドロップダウンメニューを指定します。変数 displayStyle と displayStyleGroupId は、ポートレットがこのタグlibとポートレットは BaseJSPSettingsConfigurationAction または DefaultConfigurationActionを使用します。それ以外の場合は、これらのパラメータの値を取得し、設定クラスに手動で格納します。
JSPの例として、Wikiアプリケーションの configuration.jspを参照してください。
ユーザーは、選択した ADT でポートレットをレンダリングするために、ビューコードを拡張する必要があります。これにより、ユーザーはビューのどの部分が ADT によってレンダリングされ、何がテンプレート・コンテキストで利用可能になるかを決めることができます。

まず、ADTに必要なJava変数を初期化します。
```
	<%
	String displayStyle = GetterUtil.getString(portletPreferences.getValue("displayStyle", StringPool.BLANK));
	long displayStyleGroupId = GetterUtil.getLong(portletPreferences.getValue("displayStyleGroupId", null), scopeGroupId);
	%>
	
```
次に、ADTが設定されているかどうかをテストし、レンダリングされるエンティティを取得し、ADTを使用してレンダリングします。タグ <liferay-ddm:template-renderer> はこのプロセスを支援します。これは自動的に選択されたテンプレートを使用するか、テンプレートが選択されていない場合はそのボディをレンダリングします。
以下に、これを実装する例のコードを示します。
```
<liferay-ddm:template-renderer
    className="<%= YourEntity.class.getName() %>"
    contextObjects="<%= contextObjects %>"
    displayStyle="<%= displayStyle %>"
    displayStyleGroupId="<%= displayStyleGroupId %>"
    entries="<%= yourEntities %>"
>

    <%-- The code that will be rendered by default when there is no
    template available should be inserted here. --%>

</liferay-ddm:template-renderer>
```
このステップでは、ユーザーは表示設定を扱う変数(displayStyle と displayStyleGroupId)を初期化し、以下に示す他のパラメータと共にタグに渡しました。

className: エンティティのクラス名。

contextObjects: Map<String, Object> に、ユーザーが望む任意のオブジェクトをテンプレートコンテキストに渡すことができます。

エントリ: エンティティのリストを受け付けます (例: リスト<YourEntity>)。

これを実装する例については、 configuration.jspを参照してください。
このカスタムポートレットの動作を見るために、ユーザーは新しいカスタムテンプレートを作成し、Wikiポートレットを修正することができます。
1. Liferay DXPのユーザーは、左側のサイドメニューのサイト管理 > 構成 > アプリケーション表示テンプレートをクリックすることができます。
2. 追加をクリック > ${your template}
3. テンプレートエディタで、テンプレートに名前を付けます。
4. エディタにFreeMarkerまたはVelocityのコードを入力します。サンプルです。
```
			<#if entries?has_content>
				Quick List:
				<ul>
				<#list entries as curEntry>
					<li>${curEntry.name} - ${curEntry.streetAddress}, ${curEntry.city}, ${curEntry.stateOrProvince}</li>
    				</#list>
    			</ul>
			</#if>
			
```
5. カスタムポートレットに移動し、オプション > 構成を選択します。 表示テンプレート ドロップダウンをクリックします。カスタムADTを選択し、[保存]をクリックします。

テンプレートのエクスポートとインポート

ユーザーは、アプリケーションの表示テンプレートをあるサイトから別のサイトにLAR形式でエクスポートしたり、インポートしたりするオプションがあります。これは非常に簡単にできます。それにもかかわらず、LARはLiferayの同じメジャーバージョンでしかインポートできないことに注意してください（例：6.1のLARは6.2にはインポートできず、6.2のLARはLiferay DXPにはインポートできません）。

エクスポートするアプリケーション表示テンプレートを選択します。
3つのドット（オプション）メニューをクリックします。
エクスポート] をクリックします。
LARに名前を与えます。 Wiki ADT1 またはデフォルトの名前を使用します。
デフォルト設定を使用してエクスポートをクリックします。
LARをダウンロードしてください。
テンプレートをインポートするサイトに移動します。
3つのドット（オプション）メニューをクリックします。
インポートをクリックします。
LARをドラッグ＆ドロップするか、ファイルエクスプローラを使用します。
インポート画面が表示されるまで、初期設定のままで続行します。
インポートをクリックします。テンプレートが正常にインポートされたことを確認します。第2サイトにADTが登場しました。

既知の問題とトラブルシューティング

ADTの安全性は？

Javaセキュリティの面では、ユーザーはテンプレート・コンテキストからいくつかのクラスやパッケージを非表示にしたいかもしれません。 Liferay はいくつかのポータルシステム設定を提供しています。Liferay DXP では、コントロールパネル > 設定 > システム設定 > ファンデーション > FreeMarker/Velocity Engine に移動して、制限されたクラス、パッケージ、および変数を定義します。特に、ユーザーは、FreeMarkerとVelocity Engine Restricted変数に割り当てられたデフォルト値のリストに、 serviceLocator を追加したいと思うかもしれません。

どんなパフォーマンスチューニングが必要なのか？

ポートレットがレンダリングされると、アプリケーションの表示テンプレートを使用すると、追加の処理タスクが導入されます。 Liferayのベストプラクティスでは、カスタムテンプレートを可能な限り最小限にし、より複雑な操作に既存のAPIを使用することを提案しています。利用者は、最終的な目標とサーバ負荷に対する期待値を評価する必要があります。ユーザーは、独自のパフォーマンステストを実行する必要があります。最後に、ユーザーは、Systems Settings > Foundation > Freemarker/Velocity Engine に移動し、Resource Modification チェックフィールドを設定することで、テンプレートキャッシュを調整することができます。

DXP 7.1でのアプリケーション表示テンプレートの使用