Skip to content

Commit

Permalink
Enhance JBang Documentation with Configuration and Qute Template
Browse files Browse the repository at this point in the history
The existing configuration section was not functional due to issue #30087. This commit addresses this by documenting alternative methods using `application.properties` or `application.yaml`, as recommended in issue #41739.

Additionally, integrating Qute templates was not straightforward. This commit adds a dedicated section to the JBang documentation, providing instructions on how to include and use Qute templates.
  • Loading branch information
cescoffier committed Jul 7, 2024
1 parent b8fbbed commit 17dccdd
Showing 1 changed file with 35 additions and 7 deletions.
42 changes: 35 additions & 7 deletions docs/src/main/asciidoc/scripting.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -375,18 +375,29 @@ With that in place running `jbang quarkusapp.java` will log and render as expect

== Configuring Application

Check warning on line 376 in docs/src/main/asciidoc/scripting.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.Headings] Use sentence-style capitalization in 'Configuring Application'. Raw Output: {"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Configuring Application'.", "location": {"path": "docs/src/main/asciidoc/scripting.adoc", "range": {"start": {"line": 376, "column": 4}}}, "severity": "INFO"}

You can use `//Q:CONFIG <property>=<value>` to set up static configuration for your application.
To configure the application you can use the `application.properties` file as usual, but you need to _add_ it to the script:

Check warning on line 378 in docs/src/main/asciidoc/scripting.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'. Raw Output: {"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.", "location": {"path": "docs/src/main/asciidoc/scripting.adoc", "range": {"start": {"line": 378, "column": 76}}}, "severity": "INFO"}

Check warning on line 378 in docs/src/main/asciidoc/scripting.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'. Raw Output: {"message": "[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'.", "location": {"path": "docs/src/main/asciidoc/scripting.adoc", "range": {"start": {"line": 378, "column": 94}}}, "severity": "INFO"}

I.e. if you wanted to add the `smallrye-openapi` and `swagger-ui` extensions and have the Swagger UI always show up you would add the following:
[source,java]
----
//FILES application.properties
[source,java,subs=attributes+]
// ...
@ConfigProperty(name = "prefix", defaultValue = "WG -")
String prefix;
----

This will make the `application.properties` file available to the script, and process the configuration as usual.

Check warning on line 389 in docs/src/main/asciidoc/scripting.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'. Raw Output: {"message": "[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'.", "location": {"path": "docs/src/main/asciidoc/scripting.adoc", "range": {"start": {"line": 389, "column": 93}}}, "severity": "INFO"}

Check warning on line 389 in docs/src/main/asciidoc/scripting.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'. Raw Output: {"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.", "location": {"path": "docs/src/main/asciidoc/scripting.adoc", "range": {"start": {"line": 389, "column": 105}}}, "severity": "INFO"}

You can also use the `application.yaml` file.
For this, you need to _add_ it to the `application.yaml` file to the script and include the `quarkus-config-yaml` dependency:

[source,java]
----
//DEPS io.quarkus:quarkus-smallrye-openapi:{quarkus-version}
//DEPS io.quarkus:quarkus-swagger-ui:{quarkus-version}
//Q:CONFIG quarkus.swagger-ui.always-include=true
//DEPS io.quarkus:quarkus-config-yaml
//FILES application.yaml
----

Now during build the `quarkus.swagger-ui.always-include` will be generated into the resulting jar and `http://0.0.0.0:8080/q/swagger-ui` will be available when run.
NOTE: The path to the `application.properties` and `application.yaml` files are relative to the script file.

== Running as a native application

Check warning on line 402 in docs/src/main/asciidoc/scripting.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'. Raw Output: {"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.", "location": {"path": "docs/src/main/asciidoc/scripting.adoc", "range": {"start": {"line": 402, "column": 12}}}, "severity": "INFO"}

Expand Down Expand Up @@ -440,6 +451,23 @@ __ ____ __ _____ ___ __ ____ ______
2023-03-22 09:38:45,450 INFO [io.quarkus] (main) Installed features: [cdi, rest, smallrye-context-propagation, vertx]
----

=== Using Qute

You can use the xref:./qute.adoc[Qute templating engine] in your JBang script by adding the `quarkus-qute` dependency.

Check warning on line 456 in docs/src/main/asciidoc/scripting.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'. Raw Output: {"message": "[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'.", "location": {"path": "docs/src/main/asciidoc/scripting.adoc", "range": {"start": {"line": 456, "column": 34}}}, "severity": "INFO"}
You also need to include the `templates` directory in the script:
[source,java]
----
//DEPS io.quarkus:quarkus-qute
//FILES templates/=templates/*
// ...
@Inject
Template template; // Locate and load the `templates/template.html` file
----

If your `templates` directory includes sub-directories, use `templates/=templates/**/*` instead.

=== Conclusion

If you want to get started with Quarkus or write something quickly, Quarkus Scripting with jbang lets you do that. No Maven, no Gradle - just a Java file. In this guide we outlined the very basics on using Quarkus with JBang; if you want to learn more about what JBang can do, go see https://jbang.dev.

Check warning on line 473 in docs/src/main/asciidoc/scripting.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.Spelling] Use correct American English spelling. Did you really mean 'jbang'? Raw Output: {"message": "[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'jbang'?", "location": {"path": "docs/src/main/asciidoc/scripting.adoc", "range": {"start": {"line": 473, "column": 92}}}, "severity": "WARNING"}

Check warning on line 473 in docs/src/main/asciidoc/scripting.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/scripting.adoc", "range": {"start": {"line": 473, "column": 200}}}, "severity": "INFO"}

0 comments on commit 17dccdd

Please sign in to comment.