Madapaja.TwigModule下のpageリソースで Link アトリビュートが機能しない

[clap-and-whistle]

再現方法

BEAR.Sundayのスケルトンから始めて再現するまでのコミットを、次のリポジトリへ積みました。
Kimita/twigmodule-issue@7546748

状況

BEAR.Sunday のチュートリアル２:ticketsリソース で例示されているような Linkアトリビュート は、Madapaja.TwigModule の導入によってpageリソースのレンダラがHTML出力に変わると、pageリソース側では効かなくなるもよう。

考察

• どうやら、BEAR\Resource\HalRenderer::renderHal() 内で行われているような処理がMadapaja\TwigModule\TwigRenderer では行われていないことによるもののようだ。
• ひとまず、このリンク先にて積んだコミットで問題を回避してみている。
• 上述の回避策では現状、自作の AnnotationResolver で _embedded への埋め込みまでやってしまっている。しかし、BEAR.Sundayのチュートリアルで示されている内容からすると、Embedアトリビュートには触れずに「Linkアトリビュートを _links へ埋め込む」だけを処理対象とすべきなのかも？

上記で示した回避策がもし妥当ならば、今回自作した AnnotationResolver は次のように配置＆使用されるのが理想か？

• BEAR.Resource パッケージで AnnotationResolver (に相当するクラス)を提供する
• Madapaja.TwigModule のようなプレゼンテーション層向けのパッケージ側で、レンダリング処理を行うクラスにて適宜 AnnotationResolver (に相当するクラス)を任意使用する

[koriym]

HalRendererが_embeddedの中にリソースを埋め込むのは、HALがハイパーメディアの埋め込みリンク(LE)をサポートしているメディアで、_embeddedというセマンティックが規定してあるためです。

• https://apigility.org/documentation/api-primer/halprimer
• https://stateless.group/hal_specification.html

HTMLでも<img>や<iframe>で埋め込みリンクはサポートされていますが、ここで対応しようとしているものとはまた別レイヤーの話です。

埋め込みリンクに対して、@Linkはアウトバウンド(LO)のリンクです。<a>　タグで#[Link]を利用できる方法があっても良いと思います。

他にアイデアとして例えば HeaederLinkModuleをインストールするとレスポンスヘッダーにLinkヘッダーが現れるのも良いと思います。ハイパーメディアのワークフローテストがやりやすくなりますね。

Link: <https://example.com>; rel="foo"

どのハイパーメディアがどのリンクやコントロールをサポートしているかを表すのにH Factorという表があります。ご参考に！

https://gtramontina.com/h-factors/

[clap-and-whistle]

整理してくだささりありがとうございます、助かります！

以前に

改善余地があるとすれば、aタグはidではなくrelで指定するとハイパーメディア感出ますね。

— Akihito Koriyama (@koriym) September 20, 2022

とご助言いただいたことを私なりに解釈したことと合わせて、下記のようなプルリクを投げようかと考えています。

【検討中のプルリク内容のあらまし】

1. PHPのLinkアトリビュートを、application/hal+json と同様の _links という表現で ResouceObject の body へ構築 する。
2. HTMLテンプレートエンジン側では、「 Linkアトリビュートの rel値 を _linksのキーから取り出した上で、構築した aタグのrel属性にそれをセット する」という使い方をする。

ここでちょっと気になったのが、ご提示いただいた資料から辿って見つけた下記の情報です。
https://www.w3.org/TR/1999/REC-html401-19991224/types.html#type-links
これによると、recognized link types に無いものを定義したい場合は、その定義を記述した「HEAD要素のprofile」で指定するプロファイル文書を用意するのが望ましい？

[koriym]

• 実装場所は TwigModule であるか、それともQiqModuleとも共通にできる場所が良いか
• 配列でアサインする方法の他にヘルパー関数などを使って、遅延生成した方が利用しないものに対してパフォーマンスインパクトがないのでそちらの方法はどうか
• Linkヘッダーではどうか

https://developer.mozilla.org/ja/docs/Web/HTTP/Headers/Link

など頭に浮かびました。

[koriym]

https://www.w3.org/TR/1999/REC-html401-19991224/types.html#type-links
これによると、recognized link types に無いものを定義したい場合は、その定義を記述した「HEAD要素のprofile」で指定するプロファイル文書を用意するのが望ましい？

rel定義はこのPRとはまた別に考えれば良いと思いますが、ALPSはその名の通り Application level "protocol semantics"なので　relのsemanticsを記述できるものです。

[clap-and-whistle]

私の方で「bodyへ配列でアサイン」を考えたのは、主に次のような動機からです。

• Linkアトリビュートは appリソースでもpageリソースでも同じ記述ができるしTwigModule導入前は挙動も同じだった。TwigModule導入後も記述が変わらないから挙動も同じであることを期待した。
• HTML表示において、エンドユーザーとシステム間で「次の遷移先」等のインタラクションをする場所はLinkヘッダーよりも「HTMLの中、さらにbodyタグ内」のはず、と考えた。

以上の観点から、次のようなことを思いました。

Linkヘッダーではどうか

この機能（Linkヘッダー記述の提供）の実現は、TwigModule や QiqModule のレイヤー側で「Module利用者(=アプリケーション開発者)が任意に有効化設定をする」のような実装でもいいように感じます。
というのも、上述したようにHTML表示においてはエンドユーザーとシステムとでLOのインタラクションが行われるのは基本的にHTMLのbodyタグ内と見えるため、HTMLアプリケーションのワークフローテストは aタグ を介して行うのを基本とすべきように思ったのです。（リダイレクトだけは特殊？）

ヘルパー関数などを使って、遅延生成

このアイデアで実現するならば、「ResourceObjectへLinkアトリビュートでセットされたものをHTML側で出力する手段」をヘルパー関数等に閉じ込めて、配列アサインは不要とするのがいい気がしました。配列はアプリ開発者側で壊せそうなので。
またそれならば、この 「Linkアトリビュートで差し込んだものはヘルパー使って出力してね」という制約 を取り入れたModuleを導入することが「appリソースとpageリソースとで挙動が変わる契機」であると、利用者も理解しやすいように思います。

つまり「制約として提供」の方針ならば私はこのアイデアに賛成です。

実装場所は〜〜

BEARが「原則をそのままフレームワークが制約にして提供」と努めているのでしたら、出力のHTML化を担うModuleを開発する側へ 「BEAR.Resourceから上記のようなヘルパー関数等を制約として提供する」 ことは、方針に適っている気がします。(ただし、その制約を使うor使わないはモジュール開発側が選択できていい)

なお、ヘルパー関数等ではなく「bodyへ配列でアサイン」を方針とするならば、

1. 実装場所をBEAR.Resourceにする場合: 「appコンテキストのResourceObjectと同様の構造をpageコンテキストでも実現可能とする機能を、HTML出力化を担うModuleへ提供する」ことが目的
2. 実装場所をTwigModuleにする場合: 「今までLinkアトリビュートが捨てられてたところ、使えるようにする」ことが目的

のようになるかと思いますが、a.の方は制約としては弱い感じがするので b.で実現するのが妥当か、と見えました。

[clap-and-whistle]

ALPSはその名の通り Application level "protocol semantics"なので　relのsemanticsを記述できるものです。

BEAR.Sunday + ALPS の親和性の高さがここでもひょっこり現れた！(・∀・)b
ちなみに、プロファイル文書を用意するのは「BEAR.Sundayを使ってアプリケーションを作る人の仕事」と私は認識しています。