Qute リファレンスガイド

The first part of the expression is always resolved against the current context object. If no result is found for the first part, it’s resolved against the parent context object (if available). For an expression that starts with a namespace the current context object is found using all the available NamespaceResolvers. For an expression that does not start with a namespace the current context object is derived from the position of the tag. All other parts of an expression are resolved using all ValueResolvers against the result of the previous resolution.

例えば、式 {name} には名前空間がなく、単一のパーツ - name です。"name"は、カレントコンテキストオブジェクトに対して利用可能なすべての値リゾルバを使用して解決されます。しかし、式 {global:colors} には、名前空間 global と単一パーツ - colors があります。まず、現在のコンテキストオブジェクトを見つけるために、利用可能なすべての NamespaceResolver s が使用されます。その後、見つかったコンテキストオブジェクトに対して"colors"を解決するために値リゾルバが使用されます。

If an expression does not specify a namespace, the current context object is derived from the position of the tag. By default, the current context object represents the data passed to the template instance. However, sections may change the current context object. A typical example is the let section that can be used to define named local variables:

You can iterate over elements of an array with ループセクション. Moreover, it’s also possible to get the length of the specified array and access the elements directly via an index value. Additionally, you can access the first/last n elements via the take(n)/takeLast(n) methods.

HTML と XML テンプレートの場合、'、"、<, >、& の文字は、テンプレートバリアントが設定されている場合はデフォルトでエスケープされます。

エスケープされていない値をレンダリングする必要がある場合:

仮想メソッドとは、通常のJavaメソッド呼び出しのように見える 式のパーツ です。Javaクラスの実際のメソッドと一致する必要がないため、「仮想」と呼ばれています。実際には、通常のプロパティーと同様に、仮想メソッドも値リゾルバによって処理されます。唯一の違いは、仮想メソッドの場合、値リゾルバが式でもあるパラメーターを消費することです。

単一のパラメーターを持つ仮想メソッドは 中置記法を使用して呼び出すことができます。

仮想メソッドのパラメーターは、「入れ子」仮想メソッドの呼び出しにすることができます。

java.util.concurrent.CompletionStage および io.smallrye.mutiny.Uni を実装したオブジェクトは、特別な方法で評価されます。式の一部が CompletionStage に解決された場合、このステージが完了すると解決が継続され、式の次の部分(もしあれば)が完了したステージの結果に対して評価されます。たとえば、式 {foo.size} があり、 foo が CompletionStage<List<String>> に解決された場合、 size は完了した結果、すなわち List<String> に対して解決されます。式の一部が Uni に解決される場合、 CompletionStage が Uni#subscribeAsCompletionStage() を使用して Uni から最初に作成され、その後上記のように評価されます。

