AtlassianユーザーインターフェイスでのRESTfulテーブルの実装

それは何ですか？

まったく手掛かりがない人向け：ワークフローを提供する製品（主にJIRAとConfluenceですが、おそらくIT専門家なら誰でも簡単に名前を付けることができる）で知られるAtlassianには、これらの製品のプラグインを開発するためのSDKもあります。 このSDKの一部として開発者が利用できるツールの中には、Atlassian User Interface（AUI）Webインターフェイスを開発するためのサブシステムがあります。 また、AUIの機能には、いわゆるRESTfulテーブルがあります。これは、インタラクティブなテーブルを実装するためのターンキーソリューションであり、すべての変更はRESTサービスのセットを使用してサーバー側でリアルタイムに保存されます。

最近、私はそのようなテーブルを書く必要がありました-その前に私はこれをする必要がなかったので、 公式マニュアルの現在の（AUI 7.6.2）バージョンに目を向けましたが、それは十分ではないことがわかりました。 私は情報を入手しなければなりませんでした-フォーラムとAUI自体のソースコードで、後者が利用可能であるため （そして、ちなみに、RESTfulな作業テーブルの良い例が含まれていますが、残念ながら、詳細なコメントはありません）。 ネットワークで見つかったギャップを埋めるガイドが見つかりませんでした。他の人、そしておそらく自分自身のために、同様のタスクを容易にするために掘り下げたものをまとめたいと思いました。 仕事に基づいて、もちろん、それはまだ公式ガイドに基づいているはずですが、このテキストはおそらく追加されます...いずれにせよ、それが更新されるまで。

製品とバージョン

作業中に、私は使用しました：

• Java 8
• Atlassian Plugin SDK 6.3.6（特に、アセンブリをそれに含まれるMaven 3.2.1のインスタンスにしました）
• JIRA 7.7.0 Core（プラグインはJIRAで作成され、このバージョンでのみテストされました）

問題の声明

したがって、行を追加/削除し、既存の行の内容を変更し、行を交換するには、JIRAのどこかにテーブルを含むページが必要です。 テーブルの内容の変更は、サーバー側のストレージに同期的に記録する必要があります-原則として、これはデータベースまたはその他の不揮発性ソリューションですが、テーブルとサーバー側との相互作用に興味があるため、メモリ内のストレージに制限します-これにより、取得できるようになります以前にテーブルのあるページに戻ってデータを保存しましたが、サーバーの電源を切ったときや、プラグインを再インストールしたときなどは保存しないでください。

準備する

最初に、1つの新しいページ（Apache Velocity形式でページを描画するサーブレットモジュールとします）を含むJIRA用のプラグインを作成します。 JIRAヘッダー内のリンク。 これについては詳しく説明しません-原則として、これらは簡単な操作です。 いずれの場合でも、 Bitbucketで動作するサンプルコードを利用できます 。

実装：フロントエンド

アトラシアンの公式のリーダーシップに基づいて行動しようとします。 まず、ページに通常のHTMLテーブルを追加します。これがRESTfulテーブルになります

<table id="event-rt"></table>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

...プラグイン記述子（atlassian-plugin.xml）のJSスクリプトのweb-resourceモジュールへ-対応するライブラリに依存します：

 <web-resource key="events-restful-table-script" name="events-restful-table-script"> <resource type="download" name="events-restful-table.js" location="/js/events-restful-table.js"/> <dependency>com.atlassian.auiplugin:ajs</dependency> <dependency>com.atlassian.auiplugin:aui-experimental-restfultable</dependency> </web-resource>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

...およびスクリプト自体-既存のテーブルに基づいて、1つの文字列パラメーターを使用した最小のRESTfulテーブルを作成します。

 AJS.$(document).ready(function () { new AJS.RestfulTable({ autoFocus: false, el: jQuery("#event-rt"), allowReorder: true, resources: { all: "rest/evt-restful-table/1.0/events-restful-table/all", self: "rest/evt-restful-table/1.0/events-restful-table/self" }, columns: [ { id: "name", header: "Event name" } ] }); });
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

完了-プラグインをアセンブルすることで、ページに本当に目的のコンテンツの行を追加し、編集、削除、交換できる新しいテーブルがあることを確認できます。 サーバー側では、これらの変更はもちろん修正されていません。

実装：バックエンド

これは私が今やることです。 マニュアルによると、システムに保存されたすべてのデータをテーブルモデル用に提供するRESTリソースと、モデルの特定のインスタンスでCRUD操作を実行できる別のリソース（より正確には、1つのリソースではなく、それらのセット）が必要です。 この場合、1つの一般的なコントローラークラスとデータモデルクラスとして実装します。

 @Consumes({MediaType.APPLICATION_JSON}) @Produces({MediaType.APPLICATION_JSON}) @Path("/events-restful-table/") public class RestfulTableController { private List<RestfulTableRowModel> storage = new ArrayList<>(); @GET @Path("/all") public Response getAllEvents() { return Response.ok(storage.stream() .sorted(Comparator.comparing(RestfulTableRowModel::getId).reversed()) .collect(Collectors.toList())).build(); } @GET @Path("/self/{id}") public Response getEvent(@PathParam("id") String id) { return Response.ok(findInStorage(id)).build(); } @PUT @Path("/self/{id}") public Response updateEvent(@PathParam("id") String id, RestfulTableRowModel update) { RestfulTableRowModel model = findInStorage(id); Optional.ofNullable(update.getName()).ifPresent(model::setName); return Response.ok(model).build(); } @POST @Path("/self") public Response createEvent(RestfulTableRowModel model) { model.setId(generateNewId()); storage.add(model); return Response.ok(model).build(); } @DELETE @Path("/self/{id}") public Response deleteEvent(@PathParam("id") String id) { storage.remove(findInStorage(id)); return Response.ok().build(); } private RestfulTableRowModel findInStorage(String id) { return storage.stream() .filter(item -> item.getId() == Long.valueOf(id)) .findAny() .orElse(null); } private long generateNewId() { return storage.stream() .mapToLong(RestfulTableRowModel::getId) .max().orElse(0) + 1; } }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

 @XmlRootElement @XmlAccessorType(XmlAccessType.FIELD) public class RestfulTableRowModel { @XmlElement(name = "id") private long id; @XmlElement(name = "name") private String name; public long getId() { return id; } public void setId(long id) { this.id = id; } public String getName() { return name; } public void setName(String name) { this.name = name; } }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

プラグイン記述子の対応する残りのモジュール：

 <rest name="Events RESTful Table Resource" key="events-restful-table-resource" path="/evt-restful-table" version="1.0"/>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

RESTリソースコードでは、次の点に注意してください。

• リポジトリ内のレコードを作成および更新するRESTリソースメソッドも、応答の一部としてこのレコードの結果オブジェクトを返します。一般に、これは完全に一般的な方法です。 問題は、この慣行について知らない場合、これを強制するものは何もないということです。 これがないと、テーブルは正しく機能しません。
• テーブル内のレコードを編集すると、変更されたフィールドの値のみがサーバーに渡され、残りの代わりにnullが来るため、リポジトリのレコードオブジェクトに新しい値を書き込む前にそれらの存在を確認する必要があります 空の値は空の文字列の形でサーバーに送られ、nullではないため、文字列フィールドの場合は新しい空の値と変更がないことを区別する問題はありません-しかし、プリミティブ型のフィールドの場合、困難が生じる可能性があります;
• レコードクラスにはidフィールドがあります。テーブルには表示されませんが、レコードを識別するために使用されます。 IDはサーバーによって生成され、作成されたストレージレコードオブジェクトの一部としてクライアントに返されます。 重要：idは、Javascript表現がブール値trueにキャストされ、falseではないようにする必要があります。特に、0は良くありません。
• サーバー上のレコードは（この場合はidで）ソートされます-もちろんこれは必要ではありませんが、実際のタスクでは必要になるでしょう。 順序は自然な順序とは逆になっていることに注意してください-これにより、テーブルにレコードを追加するときに直接発生した再出力（ページのリロードなど）時に同じ順序のレコードを保存できます。 ただし、表にはオプション「createPosition」があり、この例のように値「bottom」で新しいエントリを上からではなく下から追加できます。この場合、このような反転はもちろん不要です。

