Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Qute: improve docs/javadoc about value resolvers ordering #43498

Merged
merged 1 commit into from
Sep 26, 2024
Merged

Qute: improve docs/javadoc about value resolvers ordering #43498

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 10 additions & 1 deletion docs/src/main/asciidoc/qute-reference.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -335,10 +335,10 @@

[[expression_resolution]]
==== Resolution

When evaluating expressions a list of registered <<value-resolvers,value resolvers>> is used.
The first part of the expression is always resolved against the <<current_context_object,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 ``NamespaceResolver``s.

Check warning on line 341 in docs/src/main/asciidoc/qute-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.", "location": {"path": "docs/src/main/asciidoc/qute-reference.adoc", "range": {"start": {"line": 341, "column": 83}}}, "severity": "INFO"}
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 ``ValueResolver``s against the result of the previous resolution.

Expand Down Expand Up @@ -1448,9 +1448,14 @@
=== Engine Configuration

[[value-resolvers]]
==== Value Resolvers

Check warning on line 1451 in docs/src/main/asciidoc/qute-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Headings] Use sentence-style capitalization in '3.7.1. Value Resolvers'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in '3.7.1. Value Resolvers'.", "location": {"path": "docs/src/main/asciidoc/qute-reference.adoc", "range": {"start": {"line": 1451, "column": 19}}}, "severity": "INFO"}

Value resolvers are used when evaluating expressions.
First the resolvers that apply to the given `EvalContext` are filtered.
Then the resolver with _highest priority_ is used to resolve the data.
If a `io.quarkus.qute.Results.NotFound` object is returned then the next available resolver is used instead.
However, `null` return value is considered a valid result.

A custom `io.quarkus.qute.ValueResolver` can be registered programmatically via `EngineBuilder.addValueResolver()`.

.`ValueResolver` Builder Example
Expand All @@ -1462,8 +1467,12 @@
.build());
----

TIP: In Quarkus, the <<engine-customization,`@EngineConfiguration`>> annotation can be used to register a `ValueResolver` implemented as a CDI bean.

NOTE: Keep in mind that the reflection-based value resolver has priority `-1` and the max priority value for resolvers generated from <<template_data,`@TemplateData`>> and <<typesafe_expressions,type-safe expressions>> is `10`.

Check warning on line 1472 in docs/src/main/asciidoc/qute-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsWarnings] Consider using 'remember' rather than 'Keep in mind' unless updating existing content that uses the term.

Raw Output:
{"message": "[Quarkus.TermsWarnings] Consider using 'remember' rather than 'Keep in mind' unless updating existing content that uses the term.", "location": {"path": "docs/src/main/asciidoc/qute-reference.adoc", "range": {"start": {"line": 1472, "column": 7}}}, "severity": "WARNING"}

[[template-locator]]
==== Template Locator

Check warning on line 1475 in docs/src/main/asciidoc/qute-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Headings] Use sentence-style capitalization in '3.7.2. Template Locator'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in '3.7.2. Template Locator'.", "location": {"path": "docs/src/main/asciidoc/qute-reference.adoc", "range": {"start": {"line": 1475, "column": 19}}}, "severity": "INFO"}

A template can be either registered manually or automatically via a template locator.
The locators are used whenever the `Engine.getTemplate()` method is called, and the engine has no template for a given id stored in the cache.
Expand Down
5 changes: 5 additions & 0 deletions independent-projects/qute/core/src/main/java/io/quarkus/qute/TemplateExtension.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,8 +125,13 @@
String matchRegex() default "";

/**
* Value resolvers with higher priority take precedence.
* <p>
* Keep in mind that the reflection-based value resolver has priority {@code -1} and the max priority value for
* resolvers generated from {@link TemplateData} and type-safe expressions is {@code 10}.
*
* @return the priority used by the generated value resolver
* @see ValueResolver#getPriority()
*/
int priority() default DEFAULT_PRIORITY;

Expand Down
14 changes: 13 additions & 1 deletion independent-projects/qute/core/src/main/java/io/quarkus/qute/ValueResolver.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,26 @@
* Value resolvers are used when evaluating expressions.
* <p>
* First the resolvers that apply to the given {@link EvalContext} are filtered. Then the resolver with highest priority is used
* to resolve the data. If {@link Results#isNotFound(Object)} is returned the next available resolver is tried.
* to resolve the data. If a {@link io.quarkus.qute.Results.NotFound} object is returned then the next available resolver is
* used instead. However,
* {@code null} return value is considered a valid result.
*
* @see EvalContext
* @see EngineBuilder#addValueResolver(ValueResolver)
* @see EngineConfiguration
*/
public interface ValueResolver extends Resolver, WithPriority {

/**
* Value resolvers with higher priority take precedence.
*
* @return the priority value
*/
@Override
default int getPriority() {
return WithPriority.super.getPriority();
}

/**
*
* @param context
Expand Down
Loading