Add documentation for qute support

Fixes #427 Signed-off-by: azerr <azerr@redhat.com>
redhat-developer · Jan 11, 2022 · ca94e69 · ca94e69
1 parent 562ffb4
commit ca94e69
Show file tree

Hide file tree

Showing 19 changed files with 131 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -5,11 +5,17 @@
 
 ## Description
 
-This Visual Studio Code extension provides support for [Quarkus](https://quarkus.io/) and [MicroProfile](https://github.com/eclipse/microprofile) development
+This Visual Studio Code extension provides support for :
+
+ * [Quarkus](https://quarkus.io/) and [MicroProfile](https://github.com/eclipse/microprofile) development
 by extending [Visual Studio Code extension for MicroProfile](https://github.com/redhat-developer/vscode-microprofile) with Quarkus features.
 
 ![](images/propertiesSupport.png)
 
+ * [Qute support](docs/qute/README.md) to provide completion, validation, etc. for the [Qute template engine](https://quarkus.io/guides/qute-reference) inside Java and template files.
+
+![](images/quteSupport.png)
+
 ## Quarkus VS Code Commands
 The following commands are supported for both Maven and Gradle Quarkus projects:
 
@@ -75,11 +81,10 @@ The following settings are supported:
 * `quarkus.tools.alwaysShowWelcomePage` : Determines whether to show the welcome page on extension startup. Default is `true`.
 * `quarkus.tools.starter.api` : Quarkus API base URL. Default is `https://code.quarkus.io/api`.
 * `quarkus.tools.starter.showExtensionDescriptions`: Determines whether to show the Quarkus extension descriptions when selecting Quarkus extensions. Default is `true`.
-* `qute.trace.server`: Trace the communication between VS Code and the Qute language server in the Output view. Default is `off`.
-
-Since 1.6.0:
 * `quarkus.tools.propertiesLanguageMismatch` : Action performed when detected Quarkus properties have an incorrect language. Default is `forceQuarkus`.
 
+For `Qute settings`, please see [here](docs/qute/README.md#settings)
+
 ## Telemetry
 
 With your approval, vscode-quarkus extension collects anonymous [usage data](USAGE_DATA.md) and sends it to Red Hat servers to help improve our products and services.

diff --git a/docs/qute/JavaSupport.md b/docs/qute/JavaSupport.md
@@ -0,0 +1,5 @@
+# Qute Java support
+
+Qute support provides `validation`, `documentation link`, `codelens` inside Java files, to manage binding with Qute templates:
+
+![Qute Java support](images/QuteJava.gif)
diff --git a/docs/qute/README.md b/docs/qute/README.md
@@ -0,0 +1,12 @@
+# Qute support
+
+[Qute](https://quarkus.io/guides/qute-reference) is a template engine used in Quarkus applications.
+
+[vscode-quarkus](https://github.com/redhat-developer/vscode-quarkus) provides `Qute` support in:
+
+ * [templates files](TemplateSupport.md#template) : completion, validation etc. for Qute template.
+ * [Java files](JavaSupport.md#java-file) : completion, validation etc. for Qute integration within Quarkus applications.
+
+ ## Settings
+
+ * `qute.trace.server`: Trace the communication between VS Code and the Qute language server in the Output view. Default is `off`.
diff --git a/docs/qute/TemplateSupport.md b/docs/qute/TemplateSupport.md
@@ -0,0 +1,105 @@
+# Qute Template support
+
+Qute support provides `completions`, `validation`, `hover`, `definition`, `highlight`, `linked editing` in Qute template.
+
+To benefit with this support, we recommend your template files to follow the `*.qute.*` naming pattern (ex: `items.qute.html`, `items.qute.txt`, `items.qute.yaml`, etc.).
+
+## Parameter declaration support
+
+A `parameter declaration` is used to declare the expected model in a Qute template:
+
+```
+{@java.util.List<org.acme.qute.Item> items}
+```
+
+The Qute support helps to easily write this declaration with the completion, hover and definition support.
+
+### Completion for Java types
+
+The Qute support provides completion to easily write parameter declaration:
+
+![Completion for Java types](images/QuteTemplateParameterDeclarationCompletion.gif)
+
+### Validate Java type
+
+The Qute support validates Java types:
+
+![Validate Java type](images/QuteTemplateParameterDeclarationValidation.png)
+
+### Jump to Java type definition
+
+You can jump to the proper Java type:
+
+![Jump to Java type definition](images/QuteTemplateParameterDeclarationDefinition.gif)
+
+## Section support
+
+### Completion for Qute section
+
+Qute support provides snippets to quickly generate `Qute` sections. Here is a sample for the `#for` section:
+
+![Completion for Qute section](images/QuteTemplateSectionSnippetCompletion.gif)
+
+### Linked editing
+
+Linked editing is supported, allowing for simultaneous renaming of a parameter expression.
+
+To enable this feature, the setting `editor.linkedEditing` must be set to `true` in your `settings.json`.
+
+![Linked EditingRange](images/QuteTemplateLinkedEditingRange.gif)
+
+## Tag Name Highlighting
+
+When placing the cursor on a Qute section tag, the corresponding opening/closing tag will be highlighted with their nested block:
+
+![Highlight Corresponding Tag](images/QuteTemplateSectionHighlighting.gif)
+
+## Expression support
+
+A Qute expression is declared inside `{|}` or inside a section (ex : `{#for item in |}`).
+
+### Completion for Java data model
+
+Completion is available for allowed Java `fields`, `methods` and `virtual methods` (coming from the Qute core like `orEmpty` or coming from @TemplateExtension):
+
+![Completion for Java data model](images/QuteTemplateCompletionForJavaDataModel.gif)
+
+### Validation for Java data model
+
+Validation highlights unknown Java fields or methods as an error:
+
+![Validation for Java data model](images/QuteTemplateValidationForJavaDataModel.png)
+
+### Hover for Java data model
+
+When you hover over an object, property or method or virtual method (for `@TemplateExtension`), you can see the Java type:
+
+![Hover for Java data model](images/QuteTemplateHoverForJavaDataModel.gif)
+
+When you hover over a [Built-in Resolvers](https://quarkus.io/guides/qute-reference#built-in-resolvers) you can see the relevant documentation, with a link to the [Qute reference guide](https://quarkus.io/guides/qute-reference):
+
+![Hover for Built-in Resolvers](images/QuteTemplateHoverForBuildInResolver.png)
+
+### Jump to Java field, method definition
+
+`Ctrl+Click` on a property or method to jump to the definition of the matching Java field, method or virtual method (for `@TemplateExtension`):
+
+![Definition for Java data model](images/QuteTemplateDefinitionForJavaDataModel.gif)
+
+### Jump to the declared object
+
+A variable can be declared inside a Qute template (with parameter declaration, or #let section) or declared from the Java side.
+
+`Ctrl+Click` on an object part jumps to the declared object in the Qute template (with parameter declaration, or #let section) or to the Java code (method parameter or data method invocation):
+
+![Definition for Java data model](images/QuteTemplateDefinitionForObject.gif)
+
+## Quarkus integration for Qute
+
+When the template is used in a Quarkus application and it is bound with a Java Template field or a method annotated with `@CheckedTemplate`, you can see the expected model as CodeLens:
+
+![CodeLens for Java data model](images/QuteTemplateCodeLensJavaDataModel.png)
+
+In this case, you don't need to declare parameter declaration to benefit from Qute completion, validation, etc. of the Java data model.
+
+CodeLens are clickable to jump to the proper Java type, method or field.
diff --git a/docs/qute/images/QuteJava.gif b/docs/qute/images/QuteJava.gif
diff --git a/docs/qute/images/QuteTemplateCodeLensJavaDataModel.png b/docs/qute/images/QuteTemplateCodeLensJavaDataModel.png
diff --git a/docs/qute/images/QuteTemplateCompletionForJavaDataModel.gif b/docs/qute/images/QuteTemplateCompletionForJavaDataModel.gif
diff --git a/docs/qute/images/QuteTemplateDefinitionForJavaDataModel.gif b/docs/qute/images/QuteTemplateDefinitionForJavaDataModel.gif
diff --git a/docs/qute/images/QuteTemplateDefinitionForObject.gif b/docs/qute/images/QuteTemplateDefinitionForObject.gif
diff --git a/docs/qute/images/QuteTemplateHoverForBuildInResolver.png b/docs/qute/images/QuteTemplateHoverForBuildInResolver.png
diff --git a/docs/qute/images/QuteTemplateHoverForJavaDataModel.gif b/docs/qute/images/QuteTemplateHoverForJavaDataModel.gif
diff --git a/docs/qute/images/QuteTemplateLinkedEditingRange.gif b/docs/qute/images/QuteTemplateLinkedEditingRange.gif
diff --git a/docs/qute/images/QuteTemplateParameterDeclarationCompletion.gif b/docs/qute/images/QuteTemplateParameterDeclarationCompletion.gif
diff --git a/docs/qute/images/QuteTemplateParameterDeclarationDefinition.gif b/docs/qute/images/QuteTemplateParameterDeclarationDefinition.gif
diff --git a/docs/qute/images/QuteTemplateParameterDeclarationValidation.png b/docs/qute/images/QuteTemplateParameterDeclarationValidation.png
diff --git a/docs/qute/images/QuteTemplateSectionHighlighting.gif b/docs/qute/images/QuteTemplateSectionHighlighting.gif
diff --git a/docs/qute/images/QuteTemplateSectionSnippetCompletion.gif b/docs/qute/images/QuteTemplateSectionSnippetCompletion.gif
diff --git a/docs/qute/images/QuteTemplateValidationForJavaDataModel.png b/docs/qute/images/QuteTemplateValidationForJavaDataModel.png
diff --git a/images/quteSupport.png b/images/quteSupport.png