From 8e83e5d1fe14403437ab7ff737676a5a2cd91166 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20ALLEMAND?= Date: Tue, 5 Mar 2024 15:26:55 +0100 Subject: [PATCH] Doc: Little rework of DevUi documentation --- docs/src/main/asciidoc/dev-ui.adoc | 68 +++++++++++++++++------------- 1 file changed, 38 insertions(+), 30 deletions(-) diff --git a/docs/src/main/asciidoc/dev-ui.adoc b/docs/src/main/asciidoc/dev-ui.adoc index b7b2d52f966a8..362cc567b6f10 100644 --- a/docs/src/main/asciidoc/dev-ui.adoc +++ b/docs/src/main/asciidoc/dev-ui.adoc @@ -15,37 +15,45 @@ include::_attributes.adoc[] This guide covers the Dev UI v2, which is the default from Quarkus 3 onwards. ==== -This guide covers the Quarkus Dev UI for xref:building-my-first-extension.adoc[extension authors]. - -Quarkus ships with a Developer UI, which is available in dev mode (when you start -quarkus with `mvn quarkus:dev`) at http://localhost:8080/q/dev-ui[/q/dev-ui] by default. It will show you something like -this: +Quarkus ships with a Developer UI which is available in dev mode and provides a set of tools to help you develop your application. -image::dev-ui-overview-v2.png[alt=Dev UI overview,role="center"] +When you start quarkus with `mvn quarkus:dev` the Dev ui is available at http://localhost:8080/q/dev-ui[/q/dev-ui] by default. It allows you to: - quickly visualize all the extensions currently loaded -- view extension statuses and go directly to extension documentation +- view extension statuses and go directly to extension documentation - view and change `Configuration` - manage and visualize `Continuous Testing` - view `Dev Services` information - view the Build information - view and stream various logs + +_In de prod QUARKUS_PROFILE the Dev ui is not available, see the documentation on how https://quarkus.io/guides/config-reference#default-profiles[configure it]_ + +The UI will show you something like this: + +image::dev-ui-overview-v2.png[alt=Dev UI overview,role="center"] + + Each extension used in the application will be listed and you can navigate to the guide for each extension, see some more information on the extension, and view configuration applicable for that extension: image::dev-ui-extension-card-v2.png[alt=Dev UI extension card,role="center"] + +This guide covers the Quarkus Dev UI for xref:building-my-first-extension.adoc[extension authors]. + + == Make my extension extend the Dev UI -In order to make your extension listed in the Dev UI you don't need to do anything! +In order to https://quarkus.io/guides/building-my-first-extension[make your extension] listed in the Dev UI you don't need to do anything! So you can always start with that :) Extensions can: -- <> +- <> - <> - <> - <> @@ -98,7 +106,7 @@ public CardPageBuildItem pages(NonApplicationRootPathBuildItem nonApplicationRoo [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-`; +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 @@ -108,13 +116,13 @@ image::dev-ui-extension-openapi-embed-v2.png[alt=Dev UI embedded page,role="cent 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 +==== 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 <> 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")`. +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 <> 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")`. ==== Adding labels -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 +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 - static (known at build time) `.staticLabel("staticLabelValue")` - dynamic (loaded at runtime) `.dynamicLabelJsonRPCMethodName("yourJsonRPCMethodName")` @@ -146,7 +154,7 @@ There are a few options to add full page content in Dev UI. Starting from the mo 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`: -- <> +- <> - <> - <> - <> @@ -292,7 +300,7 @@ export class QwcArcBeans extends LitElement { // <3> customElements.define('qwc-arc-beans', QwcArcBeans); // <10> ---- -<1> You can import Classes and/or functions from other libraries. +<1> You can import Classes and/or functions from other libraries. In this case we use the `LitElement` class and `html` & `css` functions from `Lit` <2> Build time data as defined in the Build step and can be imported using the key and always from `build-time-data`. All keys added in your Build step will be available. <3> The component should be named in the following format: Qwc (stands for Quarkus Web Component) then Extension Name then Page Title, all concatenated with Camel Case. This will also match the file name format as described earlier. The component should also extend `LitComponent`. @@ -306,7 +314,7 @@ In this case we use the `LitElement` class and `html` & `css` functions from `Li ===== Using Vaadin UI components for rendering -Dev UI makes extensive usage of https://vaadin.com/docs/latest/components[Vaadin web components] as UI Building blocks. +Dev UI makes extensive usage of https://vaadin.com/docs/latest/components[Vaadin web components] as UI Building blocks. As an example, the Arc Beans are rendered using a https://vaadin.com/docs/latest/components/grid[Vaadin Grid]: @@ -375,7 +383,7 @@ export class QwcArcBeans extends LitElement { resizable> `; - + } else { return html`No beans found`; } @@ -413,10 +421,10 @@ export class QwcArcBeans extends LitElement { }else if(bean.kind.toLowerCase() === "synthetic"){ level = "contrast"; } - + return html` ${level - ? html`${kind}` + ? html`${kind}` : html`${kind}` }`; } @@ -435,7 +443,7 @@ export class QwcArcBeans extends LitElement { return html` ${bean.interceptorInfos.map(interceptor => html`
- ${interceptor.interceptorClass.name} + ${interceptor.interceptorClass.name} ${interceptor.priority}
` )} @@ -523,7 +531,7 @@ You can use any combination of small, primary, pill, with icon and clickable wit Custom colours - +
@@ -549,7 +557,7 @@ You can use any combination of small, primary, pill, with icon and clickable wit
-
+
Default icon @@ -690,7 +698,7 @@ import '@quarkus-webcomponents/codeblock'; [source,html] ----
- @@ -704,7 +712,7 @@ or fetching the contents from a URL: [source,html] ----
- @@ -724,7 +732,7 @@ import 'qui-ide-link'; [source,html] ---- -[${sourceClassNameFull}]; @@ -869,7 +877,7 @@ Now, in your Runtime module create the JsonRPC Service. This class will default The return object in these methods can be: -- primitives or `String`, +- primitives or `String`, - `io.vertx.core.json.JsonArray` - `io.vertx.core.json.JsonObject` - any other POJO that can be serializable to Json @@ -904,7 +912,7 @@ https://github.com/quarkusio/quarkus/blob/main/extensions/cache/runtime/src/main *Webcomponent (Javascript) part* -Now you can use the JsonRPC controller to access the `getAll` method (and any other methods in you JsonRPC Service) +Now you can use the JsonRPC controller to access the `getAll` method (and any other methods in you JsonRPC Service) [source,javascript] ---- @@ -976,7 +984,7 @@ Java side of streaming data: public class JokesJsonRPCService { private final BroadcastProcessor jokeStream = BroadcastProcessor.create(); - + @PostConstruct void init() { Multi.createFrom().ticks().every(Duration.ofHours(4)).subscribe().with((item) -> { @@ -1008,7 +1016,7 @@ this._observer = this.jsonRpc.streamJokes().onNext(jsonRpcResponse => { //<1> this._observer.cancel(); //<2> ---- -<1> You can call the method (optionally passing in parameters) and then provide the code that will be called on the next event. +<1> You can call the method (optionally passing in parameters) and then provide the code that will be called on the next event. <2> Make sure to keep an instance of the observer to cancel later if needed. https://github.com/phillip-kruger/quarkus-jokes/blob/main/deployment/src/main/resources/dev-ui/qwc-jokes-web-components.js[Example code] @@ -1077,7 +1085,7 @@ static properties = { extensionName: {type: String}, description: {type: String}, guide: {type: String}, - namespace: {type: String} + namespace: {type: String} } ----