CompletionStage が完了しなかったり、あるいは Uni がアイテム/失敗を発しないということが起こり得ます。この場合、レンダリングメソッド (TemplateInstance#render() および TemplateInstance#createUni()) は、特定のタイムアウトを過ぎると失敗します。このタイムアウトは、テンプレートインスタンスの timeout 属性として指定することができます。timeout 属性が設定されていない場合、グローバルレンダリングタイムアウトが使用されます。

式が実行時に評価されない場合があります。たとえば、{person.age} という式があり、Person クラスに age というプロパティーが宣言されていない場合です。strict レンダリング が有効かどうかによって、動作が異なってきます。

これを有効にすると、プロパティーが見つからない場合、常に TemplateException が発生し、レンダリングが中断されます。このエラーを抑制するために、default values や safe expressions を使用することができます。

無効な場合、デフォルトで特別な定数 NOT_FOUND が出力に書き込まれます。

A start tag can define parameters with optional names, e.g. {#if item.isActive} and {#let foo=1 bar=false}. Parameters are separated by one or more spaces. Names are separated from the values by the equals sign. Names and values can be prefixed and suffixed with any number of spaces, e.g. {#let id='Foo'} and {#let id = 'Foo'} are equivalents where the name of the parameter is id and the value is Foo. Values can be grouped using parentheses, e.g. {#let id=(item.id ?: 42)} where the name is id and the value is item.id ?: 42. Sections can interpret parameter values in any way, e.g. take the value as is. However, in most cases, the parameter value is registered as an expression and evaluated before use.

1つのセクションには、いくつかのコンテンツ ブロック を含めることができます。"main" ブロックは常に存在します。追加/入れ子になったブロックも # で始まり、パラメーターを持つことができます - {#else if item.isActive}。セクションのロジックを定義するセクションヘルパーは、任意のブロックを「実行」し、パラメーターを評価することができます。

ループセクションでは、Iterable、Iterator、array、Map (要素は Map.Entry)、Stream、Integer、int (プリミティブ値) のインスタンスに対して反復処理することができます。パラメーター値に null を指定すると、no-op となります。

このセクションには 2 つのフレーバーがあります。最初のものは each という名前を使い、it は反復処理要素の暗黙のエイリアスです。

もう一つの形式は、for という名前を使い、反復要素を参照するために使われるエイリアスを指定します。

また、ループ内の反復処理メタデータには、以下のキーでアクセスすることが可能です。

しかし、キーを直接使うことはできません。その代わり、外部スコープの変数と競合する可能性を避けるために、接頭辞が使用されます。デフォルトでは、反復処理された要素のエイリアスの後にアンダースコアを付けたものが接頭辞として使用されます。たとえば、{#each} セクション ({it_hasNext}) の中では、hasNext キーは it_ を接頭辞として使用する必要があります。

また、{#for} セクションの中で {item_hasNext} の形式で、item 要素のエイリアスと使用する必要があります。

for 文は、1 から始まる整数でも動作します。 以下の例では、 total = 3 です。

出力は、以下のようになります。

ループセクションは、反復する項目がないときに実行される {#else} ブロックも定義することができます。

if セクションは、基本的な制御フローセクションを表しています。最も単純なバージョンでは、単一のパラメーターを受け取り、条件が true と評価された場合にコンテンツをレンダリングします。演算子なしの条件は値が falsy (つまり、null 、 false 、空のコレクション、空のマップ、空の配列、空の文字列/文字列シーケンス、またはゼロに等しい数) ではない場合、 true と評価されます。

条件では、以下の演算子を使うこともできます:

複数の条件にも対応しています。

優先順位の規則は、カッコで上書きすることができます。

また、 else ブロックを何個でも追加することができます。

このセクションは、Java の switch や Kotlin の when に似ています。条件が満たされるまで、 テストされた値 をすべてのブロックに対して順次マッチさせます。最初にマッチしたブロックが実行されます。他のすべてのブロックは無視されます(この動作は、 break 文が必要な Java switch とは異なります)。

enum に解決されるテスト値は特別な扱いを受けます。 is / case ブロックのパラメーターは式として評価されるのではなく、テストされた値に対して toString() を呼び出した結果と比較されます。

is / case ブロック条件では、以下の演算子がサポートされています。

このセクションでは、名前付きローカル変数を定義することができます。

ローカル変数名などのセクションパラメータのキーが ? で終わっている場合、 ? を除いたキーが null または "not found" に解決される場合にのみ、ローカル変数が設定されます:

このセクションタグも set のエイリアスで登録されています。

このセクションは、現在のコンテキストオブジェクトを設定するために使用することができます。これはテンプレート構造を単純化するのに便利かもしれません。

このセクションは、複数の高価な呼び出しを避けたいときにも便利かもしれません。

このセクションは、別のテンプレートをインクルードし、場合によってはテンプレートの一部をオーバーライドするために使用することができます (下記の テンプレートの継承 を参照)。

テンプレートの継承 により、テンプレートレイアウトの再利用が可能になります。

ユーザー定義タグは、タグテンプレート をインクルードし、オプションでいくつかの引数を渡し、場合によってはテンプレートの一部をオーバーライドするために使用することができます。たとえば、itemDetail.html というタグテンプレートがあるとします。

Quarkus では、src/main/resources/templates/tags にあるすべてのファイルが、自動的に登録および監視されます。Qute スタンドアロンでは、解析されたテンプレートを itemDetail.html という名前で置き、関連する UserTagSectionHelper をエンジンに登録する必要があります。

そして、以下のようなタグを呼び出すことができます。

By default, a tag template cannot reference the data from the parent context. Qute executes the tag as an isolated template, i.e. without access to the context of the template that calls the tag. However, sometimes it might be useful to change the default behavior and disable the isolation. In this case, just add _isolated=false or _unisolated argument to the call site, for example {#itemDetail item showImage=true _isolated=false /} or {#itemDetail item showImage=true _unisolated /}.

フラグメントは、別個のテンプレートとして扱える、つまり別々にレンダリングできるテンプレートの一部分を表します。この機能を導入した主な動機の1つは、 htmxフラグメント のようなユースケースをサポートするためでした。

フラグメントは {#fragment} セクションで定義することができます。 各フラグメントは、英数字とアンダースコアのみからなる識別子を持ちます。

io.quarkus.qute.Template.getFragment(String) メソッドにより、プログラム的にフラグメントを取得することができます。

上記のスニペットは、次のようにレンダリングされるはずです:

また、 {#include} セクションを持つフラグメントを、別のテンプレートやフラグメントを定義するテンプレートの中に含めることもできます。

This section can be used to parse and evaluate a template dynamically. The behavior is very similar to Include セクション but:

めったに変更されないテンプレートの一部をキャッシュすることが実用的な場合もあります。キャッシュ機能を使うには、組み込みの io.quarkus.qute.CacheSectionHelper.Factory を登録・設定します:

Then, the {#cached} section can be used in a template:

式を評価する際に値リゾルバを使用します。カスタム io.quarkus.qute.ValueResolver は EngineBuilder.addValueResolver() からプログラムで登録することができます。

テンプレートは、手動で登録するか、テンプレートロケータを介して自動的に登録することができます。ロケーターは、 Engine.getTemplate() メソッドが呼び出されたときに、エンジンがキャッシュに保存している所定の ID のテンプレートがない場合に使用されます。ロケーターは、テンプレートの内容を読み取る際に、正しい文字エンコーディングを使用する責任があります。

コンテンツフィルタを使用して、解析前にテンプレートコンテンツを変更することができます。

strict レンダリングにより、開発者は、タイプミスや無効な式によって引き起こされるわかりにくいエラーをキャッチすることができます。この機能を有効にすると、解決できない式、つまり io.quarkus.qute.Results.NotFound のインスタンスとして評価される式は、常に TemplateException となり、レンダリングは中断されます。NotFound 値は基本的に、値リゾルバーが式を正しく解決できなかったことを意味するため、エラーとみなされます。

strict レンダリングはデフォルトで有効になっています。しかし、io.quarkus.qute.EngineBuilder.strictRendering(boolean) によって、この機能を無効にすることができます。

"not found" エラーを引き起こす可能性のある式をどうしても使いたい場合は、デフォルト値 および 安全な式 を使ってエラーを抑制することができます。デフォルト値は、式の前のパーツが解決できないか、null に解決される場合に使用されます。エルビス演算子を使ってデフォルト値 {foo.bar ?: 'baz'} を出力することができます。これは事実上、仮想メソッド {foo.bar.or('baz')} と同じになります。安全な式は ?? という接尾辞で終わり、式が解決できない場合は null という結果になります。これは、たとえば {#if} セクションの {#if valueNotFound??}Only rendered if valueNotFound is truthy!{/if} では非常に便利です。実際のところ、?? は .or(null) の簡単な表記法に過ぎず、たとえば {#if valueNotFound??} は {#if valueNotFound.or(null)} となります。

テンプレートロケーター を登録する最も簡単な方法は、これらを CDI Bean にすることです。テンプレート検証を行うビルド時にはカスタムロケーターは利用できないので、@Locate アノテーションで検証を無効化する必要があります。

If using templates in Jakarta REST resources, you can rely on the following convention:

また、 @CheckedTemplate でアノテーションされたトップレベルの Java クラスを宣言することもできます。

そして、テンプレートファイルごとに public static native TemplateInstance method(); を宣言します。これらの静的メソッドを使用してテンプレートインスタンスを構築します。

A Java record that implements io.quarkus.qute.TemplateInstance denotes a type-safe template. The record components represent the template parameters and @io.quarkus.qute.CheckedTemplate can be optionally used to configure the template.

@CheckedTemplate メソッドのテンプレートパスは、 ベースパス と デフォルトの名前 から構成されます。 ベースパス は @CheckedTemplate#basePath() で指定されます． デフォルトでは，ネストした静的クラスの場合は宣言クラスのsimple name，トップレベルクラスの場合は空文字列が使用されます． デフォルトの名前 は， @CheckedTemplate#defaultName() で指定された戦略によって導出されます。 デフォルトでは、 @CheckedTemplate のメソッドの名前がそのまま使われます。

You can also define a type-safe fragment in your Java code. A native static method with the name that contains a dollar sign $ denotes a method that represents a fragment of a type-safe template. The name of the fragment is derived from the annotated method name. The part before the last occurence of a dollar sign $ is the method name of the related type-safe template. The part after the last occurence of a dollar sign is the fragment identifier. The strategy defined by the relevant CheckedTemplate#defaultName() is honored when constructing the defaulted names.

メソッド名は、デフォルトでプロパティ名と一致するように使用されます。

このテンプレート拡張メソッドを使うと、以下のテンプレートをレンダリングすることができます。

ただし、 matchName() でマッチング名を指定することは可能です。

特別な定数 - TemplateExtension#ANY / * - を使用すると、拡張メソッドが任意の名前にマッチするように指定することができます。

また、 matchRegex() で指定された正規表現と名前を照合することも可能です。

最後に、 matchNames() を使用して、一致する名前のコレクションを指定することができます。追加の文字列メソッド・パラメータも必須です。

An extension method may declare parameters. If no namespace is specified then the first parameter that is not annotated with @TemplateAttribute is used to pass the base object, i.e. org.acme.Item in the first example. If matching any name or using a regular expression, then a string method parameter needs to be used to pass the property name. Parameters annotated with @TemplateAttribute are obtained via TemplateInstance#getAttribute(). All other parameters are resolved when rendering the template and passed to the extension method.

TemplateExtension#namespace() が指定された場合、拡張メソッドが、指定された namespace を持つ式を解決するために使用されます。同じ名前空間を共有するテンプレート拡張メソッドは、 TemplateExtension#priority() で順に 1 つのリゾルバにグループ化されます。最初にマッチする拡張メソッドが式の解決に使用されます。

これらの拡張メソッドは、以下のように使用することができます。

Quarkusは、組み込みの拡張メソッドのセットを提供しています。

もし @TemplateData#namespace() が空でない値に設定されている場合、ターゲットクラスのパブリック静的フィールドとメソッドにアクセスするための名前空間リゾルバーが自動的に生成されます。デフォルトでは、名前空間はターゲットクラスの FQCN で、ドットやドル記号はアンダースコアに置き換えられます。たとえば、名前 org.acme.Foo を持つクラスの名前空間は org_acme_Foo となります。静的フィールド Foo.AGE には、{org_acme_Foo:AGE} からアクセスすることができます。静的メソッド Foo.computeValue(int number) には、{org_acme_Foo:computeValue(10)} を介してアクセスすることができます。

また、enum 定数にアクセスするための便利なアノテーションとして、@io.quarkus.qute.TemplateEnum があります。このアノテーションは、機能的には @TemplateData(namespace = TemplateData.SIMPLENAME) と同等です。つまり、対象の enum に対して自動的に名前空間リゾルバーが生成され、対象の enum の単純名が名前空間として使用されます。

If not accessed via the global: namespace the global variables may conflict with regular data objects. Type-safe templates override the global variables automatically. For example, the following definition overrides the global variable supplied by the Globals#user() method:

そのため、Globals#user() メソッドが java.lang.String を返し、それが name プロパティーを持たないにもかかわらず、対応するテンプレートはバリデーションエラーにはなりません。

その他のテンプレートでは、明示的なパラメーター宣言が必要です。

The basic idea is that every message is potentially a very simple template. In order to prevent type errors, a message is defined as an annotated method of a message bundle interface. Quarkus generates the message bundle implementation at build time.

メッセージバンドルは、実行時に使用することができます:

The bundle name is defaulted unless it’s specified with @MessageBundle#value(). For a top-level class the msg value is used by default. For a nested class the name consists of the simple names of all enclosing classes in the hierarchy (top-level class goes first), followed by the simple name of the message bundle interface. Names are separated by underscores.

例えば、以下のメッセージバンドルの名前は、デフォルトで Controller_index になります:

Message keys are used directly in templates. The bundle name is used as a namespace in template expressions. The @MessageBundle can be used to define the default strategy used to generate message keys from method names. However, the @Message can override this strategy and even define a custom key. By default, the annotated element’s name is used as-is. Other possibilities are:

デフォルトでは、@MessageBundle インターフェイスには quarkus.default-locale 設定プロパティーで指定したデフォルトロケールが使用されます。しかし、io.quarkus.qute.i18n.MessageBundle#locale() を使用して、カスタムのロケールを指定することができます。さらに、ローカライズされたバンドルを定義するには、以下の 2 つの方法があります。

Message bundle files must be encoded in UTF-8. The file name consists of the relevant bundle name (e.g. msg) and underscore followed by a language tag (IETF; e.g. en-US). The language tag may be omitted, in which case the language tag of the default bundle locale is used. For example, if bundle msg has default locale en, then msg.properties is going to be treated as msg_en.properties. If both msg.properties and msg_en.properties are detected, an exception is thrown and build fails. The file format is very simple: each line represents either a key/value pair with the equals sign used as a separator or a comment (line starts with #). Blank lines are ignored. Keys are mapped to method names from the corresponding message bundle interface. Values represent the templates normally defined by io.quarkus.qute.i18n.Message#value(). A value may be spread out across several adjacent normal lines. In such case, the line terminator must be escaped with a backslash character \. The behavior is very similar to the behavior of the java.util.Properties.load(Reader) method.

行の終端はバックスラッシュ文字 \ でエスケープされ、次の行の先頭の空白は無視されることに注意してください。つまり、{msg:hello('Edgar')} は Hello Edgar and good morning! とレンダリングされます。

Once we have the localized bundles defined, we need a way to select the correct bundle for a specific template instance, i.e. to specify the locale for all message bundle expressions in the template. By default, the locale specified via the quarkus.default-locale configuration property is used to select the bundle. Alternatively, you can specify the locale attribute of a template instance.

@Localized 修飾子を使用して、ローカライズされたMessage Bundleインタフェースを注入することができます。

メッセージバンドルインターフェースの全てのメソッドは、メッセージテンプレートを定義しなければなりません。通常は io.quarkus.qute.i18n.Message#value() で定義しますが、利便性のため、ローカライズしたファイルに値を定義するオプションも用意されています。

メッセージテンプレートはビルド時に検証されます。メッセージテンプレートの欠落が検出された場合、例外がスローされ、ビルドに失敗します。