プラグインをまとめる...驚き！ プラグイン管理ページで確認できるように、RESTリソースがシステムに追加されていますが、データを保存することは望んでいません。 ブラウザコンソールを開くと、理由を簡単に判断できます。RESTリソースは404エラーを返します。つまり、使用されているアドレスには存在しません。 実際、アドレスは問題です。ブラウザーは、フォーム「<your_JIRA> /plugins/servlet/rest/evt-restful-table/1.0/events-restful-table/」のアドレスにアクセスしますが、リソースは「<your_JIRA」という形式のアドレスにあります> /rest/evt-restful-table/1.0/events-restful-table/ "（たとえば、 Atlassian REST API Browserプラグインを使用してこれを確認できます）。 テーブルがクエリに使用する実際のパスは、現在のページのアドレスに基づいて構築されます（たとえば、ページを描画するサーブレットへのパスを作成すると、クエリのパスはそれに応じて変更されます）。 ただし、パスをスラッシュ（「/」）で開始すると状況が変わります。この場合、リソースへのフルパスはホスト名とリソースへの指定パスで構成されます。 この現象の理由は、率直に言って、怠け者です。 ここでのポイントはAUIでさえなく、基礎となるBackbone.jsであるという疑いがあります。 いずれにしても、JIRAベースURLがホスト名と一致しない限り、各パスの先頭に単にスラッシュを追加するだけでは十分ではありません。 普遍的な解決策は、アクセス可能な（そしてスラッシュで始まる）コンテキストパスです。

 resources: { all: AJS.contextPath() + "/rest/evt-restful-table/1.0/events-restful-table/all", self: AJS.contextPath() + "/rest/evt-restful-table/1.0/events-restful-table/self" },
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

別のソリューションも可能です。アプリケーションのベースURLから相対URLではなく完全なURLを作成し、RESTリソースへのパスを自分で作成します。

 resources: { all: AJS.params.baseURL + "/rest/evt-restful-table/1.0/events-restful-table/all", self: AJS.params.baseURL + "/rest/evt-restful-table/1.0/events-restful-table/self" },
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

これらのURLは、追加の変換なしで使用されます。

プラグインを再度コンパイルし、適切なパスを示しています。 現在、テーブル内のレコードは定期的に作成、編集、削除されます。 すべてが機能しているようです...ハァッ？ そうでもない。

動線

テーブルは、ドラッグ＆ドロップ行もサポートする必要があります（これを無効にできる設定がありますが、使用しませんでした）。 これで、行のいずれかをどこかにドラッグしようとしても機能しますが、ページをリロードした後、行は同じ位置になります。 行位置の変更をサーバーに反映するには、マニュアルに記載されていない別のRESTリソース-移動が必要です。これは、移動の詳細に関する情報を受け取ります。 彼は2つのパラメータを持つオブジェクトを受け取ることを期待しています：after-ドラッグ可能およびドラッグを配置する下の行に対応するデータ要素のRESTリソースへのパス、およびposition-4つの定数の1つを使用した要素の新しい位置の説明：First、Last、Earlierまたは後で（ただし、実際には、RESTfulテーブルの現在の実装ではFirst ...のみを使用しますが、4つすべてに対して処理を実装する必要があります）。 初期化できるのは2つのフィールドのうち1つだけです。 わかりやすくするために、Javaモデル文字列のフィールドを作成しましたが、これは最も便利なソリューションではありません。

 @XmlRootElement @XmlAccessorType(XmlAccessType.FIELD) public class MoveInfo { @XmlElement(name = "position") private String position; @XmlElement(name = "after") private String after; public String getPosition() { return position; } public void setPosition(String position) { this.position = position; } public String getAfter() { return after; } public void setAfter(String after) { this.after = after; } }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

