# Dev UI

| Dev UI v1 This guide covers the Dev UI v1, which has been replaced in Quarkus 3 with a new Dev UI. You can still access the Dev UI v1 using /q/dev-v1

This guide covers the Quarkus Dev UI for extension authors.

Quarkus ships with a new experimental Dev UI, which is available in dev mode (when you start quarkus with `mvn quarkus:dev`) at /q/dev-v1 by default. It will show you something like this:

It allows you to quickly visualize all the extensions currently loaded, see their status and go directly to their documentation.

On top of that, each extension can add:

- Custom useful bits of runtime information in the overview

- Full custom pages

- Interactive pages with actions

## How can I make my extension support the Dev UI?

In order to make your extension listed in the Dev UI you don’t need to do anything!

So you can always start with that :)

If you want to contribute badges or links in your extension card on the Dev UI overview page, like this:

You have to add a file named `dev-templates/embedded.html` in your `deployment` extension module’s resources:

The contents of this file will be included in your extension card, so for example we can place two links with some styling and icons:

    <a href="{config:http-path('quarkus.smallrye-openapi.path')}" class="badge badge-light">
      <i class="fa fa-map-signs fa-fw"></i>
      OpenAPI</a>
    <br>
    <a href="{config:http-path('quarkus.swagger-ui.path')}/" class="badge badge-light">
      <i class="fa fa-map-signs fa-fw"></i>
      Swagger UI</a>

| We use the Font Awesome Free icon set.

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'.

The corresponding non-application endpoint is declared using `.routeConfigKey` to associate the route with a name:

        nonApplicationRootPathBuildItem.routeBuilder()
                .route(openApiConfig.path) (1)
                .routeConfigKey("quarkus.smallrye-openapi.path") (2)
                ...
                .build();

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

Paths are tricky business. Keep the following in mind:

- 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.

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.

The `{devRootAppend}` variable can also be used in templates to construct URLs for static dev console resources, for example:

    <img src="{devRootAppend}/resources/images/quarkus_icon_rgb_reverse.svg" width="40" height="30" class="d-inline-block align-middle" alt="Quarkus"/>

Refer to the Quarkus Vertx HTTP configuration reference for details on how the non-application root path is configured.

## Template and styling support

Both the `embedded.html` files and any full page you add in `/dev-templates` will be interpreted by the Qute template engine.

This also means that you can add custom Qute tags in `/dev-templates/tags` for your templates to use.

The style system currently in use is Bootstrap V4 (4.6.0) but note that this might change in the future.

The main template also includes jQuery 3.5.1, but here again this might change.

### Accessing Config Properties

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

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.

## Adding full pages

To add full pages for your Dev UI extension such as this one:

