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

Doc: Little rework of DevUi documentation #39235

Closed
wants to merge 1 commit into from
Closed

Doc: Little rework of DevUi documentation #39235

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
68 changes: 38 additions & 30 deletions docs/src/main/asciidoc/dev-ui.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,40 +12,48 @@
[NOTE]
.Dev UI v2
====
This guide covers the Dev UI v2, which is the default from Quarkus 3 onwards.

Check warning on line 15 in docs/src/main/asciidoc/dev-ui.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 'onwards'?

Raw Output:
{"message": "[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'onwards'?", "location": {"path": "docs/src/main/asciidoc/dev-ui.adoc", "range": {"start": {"line": 15, "column": 70}}}, "severity": "WARNING"}
====

This guide covers the Quarkus Dev UI for xref:building-my-first-extension.adoc[extension authors].
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence is very important and should stay at the top.
This guide is for extension developers.

I think what actually needs an adjustment is the title of the guide.

For the rest, I think I prefer the current content to your proposal as this guide has a very precise purpose and is not a general Dev UI guide.


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.

Check warning on line 18 in docs/src/main/asciidoc/dev-ui.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using ', which (non restrictive clause preceded by a comma)' or 'that (restrictive clause without a comma)' rather than 'which'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using ', which (non restrictive clause preceded by a comma)' or 'that (restrictive clause without a comma)' rather than 'which'.", "location": {"path": "docs/src/main/asciidoc/dev-ui.adoc", "range": {"start": {"line": 18, "column": 34}}}, "severity": "INFO"}

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.

Check warning on line 20 in docs/src/main/asciidoc/dev-ui.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 'quarkus'?

Raw Output:
{"message": "[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'quarkus'?", "location": {"path": "docs/src/main/asciidoc/dev-ui.adoc", "range": {"start": {"line": 20, "column": 16}}}, "severity": "WARNING"}

Check warning on line 20 in docs/src/main/asciidoc/dev-ui.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 'ui'?

Raw Output:
{"message": "[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'ui'?", "location": {"path": "docs/src/main/asciidoc/dev-ui.adoc", "range": {"start": {"line": 20, "column": 55}}}, "severity": "WARNING"}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
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]_

Check warning on line 33 in docs/src/main/asciidoc/dev-ui.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 'ui'?

Raw Output:
{"message": "[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'ui'?", "location": {"path": "docs/src/main/asciidoc/dev-ui.adoc", "range": {"start": {"line": 33, "column": 37}}}, "severity": "WARNING"}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure what you're trying to say here? We already state previously that the Dev UI is available in dev mode.

Also this guide is for extension authors, not for general considerations about the Dev UI.


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:

Check warning on line 40 in docs/src/main/asciidoc/dev-ui.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.SentenceLength] Try to keep sentences to an average of 32 words or fewer.

Raw Output:
{"message": "[Quarkus.SentenceLength] Try to keep sentences to an average of 32 words or fewer.", "location": {"path": "docs/src/main/asciidoc/dev-ui.adoc", "range": {"start": {"line": 40, "column": 1}}}, "severity": "INFO"}

Check warning on line 40 in docs/src/main/asciidoc/dev-ui.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using '"click", "select", "browse", or "go to"' rather than 'navigate'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using '\"click\", \"select\", \"browse\", or \"go to\"' rather than 'navigate'.", "location": {"path": "docs/src/main/asciidoc/dev-ui.adoc", "range": {"start": {"line": 40, "column": 67}}}, "severity": "INFO"}

Check warning on line 40 in docs/src/main/asciidoc/dev-ui.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsWarnings] Consider using 'information about' rather than 'information on' unless updating existing content that uses the term.

Raw Output:
{"message": "[Quarkus.TermsWarnings] Consider using 'information about' rather than 'information on' unless updating existing content that uses the term.", "location": {"path": "docs/src/main/asciidoc/dev-ui.adoc", "range": {"start": {"line": 40, "column": 123}}}, "severity": "WARNING"}

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!

Check warning on line 50 in docs/src/main/asciidoc/dev-ui.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsWarnings] Consider using 'To' rather than 'In order to' unless updating existing content that uses the term.

Raw Output:
{"message": "[Quarkus.TermsWarnings] Consider using 'To' rather than 'In order to' unless updating existing content that uses the term.", "location": {"path": "docs/src/main/asciidoc/dev-ui.adoc", "range": {"start": {"line": 50, "column": 1}}}, "severity": "WARNING"}

Check warning on line 50 in docs/src/main/asciidoc/dev-ui.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Fluff] Depending on the context, consider using 'Be concise: use 'to' rather than' rather than 'In order to'.

