Share UIカスタマイズの第一歩

第39回 Alfresco勉強会

Share UIカスタマイズの第一歩

2017年6月21日Moritaka Soma

自己紹介

相馬盛孝オープンソースコンサルティングチーム所属Alfrescoのカスタマイズやサポートをしています最近はVR技術に興味があります

本日の発表内容

本日の発表内容:

これからAlfresco ShareのUIカスタマイズを行おうと考えている方のとっかかりとなりそうな初歩的内容をご紹介

• Surf Extension Modulesの紹介• Share Headerのカスタマイズ• 簡単なUI挙動の変更

環境

環境:

Alfresco SDK 3.0 (All-In-One Project)

• Alfresco Platform 5.2.e

• Alfresco Share 5.2.d

＊共にAlfresco SDK 3.0のデフォルトで選択されているバージョンです

Alfresco SDKの使い方については割愛します…

環境

現状のAlfresco SDK 3.0 AIOの注意点:

Share Servicesが適用されているのに、「Alfresco is running without Share Services.

See your System Administrator for more details.」というメッセージが出てしまう。https://github.com/Alfresco/alfresco-sdk/issues/445

src/test/resources/share/share-config-custom.xmlの<endpoint-url>${alfresco.repo.url}/alfresco/api</endpoint-url> を<endpoint-url>${alfresco.repo.url}/api</endpoint-url> と修正することで対処可能です。

http://ja.wikipedia.org/wiki/%E3%83%95%E3%83%AA%E3%83%BC%E3%82%BD%E3%83%95%E3%83%88%E3%82%A6%E3%82%A7%E3%82%A2

Surf Extension Modules

Surf Extension Modulesとは？：

Surf Extension Modules are the main tool

to use when adding, updating, or hiding content

in the Share User Interface (UI). ** http://docs.alfresco.com/5.2/concepts/dev-extensions-share-surf-extension-modules.html

意訳：Share UIで、要素の追加・更新・削除（隠蔽）カスタマイズを行う上でのメインツール


Surf Extension Modules：RuntimeにModuleデプロイの有効/無効を切り替えることが可能です。http://<host>:<port>/share/page/modules/deploy

デバッグやテストの際、便利です。


Alfresco SDKでは<artifactId>-share-jar/src/main/resources/alfresco/

web-extension/site-data/extensions

フォルダにモジュール定義のxmlを配置します。

例: custom-header-extension-modules.xml<extension>

<modules>

<module>

<id>Custom Share Header Menu</id>

<version>1.0</version>

<auto-deploy>true</auto-deploy>

<customizations>

<customization>

<targetPackageRoot>org.alfresco.share.header</targetPackageRoot>

<sourcePackageRoot>jp.aegif.share.header</sourcePackageRoot>

</customization>

</customizations>

</module>

</modules>

</extension>


モジュール定義の説明::

<customizations>

<customization>



</customization>

</customizations>

:

この例では、Alfresco ShareのWEB-INF/classes/alfresco/site-webscripts/org/alfresco/share/header/

以下に配置される、WebScriptのjavascriptに対して、Alfresco SDK上で<artifactId>-share-jar/src/main/resources/alfresco/web-extension/

site-webscripts/jp/aegif/share/header/

以下の、同名のjavascriptファイルを追加して実行することで、カスタマイズを行う定義となります。

他にも様々な定義を行うことができますが、今回は割愛します…

Share Headerのカスタマイズ

Share Header：

比較的カスタマイズの要望が多い部分です。

• 不要なメニュー項目を隠したい• ワークフローは使わないのでタスク項目を隠したい• SSOを使うので明示的にログアウトさせたくない

• よく使う項目を追加したい• ごみ箱へ1クリックで移動したい

• 検索フィールドのメッセージが中途半端なので修正したいetc…


カスタマイズ方法：

Share HeaderはAikauのWidgetとして実装されているため、Share HeaderのWebScriptが作成するオリジナルのWidget

モデルを、Surf Extension Modulesを利用して変更することでカスタマイズを行います。

Share Header

WebScript

Original

Widget

モデル

Surf Extension

Module

作成変更

Customized

Widget

モデル


対象Widgetの調査：