そして、これが私のRESTリソースを実装する実際のメソッドです：

 @POST @Path("/self/{id}/move") public Response moveEvent(@PathParam("id") String idString, MoveInfo moveInfo) { long oldId = Long.valueOf(idString); long newId; if (moveInfo.getAfter() != null) { String[] afterPathParts = moveInfo.getAfter().split("/"); long afterId = Long.valueOf(afterPathParts[afterPathParts.length - 1]); newId = afterId > oldId ? afterId - 1 : afterId; } else if (moveInfo.getPosition() != null) { switch (moveInfo.getPosition()) { case "First": newId = getLastId(); break; case "Last": newId = 1L; break; case "Earlier": newId = oldId < getLastId() ? oldId + 1 : oldId; break; case "Later": newId = oldId > 1 ? oldId - 1 : oldId; break; default: throw new IllegalArgumentException("Unknown position type!"); } } else { throw new IllegalArgumentException("Invalid move data!"); } if (newId > oldId) { storage.stream() .filter(entry -> entry.getId() <= newId && entry.getId() >= oldId) .forEach(entry -> entry.setId(entry.getId() == oldId ? newId : entry.getId() - 1)); } else if (newId < oldId) { storage.stream() .filter(entry -> entry.getId() >= newId && entry.getId() <= oldId) .forEach(entry -> entry.setId(entry.getId() == oldId ? newId : entry.getId() + 1)); } return Response.ok().build(); }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

注：この場合に使用されるテーブル内の要素のソート方法に正確に関連しています。 逆の順序で並べ替えるには、このメソッドを変更する必要があります。

ご覧のように、このメソッドはブラウザにとって意味のあるものを返しませんが（可能ですが）、一般に移動要求の結果を処理する必要があります（返されると、マニュアルに記載されていないREORDER_SUCCESSイベントが発生します。テーブルの移動された行のモデルは古いIDを保持します（残念ながら、それらは自動的に配信されませんでした）。これは、ブラウザーとサーバーで同期されていないデータを意味するため、テーブルのインタラクティブな要素をさらに操作しても、何も良い結果にはなりません。 したがって、この場合（実際にはかなり不経済ですが）、最も簡単な方法は、サーバーから変更に関するデータを返して正しい場所にプッシュするのではなく、単にテーブルを受信して​​すべてのデータを再度描画することです。 手動で行う必要があるのは、tbodyテーブルの古い内容を削除することだけです。

 AJS.$(document).ready(function () { AJS.TableExample = {}; AJS.TableExample.table = new AJS.RestfulTable({ // ... }); AJS.$(document).bind(AJS.RestfulTable.Events.REORDER_SUCCESS, function () { AJS.TableExample.table.$tbody.empty(); AJS.TableExample.table.fetchInitialResources(); });
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

これですべてです！

他のフィールドタイプ

私のテーブルは完全に機能していますが、ほとんど役に立ちません。実際、それは単なる行のリストです。 もちろん、文字列フィールドを追加することもできますが、実際のテーブルでは、行だけでなく、日付、チェックボックス、コンボボックスなど、他の何かも表示したいでしょう。たとえば、日付を追加します-他のフィールドも同様に作成されます。

カスタムビューフィールドをテーブルに追加するには、現在作成、編集、および非アクティブになっている行で、それぞれ作成、編集、読み取り用のカスタムビューを提供する必要があります。 日付を作成および編集するには、aui-date-pickerを使用します。これは、AUIについて説明しているためです。非アクティブな行の場合、通常のスパンで十分です。

 { id: "date", header: "Event date", createView: AJS.RestfulTable.CustomCreateView.extend({ render: function (self) { var $field = AJS.$('<input type="date" class="text aui-date-picker" name="date" />'); $field.datePicker({'overrideBrowserDefault': true}); return $field; } }), editView: AJS.RestfulTable.CustomEditView.extend({ render: function (self) { var $field = AJS.$('<input type="date" class="text aui-date-picker" name="date">'); $field.datePicker({'overrideBrowserDefault': true}); if (!_.isUndefined(self.value)) { $field.val(new Date(self.value).print("%Y-%m-%d")); } return $field; } }), readView: AJS.RestfulTable.CustomReadView.extend({ render: function (self) { var val = (!_.isUndefined(self.value)) ? new Date(self.value).print("%Y-%m-%d") : undefined; return '<span data-field-name="date">' + (val ? val : '') + '</span>'; } }) }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

したがって、データモデルのjavaクラスを更新します。

 @XmlElement(name = "date") private Date date; public Date getDate() { return date; } public void setDate(Date date) { this.date = date; }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

...そして、更新メソッドに日付処理を追加します。

 Optional.ofNullable(update.getDate()).ifPresent(model::setDate);
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

完了-目的のタイプの新しいフィールドがテーブルに表示されます。

説明と追加を喜んでいたします。