Raw Output:
{"message": "[Quarkus.Fluff] Depending on the context, consider using 'Be concise: use 'to' rather than' rather than 'In order to'.", "location": {"path": "docs/src/main/asciidoc/dev-ui.adoc", "range": {"start": {"line": 50, "column": 1}}}, "severity": "INFO"}

So you can always start with that :)

Extensions can:

- <<add-links-to-an-extension-card,Add links to an extension card>>
- <<add-links-to-an-extension-card,Add links to an extension card>>
- <<add-full-pages,Add full custom pages>>
- <<add-a-log-file,Add a log stream>>
- <<add-a-section-menu,Add a section menu>>
Expand Down Expand Up @@ -98,7 +106,7 @@
[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 `<i class="fa-solid fa-house"></i>` 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 `<i class="fa-solid fa-house"></i>` will map to `font-awesome-solid:house`, so `fa` becomes `font-awesome` and for the icon name, remove the `fa-`;

==== Embedding external content

Expand All @@ -108,13 +116,13 @@

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 <<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")`.
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 <<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")`.

==== 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")`
Expand Down Expand Up @@ -146,7 +154,7 @@

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`:

- <<raw-data,Raw data>>
- <<raw-data,Raw data>>
- <<table-data,Table data>>
- <<qute-data,Qute data>>
- <<web-component-page,Web Component page>>
Expand Down Expand Up @@ -292,7 +300,7 @@
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`.
Expand All @@ -306,7 +314,7 @@

===== 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]:

Expand Down Expand Up @@ -375,7 +383,7 @@
resizable>
</vaadin-grid-column>
</vaadin-grid>`;

} else {
return html`No beans found`;
}
Expand Down Expand Up @@ -413,10 +421,10 @@
}else if(bean.kind.toLowerCase() === "synthetic"){
level = "contrast";
}

return html`
${level
? html`<qui-badge level='${level}' small><span>${kind}</span></qui-badge>`
? html`<qui-badge level='${level}' small><span>${kind}</span></qui-badge>`
: html`<qui-badge small><span>${kind}</span></qui-badge>`
}`;
}
Expand All @@ -435,7 +443,7 @@
return html`<vaadin-vertical-layout>
${bean.interceptorInfos.map(interceptor =>
html`<div>
<code>${interceptor.interceptorClass.name}</code>
<code>${interceptor.interceptorClass.name}</code>
<qui-badge class="${bean.kind.toLowerCase()}" small pill><span>${interceptor.priority}</span></qui-badge>
</div>`
)}
Expand Down Expand Up @@ -523,7 +531,7 @@
<qui-badge background="pink" color="purple" small><span>Custom colours</span></qui-badge>
</div>
</div>
</qui-card>
</qui-card>
<qui-card title="Primary">
<div slot="content">
<div class="cardcontents">
Expand All @@ -549,7 +557,7 @@
</div>
</qui-card>
<qui-card title="With icon">
<div slot="content">
<div slot="content">
<div class="cardcontents">
<qui-badge text="Default" icon="font-awesome-solid:circle-info">
<span>Default icon</span>
Expand Down Expand Up @@ -690,7 +698,7 @@
[source,html]
----
<div class="codeBlock">
<qui-code-block
<qui-code-block
mode='yaml'
content='${yaml}'>
</qui-code-block>
Expand All @@ -704,7 +712,7 @@
[source,html]
----
<div class="codeBlock">
<qui-code-block
<qui-code-block
mode='${this._mode}'
src='${this._externalUrl}'>
</qui-code-block>
Expand All @@ -724,7 +732,7 @@

[source,html]
----
<qui-ide-link title='Source full class name'
<qui-ide-link title='Source full class name'
class='text-source'
fileName='${sourceClassNameFull}'
lineNumber=${sourceLineNumber}>[${sourceClassNameFull}]</qui-ide-link>;
Expand Down Expand Up @@ -869,7 +877,7 @@

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
Expand Down Expand Up @@ -904,7 +912,7 @@

*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]
----
Expand Down Expand Up @@ -976,7 +984,7 @@
public class JokesJsonRPCService {

private final BroadcastProcessor<Joke> jokeStream = BroadcastProcessor.create();

@PostConstruct
void init() {
Multi.createFrom().ticks().every(Duration.ofHours(4)).subscribe().with((item) -> {
Expand Down Expand Up @@ -1008,7 +1016,7 @@

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]
Expand Down Expand Up @@ -1077,7 +1085,7 @@
extensionName: {type: String},
description: {type: String},
guide: {type: String},
namespace: {type: String}
namespace: {type: String}
}
----

Expand Down
Loading