ShareでClient Debug Modeを有効＊にし、Debug Menuの「Toggle Developer View」で、対象項目を調べるのが簡単です。アイコンをクリックすることで、WidgetのIDと取得のための

Snippetを確認できます。＊SDKから起動した場合Client Debug Modeは有効化されています。


Surf Extension Module作成：Share Headerのモデルを返すWebScriptのJavascriptはWEB-INF/classes/alfresco/site-webscripts/org/alfresco/share/header/share-header.get.js

なので、以下のSurf Extension Moduleを作成。

<artifactId>-share-jar/src/main/resources/alfresco/web-extension/site-data/extensions

custom-header-extension-modules.xml :

<extension>

<modules>

<module>

<id>Custom Share Header Menu</id>

<version>1.0</version>

<auto-deploy>true</auto-deploy>

<customizations>

<customization>



</customization>

</customizations>

</module>

</modules>

</extension>


項目の消去：Share Headerのモデルを修正するJavascriptは

<artifactId>-share-jar/src/main/resources/alfresco/web-extension/site-webscripts

/jp/aegif/share/header/share-header.get.js

として、以下の内容で作成します。

// Hide Task Menu Item

widgetUtils.deleteObjectFromArray(model.jsonModel, "id", "HEADER_TASKS");

widgetUtils.deleteObjectFromArray()という便利ユーティリティが使えるので、IDが判れば簡単に消去することが可能です。


項目の追加：ShareのHeaderを返すWebScriptは

<artifactId>-share/WEB-INF/classes/alfresco/site-webscripts/org/alfresco/

share/header/share-header.get.js

このファイルでimportされている、<artifactId>-share/WEB-INF/classes/alfresco/site-webscripts/org/alfresco/

share/imports/share-header.lib.js の中で

function generateAppItems() {

var appItems = [

{

id: "HEADER_HOME",

name: "alfresco/menus/AlfMenuBarItem",

config: {

id: "HEADER_HOME",

label: "header.menu.home.label",

targetUrl: getUserHomeTargetUrl()

}

},

:

:

このような感じで、メニューの内容をJSONとして定義しているので参考にします。


項目の追加：オリジナルのJSON定義を参考にして、Share Headerのモデルを修正するJavascriptに以下の内容を追加します。

// Add Trash-can to Header Menu Items

var headerMenu = widgetUtils.findObject(model.jsonModel, "id", "HEADER_APP_MENU_BAR");

if (headerMenu != null) {

headerMenu.config.widgets.push({

id: "HEADER_CUSTOM_TRASH_CAN_LINK",

name: "alfresco/menus/AlfMenuBarItem",

config: {

label: "ごみ箱",

targetUrl: "user/" + encodeURIComponent(user.name) + "/user-trashcan"

}

});

}


検索フィールドのカスタマイズ：検索フィールドのWidgetを調べると

alfresco/header/SearchBoxというWidgetであることが分かる

Alfresco ShareのソースコードからこのWidgetを調べると、aikau-1.0.101.3.jar に含まれるMETA-INF/js/aikau/1.0.101.3/alfresco/header/SearchBox.js

がWidgetの実体であることがわかる。


alfresco/header/SearchBox：実体のjavascriptファイルを確認すると、

/**

* The placeholder text to set in the main input field.

*

* @instance

* @type {string}

* @default

*/

placeholder: "search.instruction",

/**

* @instance

* @type {boolean}

* @default

*/

liveSearch: true,

文言やLiveSearchの有効/無効設定がプロパティになっていて、config経由で設定できることが分かる


検索フィールド文言の変更：Share Headerのモデルを修正するJavascriptに以下の内容を追加する。

// Change Search Placeholder Message

widgetUtils.findObject(model.jsonModel, "id", "HEADER_SEARCH").config.placeholder = "検索";

*本来は表示したい文言をメッセージとして定義し、そのkeyを指定します。


検索フィールドLiveSearchの停止：Share Headerのモデルを修正するJavascriptに以下の内容を追加する。

// Disable Live Search

widgetUtils.findObject(model.jsonModel, "id", "HEADER_SEARCH").config.liveSearch = false;

デモ

ご質問など

ありがとうございました。

Software

Share UIカスタマイズの第一歩