User Name Input
diff --git a/_guides/security-customization.adoc b/_guides/security-customization.adoc index ab7faf8f9f..fedc190135 100644 --- a/_guides/security-customization.adoc +++ b/_guides/security-customization.adoc @@ -4,7 +4,6 @@ and pull requests should be submitted there: https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// = Security Tips and Tricks - include::_attributes.adoc[] == Quarkus Security Dependency @@ -621,6 +620,6 @@ xref:context-propagation.adoc[Context Propagation Guide]. == References * xref:security-overview.adoc[Quarkus Security overview] -* xref:security-architecture.adoc[Quarkus Security architecture] +* xref:security-architecture.adoc[Quarkus Security architecture] * xref:security-authentication-mechanisms.adoc#other-supported-authentication-mechanisms[Authentication mechanisms in Quarkus] * xref:security-identity-providers.adoc[Identity providers] diff --git a/_guides/security-jpa.adoc b/_guides/security-jpa.adoc index eb5faa68d4..8a5eaf4d13 100644 --- a/_guides/security-jpa.adoc +++ b/_guides/security-jpa.adoc @@ -1,3 +1,8 @@ +//// +This document is maintained in the main Quarkus repository +and pull requests should be submitted there: +https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc +//// [id="security-jpa"] = Quarkus Security with Jakarta Persistence include::_attributes.adoc[] diff --git a/_guides/security-jwt-build.adoc b/_guides/security-jwt-build.adoc index 9348c4629d..d96d1c1c8f 100644 --- a/_guides/security-jwt-build.adoc +++ b/_guides/security-jwt-build.adoc @@ -4,7 +4,6 @@ and pull requests should be submitted there: https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// = Build, Sign and Encrypt JSON Web Tokens - include::_attributes.adoc[] According to link:https://datatracker.ietf.org/doc/html/rfc7519[RFC7519], JSON Web Token (JWT) is a compact, URL-safe means of representing claims which are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code(MAC) and/or encrypted. diff --git a/_guides/security-keycloak-admin-client.adoc b/_guides/security-keycloak-admin-client.adoc index c27caf445b..7a82118a0c 100644 --- a/_guides/security-keycloak-admin-client.adoc +++ b/_guides/security-keycloak-admin-client.adoc @@ -4,8 +4,9 @@ and pull requests should be submitted there: https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// = Using Keycloak Admin Client - include::_attributes.adoc[] +:categories: security +:keywords: sso oidc security keycloak The Quarkus Keycloak Admin Client and its reactive twin support Keycloak Admin Client which can be used to configure a running Keycloak server. diff --git a/_guides/security-keycloak-authorization.adoc b/_guides/security-keycloak-authorization.adoc index 9a2ca199c9..f8b5024e74 100644 --- a/_guides/security-keycloak-authorization.adoc +++ b/_guides/security-keycloak-authorization.adoc @@ -6,6 +6,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc = Using OpenID Connect (OIDC) and Keycloak to Centralize Authorization include::_attributes.adoc[] :categories: security +:keywords: sso oidc security keycloak :summary: This guide demonstrates how your Quarkus application can authorize access to protected resources using Keycloak Authorization Services. This guide demonstrates how your Quarkus application can authorize a bearer token access to protected resources using https://www.keycloak.org/docs/latest/authorization_services/index.html[Keycloak Authorization Services]. diff --git a/_guides/security-oauth2.adoc b/_guides/security-oauth2.adoc index 9778c6883f..47b4199a03 100644 --- a/_guides/security-oauth2.adoc +++ b/_guides/security-oauth2.adoc @@ -6,6 +6,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc = Using OAuth2 RBAC include::_attributes.adoc[] :categories: security +:keywords: oauth :summary: This guide explains how your Quarkus application can utilize OAuth2 tokens to provide secured access to the Jakarta REST endpoints. :extension-name: Elytron Security OAuth2 diff --git a/_guides/security-oidc-code-flow-authentication-tutorial.adoc b/_guides/security-oidc-code-flow-authentication-tutorial.adoc index 3d7e1a525f..a6c8df4355 100644 --- a/_guides/security-oidc-code-flow-authentication-tutorial.adoc +++ b/_guides/security-oidc-code-flow-authentication-tutorial.adoc @@ -1,3 +1,8 @@ +//// +This document is maintained in the main Quarkus repository +and pull requests should be submitted there: +https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc +//// [id="security-oidc-code-flow-authentication-tutorial"] = Protect a web application by using OpenID Connect (OIDC) authorization code flow include::_attributes.adoc[] diff --git a/_guides/security-openid-connect-client-reference.adoc b/_guides/security-openid-connect-client-reference.adoc index f62ed9e681..2012fe9d79 100644 --- a/_guides/security-openid-connect-client-reference.adoc +++ b/_guides/security-openid-connect-client-reference.adoc @@ -4,7 +4,6 @@ and pull requests should be submitted there: https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// = OpenID Connect (OIDC) and OAuth2 Client and Filters Reference Guide - include::_attributes.adoc[] This reference guide explains how to use: diff --git a/_guides/security-openid-connect-dev-services.adoc b/_guides/security-openid-connect-dev-services.adoc index 442c8a663b..2e8f93d2b2 100644 --- a/_guides/security-openid-connect-dev-services.adoc +++ b/_guides/security-openid-connect-dev-services.adoc @@ -6,6 +6,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc = Dev Services and UI for OpenID Connect (OIDC) include::_attributes.adoc[] :categories: security +:keywords: sso oidc security keycloak :summary: Start Keycloak or other providers automatically in dev and test modes. This guide covers the Dev Services and UI for OpenID Connect (OIDC) Keycloak provider and explains how to support Dev Services and UI for other OpenID Connect providers. diff --git a/_guides/security-openid-connect-multitenancy.adoc b/_guides/security-openid-connect-multitenancy.adoc index e9d0d0e48a..bd444ef9f9 100644 --- a/_guides/security-openid-connect-multitenancy.adoc +++ b/_guides/security-openid-connect-multitenancy.adoc @@ -6,6 +6,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc = Using OpenID Connect (OIDC) Multi-Tenancy include::_attributes.adoc[] :categories: security +:keywords: sso oidc oauth2 security :summary: This guide demonstrates how your OpenID Connect application can support multi-tenancy so that you can serve multiple tenants from a single application. This guide demonstrates how your OpenID Connect (OIDC) application can support multi-tenancy so that you can serve multiple tenants from a single application. Tenants can be distinct realms or security domains within the same OpenID Provider or even distinct OpenID Providers. @@ -590,9 +591,9 @@ To configure the resolution of the tenant identifier, use one of the following o [[default-tenant-resolver]] === Default resolution -The default resolution for a tenant identifier is convention based, whereby the authentication request must include the tenant identifier in the last segment of the request path. +The default resolution for a tenant identifier is convention based, whereby the authentication request must include the tenant identifier in the last segment of the request path. -The following `application.properties` example shows how you can configure two tenants named `google` and `github`: +The following `application.properties` example shows how you can configure two tenants named `google` and `github`: [source,properties] ---- @@ -609,7 +610,7 @@ quarkus.oidc.github.credentials.secret=${github-client-secret} quarkus.oidc.github.authentication.redirect-path=/signed-in ---- -In this example, both tenants configure OIDC `web-app` applications to use an authorization code flow to authenticate users and also require session cookies to get generated after the authentication has taken place. +In this example, both tenants configure OIDC `web-app` applications to use an authorization code flow to authenticate users and also require session cookies to get generated after the authentication has taken place. After either Google or GitHub authenticates the current user, the user gets returned to the `/signed-in` area for authenticated users, for example, a secured resource path on the JAX-RS endpoint. Finally, to complete the default tenant resolution, set the following configuration property: @@ -620,8 +621,8 @@ quarkus.http.auth.permission.login.paths=/google,/github quarkus.http.auth.permission.login.policy=authenticated ---- -If the endpoint is running on `http://localhost:8080`, you can also provide UI options for users to log in to either `http://localhost:8080/google` or `http://localhost:8080/github`, without having to add specific`/google` or `/github` JAX-RS resource paths. -Tenant identifiers are also recorded in the session cookie names after the authentication is completed. +If the endpoint is running on `http://localhost:8080`, you can also provide UI options for users to log in to either `http://localhost:8080/google` or `http://localhost:8080/github`, without having to add specific`/google` or `/github` JAX-RS resource paths. +Tenant identifiers are also recorded in the session cookie names after the authentication is completed. Therefore, authenticated users can access the secured application area without requiring either the `google` or `github` path values to be included in the secured URL. Default resolution can also work for Bearer token authentication but it might be less practical in this case because a tenant identifier will always need to be set as the last path segment value. @@ -629,7 +630,7 @@ Default resolution can also work for Bearer token authentication but it might be [[tenant-resolver]] === Resolve with `TenantResolver` -The following `application.properties` example shows how you can resolve the tenant identifier of two tenants named `a` and `b` by using the `TenantResolver` method: +The following `application.properties` example shows how you can resolve the tenant identifier of two tenants named `a` and `b` by using the `TenantResolver` method: [source,properties] ---- diff --git a/_guides/security-openid-connect-providers.adoc b/_guides/security-openid-connect-providers.adoc index eb204a6111..266d22c53c 100644 --- a/_guides/security-openid-connect-providers.adoc +++ b/_guides/security-openid-connect-providers.adoc @@ -8,6 +8,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :diataxis-type: concept :categories: security,web +:keywords: oidc github twitter google facebook mastodon microsoft apple spotify twitch :toclevels: 3 This document explains how to configure well-known social OIDC and OAuth2 providers. @@ -178,7 +179,7 @@ quarkus.oidc.token.customizer-name=azure-access-token-customizer [[apple]] === Apple -In order to set up OIDC for Apple you need to create a developer account, and sign up for the 99€/year program, but you cannot test your application on `localhost` like most other OIDC providers: +In order to set up OIDC for Apple you need to create a developer account, and sign up for the 99€/year program, but you cannot test your application on `localhost` like most other OIDC providers: you will need to run it over `https` and make it publicly accessible, so for development purposes you may want to use a service such as https://ngrok.com. @@ -287,7 +288,7 @@ quarkus.oidc.credentials.jwt.subject=| Timestamp | -User | -Joke | -
|---|---|---|
| {joke.timestamp} | -{joke.fullJoke} | -
-
- ${this._beans.map((bean) => // <9>
- html`
- ${bean.providerType.name} ` - )}
@${bean.scope.simpleName}
- ${bean.nonDefaultQualifiers.map(qualifier =>
- html`${this._qualifierRenderer(qualifier)}`
- )}
- ${bean.providerType.name}
- ${bean.declaringClass.simpleName}.${bean.memberName}()`
- : html`${bean.memberName}`
- }
- `;
- }
-
- _interceptorsRenderer(bean) {
- if (bean.interceptors && bean.interceptors.length > 0) {
- return html`
- ${interceptor.priority}
-
`
- )}
- ${interceptor.interceptorClass.name}
- ${qualifier.simpleName}`;
- }
-
- _camelize(str) {
- return str.replace(/(?:^\w|[A-Z]|\b\w|\s+)/g, function (match, index) {
- if (+match === 0)
- return "";
- return index === 0 ? match.toUpperCase() : match.toLowerCase();
- });
- }
-}
-customElements.define('qwc-arc-beans', QwcArcBeans);
-----
-<1> Import the Vaadin component you want to use
-<2> You can also import other functions if needed
-<3> There are some internal UI components that you can use, described below
-
-===== Using internal UI components
-
-Some https://github.com/quarkusio/quarkus/tree/main/extensions/vertx-http/dev-ui-resources/src/main/resources/dev-ui/qui[internal UI components] (under the `qui` namespace) are available to make certain things easier:
-
-- Card
-- Badge
-- Alert
-- Code block
-- IDE Link
-
-====== Card
-
-Card component to display contents in a card
-
-[source,javascript]
-----
-import 'qui-card';
-----
-
-[source,html]
-----
-
- My contents
-
-
-
-----
-
-https://github.com/phillip-kruger/quarkus-jokes/blob/f572ed6f949de0c0b8cbfa99d7389ab5168fea65/deployment/src/main/resources/dev-ui/qwc-jokes-vaadin.js#L214[Example code]
-
-====== Alert
-
-Alerts are modeled around the Bootstrap alerts. Click https://getbootstrap.com/docs/4.0/components/alerts[here] for more info.
-
-Also see Notification controller below as an alternative.
-
-image::dev-ui-qui-alert-v2.png[alt=Dev UI Alert,role="center"]
-
-[source,javascript]
-----
-import 'qui-alert';
-----
-
-[source,html]
-----
-Badges
-Badges wrap the Vaadin theme in a component. - See https://vaadin.com/docs/latest/components/badge for more info. -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Default
- Success
- Warning
- Error
- Contrast
- Custom colours
-
-
-
-
- Default primary
- Success primary
- Warning primary
- Error primary
- Contrast primary
- Custom colours
-
-
-
-
- Default pill
- Success pill
- Warning pill
- Error pill
- Contrast pill
- Custom colours
-
-
-
-
-
- Default icon
-
-
- Success icon
-
-
- Warning icon
-
-
- Error icon
-
-
- Contrast icon
-
-
- Custom colours
-
-
-
-
-
-
-
-
-
- this._info()}>Default
- this._success()}>Success
- this._warning()}>Warning
- this._error()}>Error
- this._contrast()}>Contrast
- this._info()}>Custom colours
-
-
-
-----
-
-https://github.com/phillip-kruger/quarkus-jokes/blob/f572ed6f949de0c0b8cbfa99d7389ab5168fea65/deployment/src/main/resources/dev-ui/qwc-jokes-vaadin.js#L316[Example code]
-
-
-====== Code block
-
-Display a code block. This component is aware of the theme and will use the correct codemirror theme to match the light/dark mode.
-
-
-image::dev-ui-qui-code-block-v2.png[alt=Dev UI Code Block,role="center"]
-
-[source,javascript]
-----
-import 'qui-code-block';
-----
-
-[source,html]
-----
-
- Info alert
- Success alert
- Warning alert
- Error alert
-
-Permanent Info alert
- Permanent Success alert
- Permanent Warning alert
- Permanent Error alert
-
-Center Info alert
- Center Success alert
- Center Warning alert
- Center Error alert
-
-Info alert with icon
- Success alert with icon
- Warning alert with icon
- Error alert with icon
-
-Info alert with custom icon
- Success alert with custom icon
- Warning alert with custom icon
- Error alert with custom icon
-
-Small Info alert with icon
- Small Success alert with icon
- Small Warning alert with icon
- Small Error alert with icon
-
-Info
quarkus.io
- Success
quarkus.io
- Warning
quarkus.io
- Error
quarkus.io
-
-Primary Info alert with icon
- Primary Success alert with icon
- Primary Warning alert with icon
- Primary Error alert with icon
-
-Info alert with title
- Success alert with title
- Warning alert with title
- Error alert with title
-
-Info alert with title and icon
- Success alert with title and icon
- Warning alert with title and icon
- Error alert with title and icon
-
--
-
-
-
-
-
alert with markup quarkus.io
alert with markup quarkus.io
alert with markup quarkus.io
alert with markup quarkus.io
-
-
-
-
-
-
;
-----
-
-https://github.com/quarkusio/quarkus/blob/e03a97845738436c69443a591ec4ce88ed04ac91/extensions/kubernetes/vanilla/deployment/src/main/resources/dev-ui/qwc-kubernetes-manifest.js#L99[Example code]
-
-or fetching the contents from a URL:
-
-[source,html]
-----
-
-
-
-
-----
-
-https://github.com/quarkusio/quarkus/blob/95c54fa46a6b6f31d69477234486d9359a2a3a4a/extensions/vertx-http/dev-ui-resources/src/main/resources/dev-ui/qwc/qwc-external-page.js#L116[Example code]
-
-====== IDE link
-
-Creates a link to a resource (like a Java source file) that can be opened in the user's IDE (if we could detect the IDE).
-
-[source,javascript]
-----
-import 'qui-ide-link';
-----
-
-[source,html]
-----
-- - - Swagger UI +@BuildStep(onlyIf = IsDevelopment.class)// <1> +public CardPageBuildItem pages(NonApplicationRootPathBuildItem nonApplicationRootPathBuildItem) { + + CardPageBuildItem cardPageBuildItem = new CardPageBuildItem(); // <2> + + cardPageBuildItem.addPage(Page.externalPageBuilder("Schema yaml") // <3> + .url(nonApplicationRootPathBuildItem.resolvePath("openapi")) // <4> + .isYamlContent() // <5> + .icon("font-awesome-solid:file-lines")); // <6> + + cardPageBuildItem.addPage(Page.externalPageBuilder("Schema json") + .url(nonApplicationRootPathBuildItem.resolvePath("openapi") + "?format=json") + .isJsonContent() + .icon("font-awesome-solid:file-code")); + + cardPageBuildItem.addPage(Page.externalPageBuilder("Swagger UI") + .url(nonApplicationRootPathBuildItem.resolvePath("swagger-ui")) + .isHtmlContent() + .icon("font-awesome-solid:signs-post")); + + return cardPageBuildItem; +} ---- +<1> Always make sure that this build step is only run when in dev mode +<2> To add anything on the card, you need to return/produce a `CardPageBuildItem`. +<3> To add a link, you can use the `addPage` method, as all links go to a "page". `Page` has some builders to assist with building a page. For `external` links, use the `externalPageBuilder` +<4> Adding the url of the external link (in this case we use `NonApplicationRootPathBuildItem` to create this link, as this link is under the configurable non application path, default `/q`). Always use `NonApplicationRootPathBuildItem` if your link is available under `/q`. +<5> You can (optionally) hint the content type of the content you are navigating to. If there is no hint, a header call will be made to determine the `MediaType`; +<6> You can add an icon. All free font-awesome icons are available. + +[NOTE] +.Note about icons + +If you find your icon at https://fontawesome.com/search?o=r&m=free[Font awesome], you can map as follow: Example `` will map to `font-awesome-solid:house`, so `fa` becomes `font-awesome` and for the icon name, remove the `fa-`; + +==== Embedding external content + +By default, even external links will render inside (embedded) in Dev UI. In the case of HTML, the page will be rendered and any other content will be shown using https://codemirror.net/[code-mirror] to markup the media type. For example the open api schema document in `yaml` format: + +image::dev-ui-extension-openapi-embed-v2.png[alt=Dev UI embedded page,role="center"] + +If you do not want to embed the content, you can use the `.doNotEmbed()` on the Page Builder, this will then open the link in a new tab. + +==== Runtime external links + +The example above assumes you know the link to use at build time. There might be cases where you only know this at runtime. In that case you can use a xref:JsonRPC[JsonRPC] Method that returns the link to add, and use that when creating the link. Rather than using the `.url` method on the page builder, use the `.dynamicUrlJsonRPCMethodName("yourJsonRPCMethodName")`. -TIP: We use the Font Awesome Free icon set. +==== Adding labels -Note how the paths are specified: `{config:http-path('quarkus.smallrye-openapi.path')}`. This is a special -directive that the quarkus dev console understands: it will replace that value with the resolved route -named 'quarkus.smallrye-openapi.path'. +You can add an option label to the link in the card using one of the builder methods on the page builder. These labels can be -The corresponding non-application endpoint is declared using `.routeConfigKey` to associate the route with a name: +- static (known at build time) `.staticLabel("staticLabelValue")` +- dynamic (loaded at runtime) `.dynamicLabelJsonRPCMethodName("yourJsonRPCMethodName")` +- streaming (continuously streaming updated values at runtime) `.streamingLabelJsonRPCMethodName("yourJsonRPCMethodName")` + +For dynamic and streaming labels, see the xref:JsonRPC[JsonRPC] Section. + +image::dev-ui-extension-card-label-v2.png[alt=Dev UI card labels,role="center"] + +== Add full pages + +You can also link to an "internal" page (as opposed to the above "external" page). This means that you can build the page and add data and actions for rendering in Dev UI. + +=== Build time data + +To make build time data available in your full page, you can add any data to your `CardPageBuildItem` with a key and a value: [source,java] ---- - nonApplicationRootPathBuildItem.routeBuilder() - .route(openApiConfig.path) // <1> - .routeConfigKey("quarkus.smallrye-openapi.path") // <2> - ... - .build(); +CardPageBuildItem pageBuildItem = new CardPageBuildItem(); +pageBuildItem.addBuildTimeData("someKey", getSomeValueObject()); ---- -<1> The configured path is resolved into a valid route. -<2> The resolved route path is then associated with the key `quarkus.smallrye-openapi.path`. -== Path considerations +You can add multiple of these key-value pairs for all the data you know at build time that you need on the page. -Paths are tricky business. Keep the following in mind: +There are a few options to add full page content in Dev UI. Starting from the most basic (good start) to a full blown web-component (preferred). -* Assume your UI will be nested under the dev endpoint. Do not provide a way to customize this without a strong reason. -* Never construct your own absolute paths. Adding a suffix to a known, normalized and resolved path is fine. +=== Display some build time data on a screen (without having to do frontend coding): -Configured paths, like the `dev` endpoint used by the console or the SmallRye OpenAPI path shown in the example above, -need to be properly resolved against both `quarkus.http.root-path` and `quarkus.http.non-application-root-path`. -Use `NonApplicationRootPathBuildItem` or `HttpRootPathBuildItem` to construct endpoint routes and identify resolved -path values that can then be used in templates. +If you have some data that is known at build time that you want to display you can use one of the following builders in `Page`: -The `{devRootAppend}` variable can also be used in templates to construct URLs for static dev console resources, for example: +- xref:raw-data[Raw data] +- xref:table-data[Table data] +- xref:qute-data[Qute data] +- xref:web-component-page[Web Component page] -[source,html] +==== Raw data +This will display your data in it's raw (serialised) json value: + +[source,java] ---- -
+cardPageBuildItem.addPage(Page.rawDataPageBuilder("Raw data") // <1>
+ .icon("font-awesome-brands:js")
+ .buildTimeDataKey("someKey")); // <2>
----
+<1> Use the `rawDataPageBuilder`.
+<2> Link back to the key used when you added the build time data in `addBuildTimeData` on the Page BuildItem.
-Refer to the xref:all-config.adoc#quarkus-vertx-http_quarkus.http.non-application-root-path[Quarkus Vertx HTTP configuration reference]
-for details on how the non-application root path is configured.
+That will create a link to a page that renders the raw data in json:
-== Template and styling support
+image::dev-ui-raw-page-v2.png[alt=Dev UI raw page,role="center"]
-Both the `embedded.html` files and any full page you add in `/dev-templates` will be interpreted by
-xref:qute.adoc[the Qute template engine].
+==== Table data
-This also means that you can xref:qute-reference.adoc#user_tags[add custom Qute tags] in
-`/dev-templates/tags` for your templates to use.
+You can also display your Build time data in a table if the structure allows it:
-The style system currently in use is https://getbootstrap.com/docs/4.6/getting-started/introduction/[Bootstrap V4 (4.6.0)]
-but note that this might change in the future.
+[source,java]
+----
+cardPageBuildItem.addPage(Page.tableDataPageBuilder("Table data") // <1>
+ .icon("font-awesome-solid:table")
+ .showColumn("timestamp") // <2>
+ .showColumn("user") // <2>
+ .showColumn("fullJoke") // <2>
+ .buildTimeDataKey("someKey")); // <3>
+----
+<1> Use the `tableDataPageBuilder`.
+<2> Optionally only show certain fields.
+<3> Link back to the key used when you added the build time data in `addBuildTimeData` on the Page BuildItem.
+
+That will create a link to a page that renders the data in a table:
-The main template also includes https://jquery.com/[jQuery 3.5.1], but here again this might change.
+image::dev-ui-table-page-v2.png[alt=Dev UI table page,role="center"]
-=== Accessing Config Properties
+==== Qute data
-A `config:property(name)` expression can be used to output the config value for the given property name.
-The property name can be either a string literal or obtained dynamically by another expression.
-For example `{config:property('quarkus.lambda.handler')}` and `{config:property(foo.propertyName)}`.
+You can also display your build time data using a qute template. All build time data keys are available to use in the template:
-Reminder: do not use this to retrieve raw configured path values. As shown above, use `{config:http-path(...)}` with
-a known route configuration key when working with resource paths.
+[source,java]
+----
+cardPageBuildItem.addPage(Page.quteDataPageBuilder("Qute data") // <1>
+ .icon("font-awesome-solid:q")
+ .templateLink("qute-jokes-template.html")); // <2>
+----
+<1> Use the `quteDataPageBuilder`.
+<2> Link to the Qute template in `/deployment/src/main/resources/dev-ui/`.
-== Adding full pages
+Using any Qute template to display the data, for example `qute-jokes-template.html`:
-To add full pages for your Dev UI extension such as this one:
+[source,html]
+----
+| Timestamp | +User | +Joke | +
|---|---|---|
| {joke.timestamp} | +{joke.fullJoke} | +
-
+ ${this._beans.map((bean) => // <9>
+ html`
- ${bean.providerType.name} ` + )}
@${bean.scope.simpleName}
+ ${bean.nonDefaultQualifiers.map(qualifier =>
+ html`${this._qualifierRenderer(qualifier)}`
+ )}
+ ${bean.providerType.name}
+ ${bean.declaringClass.simpleName}.${bean.memberName}()`
+ : html`${bean.memberName}`
+ }
+ `;
+ }
+
+ _interceptorsRenderer(bean) {
+ if (bean.interceptors && bean.interceptors.length > 0) {
+ return html`
+ ${interceptor.priority}
+
`
+ )}
+ ${interceptor.interceptorClass.name}
+ ${qualifier.simpleName}`;
+ }
+
+ _camelize(str) {
+ return str.replace(/(?:^\w|[A-Z]|\b\w|\s+)/g, function (match, index) {
+ if (+match === 0)
+ return "";
+ return index === 0 ? match.toUpperCase() : match.toLowerCase();
});
- });
- {/script}
- {#title}Cache{/title}// <4>
- {#body}// <5>
- | Name | -Size | -
|---|---|
| - {cacheInfo.name} - | -- - | -
+ My contents
+
+
+
+----
+
+https://github.com/phillip-kruger/quarkus-jokes/blob/f572ed6f949de0c0b8cbfa99d7389ab5168fea65/deployment/src/main/resources/dev-ui/qwc-jokes-vaadin.js#L214[Example code]
+
+====== Alert
+
+Alerts are modeled around the Bootstrap alerts. Click https://getbootstrap.com/docs/4.0/components/alerts[here] for more info.
+
+Also see Notification controller below as an alternative.
+
+image::dev-ui-qui-alert-v2.png[alt=Dev UI Alert,role="center"]
+
+[source,javascript]
+----
+import 'qui-alert';
+----
+
+[source,html]
+----
+Badges
+Badges wrap the Vaadin theme in a component. + See https://vaadin.com/docs/latest/components/badge for more info. +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Default
+ Success
+ Warning
+ Error
+ Contrast
+ Custom colours
+
+
+
+
+ Default primary
+ Success primary
+ Warning primary
+ Error primary
+ Contrast primary
+ Custom colours
+
+
+
+
+ Default pill
+ Success pill
+ Warning pill
+ Error pill
+ Contrast pill
+ Custom colours
+
+
+
+
+
+ Default icon
+
+
+ Success icon
+
+
+ Warning icon
+
+
+ Error icon
+
+
+ Contrast icon
+
+
+ Custom colours
+
+
+
+
+
+
+
+
+
+ this._info()}>Default
+ this._success()}>Success
+ this._warning()}>Warning
+ this._error()}>Error
+ this._contrast()}>Contrast
+ this._info()}>Custom colours
+
+
+
+----
+
+https://github.com/phillip-kruger/quarkus-jokes/blob/f572ed6f949de0c0b8cbfa99d7389ab5168fea65/deployment/src/main/resources/dev-ui/qwc-jokes-vaadin.js#L316[Example code]
+
+
+====== Code block
+
+Display a code block. This component is aware of the theme and will use the correct codemirror theme to match the light/dark mode.
+
+
+image::dev-ui-qui-code-block-v2.png[alt=Dev UI Code Block,role="center"]
+
+[source,javascript]
+----
+import 'qui-code-block';
+----
+
+[source,html]
+----
+
+ Info alert
+ Success alert
+ Warning alert
+ Error alert
+
+Permanent Info alert
+ Permanent Success alert
+ Permanent Warning alert
+ Permanent Error alert
+
+Center Info alert
+ Center Success alert
+ Center Warning alert
+ Center Error alert
+
+Info alert with icon
+ Success alert with icon
+ Warning alert with icon
+ Error alert with icon
+
+Info alert with custom icon
+ Success alert with custom icon
+ Warning alert with custom icon
+ Error alert with custom icon
+
+Small Info alert with icon
+ Small Success alert with icon
+ Small Warning alert with icon
+ Small Error alert with icon
+
+Info
quarkus.io
+ Success
quarkus.io
+ Warning
quarkus.io
+ Error
quarkus.io
+
+Primary Info alert with icon
+ Primary Success alert with icon
+ Primary Warning alert with icon
+ Primary Error alert with icon
+
+Info alert with title
+ Success alert with title
+ Warning alert with title
+ Error alert with title
+
+Info alert with title and icon
+ Success alert with title and icon
+ Warning alert with title and icon
+ Error alert with title and icon
+
++
+
+
+
+
+
alert with markup quarkus.io
alert with markup quarkus.io
alert with markup quarkus.io
alert with markup quarkus.io
+
+
+
+
+
+
;
+----
+
+https://github.com/quarkusio/quarkus/blob/e03a97845738436c69443a591ec4ce88ed04ac91/extensions/kubernetes/vanilla/deployment/src/main/resources/dev-ui/qwc-kubernetes-manifest.js#L99[Example code]
+
+or fetching the contents from a URL:
+
+[source,html]
+----
+
+
+
+
+----
+
+https://github.com/quarkusio/quarkus/blob/95c54fa46a6b6f31d69477234486d9359a2a3a4a/extensions/vertx-http/dev-ui-resources/src/main/resources/dev-ui/qwc/qwc-external-page.js#L116[Example code]
+
+====== IDE link
+
+Creates a link to a resource (like a Java source file) that can be opened in the user's IDE (if we could detect the IDE).
+
+[source,javascript]
+----
+import 'qui-ide-link';
+----
+
+[source,html]
+----
+-
-
- Foo 100 - +
- Foo 100 +
-
-
+
- Foo 100 - - + +
-
{#for item in item.derivedItems} <2>
- - {item.name} <3> + {item.name} <3> is derived from {data:item.name} <4> @@ -490,7 +492,7 @@ The only difference is that for virtual methods a value resolver consumes parame
{item.buildName(item.name,5)}
<1> ---- -<1> `buildName(item.name,5)` represents a virtual method with name `buildName` and two parameters: `item.name` and `5` . The virtual method could be evaluated by a value resolver generated for the following Java class: +<1> `buildName(item.name,5)` represents a virtual method with name `buildName` and two parameters: `item.name` and `5` . The virtual method could be evaluated by a value resolver generated for the following Java class: + [source,java] ---- @@ -535,7 +537,7 @@ If a part of an expression resolves to a `Uni`, a `CompletionStage` is first cre IMPORTANT: Note that each `Uni#subscribeAsCompletionStage()` results in a new subscription. You might need to configure memoization of the `Uni` item or failure before it's used as template data, i.e. `myUni.memoize().indefinitely()`. -It can happen that a `CompletionStage` never completes or a `Uni` emits no item/failure. +It can happen that a `CompletionStage` never completes or a `Uni` emits no item/failure. In this case, the rendering methods (such as `TemplateInstance#render()` and `TemplateInstance#createUni()`) fail after a specific timeout. The timeout can be specified as a template instance `timeout` attribute. If no `timeout` attribute is set the global rendering timeout is used. @@ -639,11 +641,11 @@ A start tag can define parameters with optional names, e.g. `{#if item.isActive} 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`. +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 xref:expressions[expression] and evaluated before use. -A section may contain several content *blocks*. +A section may contain several content *blocks*. The "main" block is always present. Additional/nested blocks also start with `#` and can have parameters too - `{#else if item.isActive}`. A section helper that defines the logic of a section can "execute" any of the blocks and evaluate the parameters. @@ -685,7 +687,7 @@ The other form is using the name `for` and specifies the alias used to reference [source] ---- {#for item in items} <1> - {item.name} + {item.name} {/for} ---- <1> `item` is the alias used for the iteration element. @@ -714,7 +716,7 @@ For example, the `hasNext` key must be prefixed with `it_` inside an `{#each}` s {#if it_hasNext}{/if} <2> {/each} ---- -<1> `it_count` represents one-based index. +<1> `it_count` represents one-based index. <2> `
` is only rendered if the iteration has more elements. And must be used in a form of `{item_hasNext}` inside a `{#for}` section with the `item` element alias. @@ -727,12 +729,12 @@ And must be used in a form of `{item_hasNext}` inside a `{#for}` section with th {#if item_hasNext}
{/if} <2> {/for} ---- -<1> `item_count` represents one-based index. +<1> `item_count` represents one-based index. <2> `
` is only rendered if the iteration has more elements. [TIP] ==== -The iteration metadata prefix is configurable either via `EngineBuilder.iterationMetadataPrefix()` for standalone Qute or via the `quarkus.qute.iteration-metadata-prefix` configuration property in a Quarkus application. Three special constants can be used: +The iteration metadata prefix is configurable either via `EngineBuilder.iterationMetadataPrefix()` for standalone Qute or via the `quarkus.qute.iteration-metadata-prefix` configuration property in a Quarkus application. Three special constants can be used: 1. `
My page
-This document +
This document {#include $strong val='contains' /} <2> -a lot of +a lot of {#include $strong val='information' /} <3> !
---- @@ -1320,9 +1322,9 @@ The snippet above renders something like: [source,html] ----My page
-This document +
This document contains -a lot of +a lot of information !
---- @@ -1408,11 +1410,11 @@ template.data(foo).renderAsync().whenComplete((result, failure) -> { <1> } }; ---- -<1> Register a callback that is executed once the rendering is finished. +<1> Register a callback that is executed once the rendering is finished. There are also two methods that return https://smallrye.io/smallrye-mutiny/[Mutiny] types. `TemplateInstance.createUni()` returns a new `Uni