Skip to content

Commit

Permalink
Qute docs - introduce the "Qute Used as a Standalone Library" section
Browse files Browse the repository at this point in the history
  • Loading branch information
mkouba committed Sep 3, 2021
1 parent 47a92b4 commit 0132488
Showing 1 changed file with 37 additions and 0 deletions.
37 changes: 37 additions & 0 deletions docs/src/main/asciidoc/qute-reference.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,12 @@ The usage of reflection is minimized to reduce the size of native images.
The API combines both the imperative and the non-blocking reactive style of coding.
In the development mode, all files located in the `src/main/resources/templates` folder are watched for changes and modifications are immediately visible in your application.
Furthermore, Qute attempts to detect most of the template problems at build time and fail fast.

In this guide, you will find an <<hello_world_example,introductory example>>, the description of the <<core_features,core features>> and <<quarkus_integration,Quarkus integration>> details.

NOTE: Qute is primarily designed as a Quarkus extension. It is possible to use it as a "standalone" library too. However, in such case some of the features are not available. In general, any feature mentioned under the <<quarkus_integration>> section is missing. You can find more information about the limitations and possibilities in the <<standalone>> section.


[[hello_world_example]]
== Hello World Example

Expand Down Expand Up @@ -992,6 +996,7 @@ NOTE: The template rendering is divided in two phases. During the first phase, w

=== Engine Configuration

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

Value resolvers are used when evaluating expressions.
Expand All @@ -1006,6 +1011,7 @@ engineBuilder.addValueResolver(ValueResolver.builder()
.build());
----

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

Manual registration is sometimes handy but it's also possible to register a template locator using `EngineBuilder.addLocator(Function<String, Optional<Reader>>)`.
Expand Down Expand Up @@ -1673,6 +1679,7 @@ WARNING: Unlike with `@Inject` the templates obtained via `RestTemplate` are not

In the development mode, all files located in `src/main/resources/templates` are watched for changes and modifications are immediately visible.

[[type-safe-message-bundles]]
=== Type-safe Message Bundles

==== Basic Concepts
Expand Down Expand Up @@ -1838,3 +1845,33 @@ public class MyBean {
=== Configuration Reference

include::{generated-dir}/config/quarkus-qute.adoc[leveloffset=+1, opts=optional]


[[standalone]]
== Qute Used as a Standalone Library

Qute is primarily designed as a Quarkus extension.
However. it is possible to use it as a "standalone" library.
In this case, some features are not available and some additional configuration is needed.

Engine:: First of all, no managed `Engine` instance is available out of the box.
You'll need to configure a new instance via `Engine.builder()`.

Templates::
* By default, no <<template-locator,template locators>> are registered, i.e. `Engine.getTemplate(String)` will not work.
* You can register a custom template locator or parse a template manually and put the reulst in the cache via `Engine.putTemplate(String, Template)`.

Value resolvers::
* No <<value-resolvers,``ValueResolver``s>> are generated automatically.
** <<template_extension_methods,`@TemplateExtension` methods>> will not work.
** <<template_data,`@TemplateData`>> annotations are ignored.
* It's recommended to register a `ReflectionValueResolver` instance via `Engine.addValueResolver(new ReflectionValueResolver())` so that Qute can access object properties and call public methods.
+
NOTE: Keep in mind that reflection may not work correctly in some restricted environments or may require additional configuration, e.g. registration in case of a GraalVM native image.
* A custom value resolver can be easily built via `ValueResolver.builder()`

Type-safety::
* <<typesafe_expressions>> are not validated.
* <<type-safe-message-bundles,Type-safe message bundles>> are not supported.

Injection:: It is not possible to inject a `Template` instance and vice versa - a template cannot inject a `@Named` CDI bean via the `inject:` namespace.

0 comments on commit 0132488

Please sign in to comment.