Using Application Display Templates on Liferay DXP 7.0

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

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

Globalコンテキストを選択すると、テンプレートはすべてのサイトで利用できますが、ADTはサイトレベルで含めることができます。 ADTを適用する部位を選択するため：

Compass アイコンをクリックして、Site Administration ドロップダウンリストに移動します。
グローバル］コンテキストを選択すると、［サイト管理］の［設定］メニューの［アプリケーション表示テンプレート］ページに、利用可能なサンプルテンプレートのリストが表示されます。
これらのサンプルテンプレートは、すでにアプリに設定されているデフォルトのテンプレートとは異なります。特定のサイトがテンプレートのホストとして選ばれた場合、ユーザーはそのサイトのアプリ用に新しいカスタムテンプレートを作成する必要があります。
Liferay DXP 版で新しいテンプレートを作成するには、灰色のプラスボタンをクリックします。

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

アセットバプリッシャー
ブログ
パンくずリスト
カテゴリーナビゲーション
ドキュメントとメディア
言語選択
ナビゲーションメニュー
RSS パブリッシャー
サイトマップ
タグナビゲーション
Wikiノード

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

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

Add > Applications > Content Management > Media Galleryに移動して、Media Gallery アプリケーションをページに追加します。
アプリの 追加ボタン > 複数メディア をクリックし、表示するカスタムフォトを2枚選択します。その後、「 保存」をクリックし、アプリケーションのメイン画面に戻ります。
写真のデフォルトのフォーマットに注目してください。このアプリの表示テンプレートを変更するには、 オプション > 設定に移動してください。
表示テンプレート」ドロップダウンメニューから、「 カルーセル」を選択します。その後、保存をクリックします。

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

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

APIの利用

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

Application Display Templates（ADT）ポートレットは、Dynamic Data Mapping APIとTemplates APIの上に構築されています。
固有のAPIです：ADT固有のAPIは非常にシンプルです。主に2つのクラス（PortletDisplayTemplateUtilとBasePortletDisplayTemplateHandler）のみをベースにしています。
サービスAPI：ADTはサービスAPIを持たないが（したがって、DBに特定のテーブルがない）、DDMのサービスAPIを再利用する。すべての情報は DDMTemplate テーブルに格納されます。 ADTの場合、DDMTemplateテーブルのclassNameIdフィールドはADTでレンダリングされるエンティティ（Blogなど）のものであり、classPKフィールドは0です。
DDMサービスAPIは、プラグインやWebサービスからアクセスすることができます。
テンプレートAPI：ADTは、テーマ、レイアウト、ウェブコンテンツに使用されている既存のFreemarkerとVelocityのテンプレートレンダリングAPIを再利用します。

カスタムADTを作成する

ADT APIを活用するためには、ユーザーがいくつかのステップを踏む必要があります。 ADTを使用するポートレットの登録、権限の定義、ユーザーへのADT機能の公開など、これらの手順が含まれます。次の手順で使用します：

*PortletDisplayTemplateHandler のカスタムコンポーネントを作成し、登録します。 Liferayは、ユーザーが拡張するための基本実装として、 BasePortletDisplayTemplateHandler を提供しています。各テンプレートハンドラメソッドについては、 TemplateHandler インタフェースのJavadocを確認してください。
Component 注釈は、ポートレットのポートレット名としてプロパティ javax.portlet.name を設定して、ハンドラを特定のポートレットに結びつけます。同じプロパティがポートレットクラスにもあるはずです。以下に例を示します。

	@Component(
		immediate = true,
		property = {
			"javax.portlet.name="AssetCategoriesNavigationPortletKeysASSET_CATEGORIES_NAVIGATIONserviceTemplateHandlerclasspreEachofthemethodsinthisclasshaveasignificantroleindefiningandimplementingADTsforthecustomportletViewthelistbelowforadetailedexplanationforeachmethoddefinedspecificallyforADTsbrbrbgetClassNamebDefinesthetypeofentrytheportletisrenderingbrbgetNamebDeclaresthenameoftheADTtypetypicallythenameoftheportletbrbgetResourceNamebSpecifieswhichresourceisusingtheADTegaportletforpermissioncheckingThismethodmustreturntheportletsFullyQualifiedPortletIDFQPIbrbgetTemplateVariableGroupsbDefinesthevariablesexposedinthetemplateeditorliolAsanexamplecodePortletDisplayTemplateHandlercodeimplementationlookatWikiPortletDisplayTemplateHandlerjavaolliSincetheabilitytoaddADTsisnewtotheportletconfigurethepermissionssothatadministrativeuserscangrantpermissionstotherolesthatwillbeallowedtocreateandmanagedisplaytemplatesOnlegacyPortal62addtheactionkeycodeADD_PORTLET_DISPLAY_TEMPLATEcodetotheuportletsusrcmainresourcesresourceactionsdefaultxmlfilepreltxmlversion"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 は、このタグリブを使用するときにポートレットが保存する環境設定で、ポートレットは 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> に、ユーザーが望む任意のオブジェクトをテンプレート・コンテキストに追加して受け付ける。
entries: エンティティのリストを受け取ります（例： List<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をDXPにインポートすることはできません）。

エクスポートするアプリケーション表示テンプレートを選択します。
三点鎖線（オプション）メニューをクリックします。
エクスポートをクリックします。
LAR に名前を付ける： Wiki ADT1 またはデフォルトの名前を使用します。
Export をデフォルトの設定でクリックします。
LARをダウンロードします。
テンプレートをインポートするサイトへ移動します。
三点鎖線（オプション）メニューをクリックします。
インポートをクリックします。
LARをドラッグ＆ドロップするか、ファイルエクスプローラーを使用します。
インポート画面まで、初期設定を使い続けます。
インポートをクリックします。テンプレートが正常にインポートされたことを確認します。第2サイトではADTを公開中です。

よくある質問とトラブルシューティング

ADTのセキュリティはどうなっていますか？

Javaのセキュリティに関しては、ユーザーはテンプレート・コンテキストから一部のクラスやパッケージを隠したい場合があります。また、ユーザーはADTがポータルで実行できる操作を制限することができます。 Liferay はいくつかのポータルシステム設定を提供します。DXP では、コントロールパネル > 設定 > システム設定 > Foundation > FreeMarker/Velocity Engine に移動し、制限されたクラス、パッケージ、変数を定義します。特に、FreeMarkerとVelocity Engine Restrictedの変数に割り当てられるデフォルト値のリストに、serviceLocatorを追加したい場合があります。

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

ポートレットがレンダリングされる際、アプリケーション表示テンプレートを使用すると、追加の処理タスクが発生します。 Liferayのベストプラクティスでは、カスタムテンプレートはできるだけ少なくし、より複雑な操作には既存のAPIを使用することを推奨しています。ユーザーは、最終的なゴールとサーバー負荷に対する期待を評価する必要があります。ユーザーも独自のパフォーマンステストを実施する必要があります。最後に、ユーザーは、システム設定 > Foundation > Freemarker/Velocity Engineに移動して、Resource Modificationチェックフィールドを設定することで、テンプレートキャッシュを調整できます。

Liferay DXP 7.0でのアプリケーション表示テンプレートの使用について

目次

紹介