You need to place them in your extension’s `deployment` module’s `/dev-templates` resource folder, like this page for the `quarkus-cache` extension:

    {#include main}(1)
        {#style}(2)
            .custom {
                color: gray;
            }
        {/style}
        {#script} (3)
         $(document).ready(function(){
            $(function () {
              $('[data-toggle="tooltip"]').tooltip()
            });
        });
        {/script}
        {#title}Cache{/title}(4)
        {#body}(5)
            <table class="table table-striped custom">
                <thead class="thead-dark">
                    <tr>
                        <th scope="col">Name</th>
                        <th scope="col">Size</th>
                    </tr>
                </thead>
                <tbody>
                    {#for cacheInfo in info:cacheInfos}(6)
                        <tr>
                            <td>
                                {cacheInfo.name}
                            </td>
                            <td>
                                <form method="post"(7)
                                      enctype="application/x-www-form-urlencoded">
                                    <label class="form-check-label" for="clear">
                                        {cacheInfo.size}
                                    </label>
                                    <input type="hidden" name="name" value="{cacheInfo.name}">
                                    <input id="clear" type="submit"
                                           class="btn btn-primary btn-sm" value="Clear" >
                                </form>
                            </td>
                        </tr>
                    {/for}
                </tbody>
            </table>
        {/body}
    {/include}

1 | In order to benefit from the same style as other Dev UI pages, extend the `main` template
2 | You can pass extra CSS for your page in the `style` template parameter
3 | You can pass extra JavaScript for your page in the `script` template parameter. This will be added inline after the JQuery script, so you can safely use JQuery in your script.
4 | Don’t forget to set your page title in the `title` template parameter
5 | The `body` template parameter will contain your content
6 | In order for your template to read custom information from your Quarkus extension, you can use the `info` namespace.
7 | This shows an interactive page

## Linking to your full-page templates

Full-page templates for extensions live under a pre-defined `{devRootAppend}/{groupId}.{artifactId}/` directory that is referenced using the `urlbase` template parameter. Using configuration defaults, that would resolve to `/q/dev-v1/io.quarkus.quarkus-cache/`, as an example.

Use the `{urlbase}` template parameter to reference this folder in `embedded.html`:

    <a href="{urlbase}/caches" class="badge badge-light">(1)
      <i class="fa ..."></i>
      Caches <span class="badge badge-light">{info:cacheInfos.size()}</span></a>

1 | Use the `urlbase` template parameter to reference full-page templates for your extension

## Passing information to your templates

In `embedded.html` or in full-page templates, you will likely want to display information that is available from your extension.

There are two ways to make that information available, depending on whether it is available at build time or at run time.

In both cases we advise that you add support for the Dev UI in your `{pkg}.deployment.devconsole` package in a `DevConsoleProcessor` class (in your extension’s `deployment` module).

### Passing run-time information

    package io.quarkus.cache.deployment.devconsole;

    import io.quarkus.cache.runtime.CaffeineCacheSupplier;
    import io.quarkus.deployment.IsDevelopment;
    import io.quarkus.deployment.annotations.BuildStep;
    import io.quarkus.devconsole.spi.DevConsoleRuntimeTemplateInfoBuildItem;

    public class DevConsoleProcessor {

        @BuildStep(onlyIf = IsDevelopment.class)(1)
        public DevConsoleRuntimeTemplateInfoBuildItem collectBeanInfo() {
            return new DevConsoleRuntimeTemplateInfoBuildItem("cacheInfos",
                          new CaffeineCacheSupplier());(2)
        }
    }

1 | Don’t forget to make this build step conditional on being in dev mode
2 | Declare a run-time dev `info:cacheInfos` template value

This will map the `info:cacheInfos` value to this supplier in your extension’s `runtime module`:

    package io.quarkus.cache.runtime;

    import java.util.ArrayList;
    import java.util.Collection;
    import java.util.Comparator;
    import java.util.List;
    import java.util.function.Supplier;

    import io.quarkus.arc.Arc;
    import io.quarkus.cache.CaffeineCache;

    public class CaffeineCacheSupplier implements Supplier<Collection<CaffeineCache>> {

        @Override
        public List<CaffeineCache> get() {
            List<CaffeineCache> allCaches = new ArrayList<>(allCaches());
            allCaches.sort(Comparator.comparing(CaffeineCache::getName));
            return allCaches;
        }

        public static Collection<CaffeineCache> allCaches() {
            // Get it from ArC at run-time
            return (Collection<CaffeineCache>) (Collection)
                Arc.container().instance(CacheManagerImpl.class).get().getAllCaches();
        }
    }

### Passing build-time information

Sometimes you only need build-time information to be passed to your template, so you can do it like this:

    package io.quarkus.qute.deployment.devconsole;

    import java.util.List;

    import io.quarkus.deployment.IsDevelopment;
    import io.quarkus.deployment.annotations.BuildStep;
    import io.quarkus.devconsole.spi.DevConsoleTemplateInfoBuildItem;
    import io.quarkus.qute.deployment.CheckedTemplateBuildItem;
    import io.quarkus.qute.deployment.TemplateVariantsBuildItem;

    public class DevConsoleProcessor {

        @BuildStep(onlyIf = IsDevelopment.class)
        public DevConsoleTemplateInfoBuildItem collectBeanInfo(
                List<CheckedTemplateBuildItem> checkedTemplates,(1)
                TemplateVariantsBuildItem variants) {
            DevQuteInfos quteInfos = new DevQuteInfos();
            for (CheckedTemplateBuildItem checkedTemplate : checkedTemplates) {
                DevQuteTemplateInfo templateInfo =
                    new DevQuteTemplateInfo(checkedTemplate.templateId,
                        variants.getVariants().get(checkedTemplate.templateId),
                        checkedTemplate.bindings);
                quteInfos.addQuteTemplateInfo(templateInfo);
            }
            return new DevConsoleTemplateInfoBuildItem("devQuteInfos", quteInfos);(2)
        }

    }

1 | Use whatever dependencies you need as input
2 | Declare a build-time `info:devQuteInfos` DEV template value

## Advanced usage: adding actions

You can also add actions to your Dev UI templates:

This can be done by adding another build step to declare the action in your extension’s `deployment` module:

    package io.quarkus.cache.deployment.devconsole;

    import static io.quarkus.deployment.annotations.ExecutionTime.STATIC_INIT;

    import io.quarkus.cache.runtime.devconsole.CacheDevConsoleRecorder;
    import io.quarkus.deployment.annotations.BuildStep;
    import io.quarkus.deployment.annotations.Record;
    import io.quarkus.devconsole.spi.DevConsoleRouteBuildItem;

    public class DevConsoleProcessor {

        @BuildStep
        @Record(value = STATIC_INIT, optional = true)(1)
        DevConsoleRouteBuildItem invokeEndpoint(CacheDevConsoleRecorder recorder) {
            return new DevConsoleRouteBuildItem("caches", "POST",
                                                recorder.clearCacheHandler());(2)
        }
    }

1 | Mark the recorder as optional, so it will only be invoked when in dev mode
2 | Declare a `POST {urlbase}/caches` route handled by the given handler

Note: you can see how to invoke this action from your full page.

Now all you have to do is implement the recorder in your extension’s `runtime module`:

    package io.quarkus.cache.runtime.devconsole;

    import io.quarkus.cache.CaffeineCache;
    import io.quarkus.cache.runtime.CaffeineCacheSupplier;
    import io.quarkus.runtime.annotations.Recorder;
    import io.quarkus.devconsole.runtime.spi.DevConsolePostHandler;
    import io.quarkus.vertx.http.runtime.devmode.devconsole.FlashScopeUtil.FlashMessageStatus;
    import io.vertx.core.Handler;
    import io.vertx.core.MultiMap;
    import io.vertx.ext.web.RoutingContext;

    @Recorder
    public class CacheDevConsoleRecorder {

        public Handler<RoutingContext> clearCacheHandler() {
            return new DevConsolePostHandler() {(1)
                @Override
                protected void handlePost(RoutingContext event, MultiMap form) (2)
                  throws Exception {
                    String cacheName = form.get("name");
                    for (CaffeineCache cache : CaffeineCacheSupplier.allCaches()) {
                        if (cache.getName().equals(cacheName)) {
                            cache.invalidateAll();
                            flashMessage(event, "Cache for " + cacheName + " cleared");(3)
                            return;
                        }
                    }
                    flashMessage(event, "Cache for " + cacheName + " not found",
                                 FlashMessageStatus.ERROR);(4)
                }
            };
        }
    }

1 | While you can use any Vert.x handler, the `DevConsolePostHandler` superclass will handle your POST actions nicely, and auto-redirect to the `GET` URI right after your `POST` for optimal behavior.
2 | You can get the Vert.x `RoutingContext` as well as the `form` contents
3 | Don’t forget to add a message for the user to let them know everything went fine
4 | You can also add error messages

| Flash messages are handled by the `main` DEV template and will result in nice notifications for your users: