EmbedBlockAuthoringTagHandler
in package
implements
VoidAuthoringTagHandler
`<acms-block-editor-embed-block url="...">` を、Embed サービスで取得した埋め込みブロックの機能タグにする。
URL の検証・SSRF 対策・取得キャッシュ・HTML のサニタイズは、編集画面で URL を確定したときと
同じ Embed サービスに委ねる。取得できなければ通常リンクの段落へ退避して警告を残す。
id / class 属性は機能タグへ引き継ぐ。属性だけで表現できるため中身を持たないタグとして扱い、
閉じタグを書き忘れても後続の本文を飲み込まない。
Table of Contents
Interfaces
- VoidAuthoringTagHandler
- 中身を持たない入稿用タグ（HTML の void 要素のように開始タグだけで完結する）のハンドラ。
Constants
- WARNING_KIND = 'embed'
- 警告の種別（CSV インポートは埋め込みの取得失敗を種別ごとに数える）
Properties
- $embed : callable(): Helper
- $failedUrls : array<string, true>
- 取得に失敗した URL（値は常に true）
Methods
- __construct() : mixed
- Why not EmbedHelper を直接受け取る: レジストリは singleton のため、拡張アプリが後から `embed` を差し替えても（Container::override）古いインスタンスを使い続けてしまう。使うときに解決する
- convert() : string
- 入稿用タグを保存用の HTML へ変換する
- getTagName() : string
- 担当する入稿用タグの要素名
- fallbackParagraph() : string
- 埋め込みを解決できなかった URL の退避先（通常リンクの段落）を組み立てる
- resolve() : EmbedData
- toEmbedProps() : array<string, string|bool>
- 編集画面で URL を確定したときと同じ props を組み立てる
Constants
WARNING_KIND
警告の種別（CSV インポートは埋め込みの取得失敗を種別ごとに数える）
public
mixed
WARNING_KIND
= 'embed'
Properties
$embed
private
callable(): Helper
$embed
$failedUrls
取得に失敗した URL（値は常に true）
private
array<string, true>
$failedUrls
= []
成功した結果は Embed サービスのキャッシュが保持する。失敗はそのキャッシュが再取得する （fetchWithRetryOnEmptyCache）ため、同じ処理の中で失敗し続ける URL へ何度も外部へ 取りに行かないよう、ここで覚えておく。
Methods
__construct()
Why not EmbedHelper を直接受け取る: レジストリは singleton のため、拡張アプリが後から `embed` を差し替えても（Container::override）古いインスタンスを使い続けてしまう。使うときに解決する
public
__construct(callable(): Helper $embed) : mixed
Parameters
- $embed : callable(): Helper
convert()
入稿用タグを保存用の HTML へ変換する
public
convert(AuthoringTag $tag, AuthoringContext $context) : string
戻り値でタグ全体（開始タグから閉じタグまで）を置き換える。空文字を返すとタグごと取り除かれる。 戻り値は再変換されないため、中身に入稿用タグを含められるブロックは AuthoringContext::convert() で中身を変換してから組み込むこと。 属性・中身は CSV / API の利用者が自由に書ける値のため、期待する形でなくても例外を投げず、 安全側の HTML を返して AuthoringContext::warn() で警告を残すこと。
Parameters
- $tag : AuthoringTag
-
変換対象のタグ
- $context : AuthoringContext
-
警告の記録・外部取得の可否・中身の再帰変換
Return values
stringgetTagName()
担当する入稿用タグの要素名
public
getTagName() : string
カスタム要素名（小文字英字で始まり、ハイフンを1つ以上含む）であること。拡張アプリは
コアとの衝突を避けるため acms-block-editor- 以外の接頭辞（プラグイン名等）を使う。
同じ名前のハンドラを後から登録した場合は、後勝ちで置き換わる。
Return values
stringfallbackParagraph()
埋め込みを解決できなかった URL の退避先（通常リンクの段落）を組み立てる
private
static fallbackParagraph(string $url) : string
Parameters
- $url : string
Return values
stringresolve()
private
resolve(Helper $embed, string $url) : EmbedData
Parameters
- $embed : Helper
- $url : string
Return values
EmbedDatatoEmbedProps()
編集画面で URL を確定したときと同じ props を組み立てる
private
toEmbedProps(string $url, EmbedData $data) : array<string, string|bool>
対応するフロントエンドの型は EmbedBlock の EmbedBlockProps（既定値は EMPTY_EMBED_BLOCK_PROPS）。
Parameters
- $url : string
- $data : EmbedData