hxuanyu/intellij-sdk-code-samples
1
0
Fork 0
mirror of https://github.com/JetBrains/intellij-sdk-code-samples.git synced 2025-07-27 16:57:49 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add live templates configuration file documentation

Browse Source
This commit is contained in:
Karol Lewandowski 2024-12-20 20:17:54 +01:00
parent 35a4c71f96
commit c9839de1c0
5 changed files with 256 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
.github/scripts/generate_descriptor_pages.main.kts vendored
View File

@ -3,8 +3,7 @@
// Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license.
/**
* Generates the elements content for the plugin_configuration_file.md page.
* It fetches the elements data from <TODO>.
* Generates the elements content for pages defined in [descriptors].
*/
@file:DependsOn("org.yaml:snakeyaml:2.3")
@ -44,7 +43,8 @@ val renderedPageNameToTopicNames = mutableMapOf<String, String>().apply {
val renderedElementPaths = mutableListOf<String>()
val descriptors = listOf(
DescriptorInfo("https://jb.gg/sdk-docs/plugin-descriptor.yaml", "topics/basics/plugin_structure/plugin_configuration_file.md")
DescriptorInfo("https://jb.gg/sdk-docs/plugin-descriptor.yaml", "topics/basics/plugin_structure/plugin_configuration_file.md"),
DescriptorInfo("https://jb.gg/sdk-docs/templates-descriptor.yaml", "topics/tutorials/live_templates/live_templates_configuration_file.md")
)
descriptors.forEach { descriptor ->

4
ijs.tree
View File

@ -195,7 +195,9 @@
<toc-element topic="advanced_postfix_templates.md"/>
</toc-element>
<toc-element topic="live_templates.md">
<toc-element topic="providing_live_templates.md" accepts-web-file-names="template-support.html"/>
<toc-element topic="providing_live_templates.md" accepts-web-file-names="template-support.html">
<toc-element topic="live_templates_configuration_file.md"/>
</toc-element>
<toc-element topic="creating_live_template_functions.md" accepts-web-file-names="new-macros.html"/>
</toc-element>
<toc-element topic="file_and_code_templates.md" accepts-web-file-names="templates.html">

5
topics/tutorials/live_templates.md
View File

@ -54,5 +54,6 @@ public void testMethod() {
For more information about creating Custom Live Templates, refer to the [corresponding documentation](https://www.jetbrains.com/idea/help/creating-and-editing-live-templates.html).
These sections describe how to add Live Templates, and their associated building blocks, to plugins.
* [Providing Live Templates](providing_live_templates.md)
* [Creating New Functions for Live Templates](creating_live_template_functions.md)
* [](providing_live_templates.md)
* [](live_templates_configuration_file.md)
* [](creating_live_template_functions.md)

243
topics/tutorials/live_templates/live_templates_configuration_file.md Normal file
View File

@ -0,0 +1,243 @@
<!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
# Live Templates Configuration File
<show-structure for="chapter" depth="4"/>
<link-summary>Live templates configuration file contains all the information about templates provided by the plugin.</link-summary>
This page lists and describes all the elements and attributes used in live templates configuration files.
## Configuration Structure Overview
[//]: # (GENERATED CONTENT START)
[//]: # (This content is generated by generate_descriptor_pages.main.kts script.)
[//]: # (DO NOT EDIT IT MANUALLY)
- [`<templateSet>`](#templateSet)
- [`<template>`](#templateSet__template)
- [`<variable>`](#templateSet__template__variable)
- [`<context>`](#templateSet__template__context)
- [`<option>`](#templateSet__template__context__option)
## `templateSet`
{#templateSet}
<tldr>
**Reference:** [Live Templates](live_templates.md)
, [Live Templates (IntelliJ IDEA Web Help)](https://www.jetbrains.com/help/idea/settings-live-templates.html)
</tldr>
The live templates file root element.
{style="narrow"}
Required
: **yes**
Attributes
:
- `group` _(optional)_<br/>
Name of the template set group, which is displayed in <ui-path>Settings | Editor | Live Templates</ui-path> list.
If the group name is not provided, then templates' XML file name is used by default.
- `replace` _(optional)_<br/>
Name of a template group that this template set replaces.
Templates from the replaced group are removed and are skipped in settings and completion.
Children
:
- [`<template>`](#templateSet__template)
### `template`
{#templateSet__template}
Describes a template.
{style="narrow"}
Required
: no
Attributes
:
- `id` _(optional)_<br/>
Optional template identifier.
- `name` _(**required**)_<br/>
The template abbreviation typed by users in the editor to expand it.
The abbreviation must be unique in the group containing the template.
- `value` _(**required**)_<br/>
The text that the template is expanded to.<br/>
It may contain plain text and reference [variables](#templateSet__template__variable) in the format `$VARIABLE_NAME$`.
To escape a dollar sign `$` in the template text, use `$$`.
- `resource-bundle` _(optional)_<br/>
Message bundle containing the template description specified by `key`.
- `key` _(optional)_<br/>
The key of the template description provided in a message bundle defined by `resource-bundle`.
Description is used in the UI.
Overrides the value of `description`.
- `description` _(optional)_<br/>
The template description used in the UI.
It is ignored if the description is provided with `resource-bundle` and `key`.
- `shortcut` _(optional)_<br/>
Defines a character that expands the template.
Allowed values:
- `SPACE` - space key
- `TAB` - tab key
- `ENTER` - enter key
- `CUSTOM` - key defined in the <control>By default expand with</control> field in <ui-path>Settings | Editor | Live Templates</ui-path>
- `NONE` - disables expanding with a key
- `toReformat` _(optional)_<br/>
Defines whether the inserted code should be reformatted according to the language code style.<br/>
Default value: `false`.
- `toShortenFQNames` _(optional)_<br/>
Defines whether qualified names in the expanded code should be shortened,
for example, fully qualified names of Java classes are imported.<br/>
Shortening qualified names is performed in implementations of [`TemplateOptionalProcessor`](%gh-ic%/platform/analysis-impl/src/com/intellij/codeInsight/template/impl/TemplateOptionalProcessor.java).<br/>
Default value: `false`.
- `useStaticImport` _(optional)_<br/>
Defines whether symbols used in the expanded code should be statically imported, if possible.<br/>
Importing symbols statically is performed in implementations of [`TemplateOptionalProcessor`](%gh-ic%/platform/analysis-impl/src/com/intellij/codeInsight/template/impl/TemplateOptionalProcessor.java).<br/>
Default value: `false`.
- `deactivated` _(optional)_<br/>
Allows deactivating the template.
Deactivated templates are listed in the UI and can be activated by users.<br/>
Default value: `false`.
Children
:
- [`<context>`](#templateSet__template__context)
- [`<variable>`](#templateSet__template__variable)
#### `variable`
{#templateSet__template__variable}
<tldr>
**Reference:** [Template Variables](https://www.jetbrains.com/help/idea/edit-template-variables-dialog.html)
</tldr>
Defines a variable to be used in the template `value`.
A single template can provide multiple variables.
The order of the variables determines the order in which the IDE will switch between
the corresponding input fields when the template is expanded.
{style="narrow"}
Required
: no
Attributes
:
- `name` _(optional)_<br/>
The variable name that is referenced in the [`<template>`](#templateSet__template) element's `value` attribute.
- `expression` _(optional)_<br/>
Expression to calculate the value of the corresponding template input field automatically.<br/>
The expression may contain the following constructs:
- string constants in escaped double quotes, for example, `&quot;value&quot;`
- names of other variables defined in the template, for example, `ANOTHER_VAR`
- functions ([built-in](https://www.jetbrains.com/help/idea/template-variables.html#predefined_functions) or [custom](creating_live_template_functions.md)) with possible arguments
- `defaultValue` _(optional)_<br/>
The default value for the corresponding input field of the expanded template
if the expression does not give any result after calculation.<br/>
It can refer to other live template variables, for example, `ANOTHER_VAR`.<br/>
To define the default value as a literal, enclose it in escaped quotation marks, for example, `&quot;value&quot;`.
- `alwaysStopAt` _(optional)_<br/>
If `true`, the IDE will always stop at the corresponding input of the expanded template.<br/>
If `false`, the IDE will skip the corresponding input of the expanded template if the input value is defined.<br/>
Default value: `false`.
Examples
:
- Empty variable allowing to provide a value manually by a user:
```xml
<variable
name="MY_VAR"
expression=""
defaultValue=""
alwaysStopAt="true"/>
```
- Variable inserting the content of the clipboard,
and referencing the `PLACEHOLDER` variable if the clipboard content is empty:
```xml
<variable
name="PLACEHOLDER"
expression=""
defaultValue=""
alwaysStopAt="true"/>
<variable
name="MY_VAR"
expression="clipboard()"
defaultValue="PLACEHOLDER"
alwaysStopAt="true"/>
```
- Variable invoking completion and providing the `myValue` value if the completion doesn't provide any result:
```xml
<variable
name="MY_VAR"
expression="complete()"
defaultValue="&quot;myValue&quot;"
alwaysStopAt="true"/>
```
#### `context`
{#templateSet__template__context}
Defines a mapping of a context type (for example, a Java method, a Markdown file) to applicability of the template
in this context type.
{style="narrow"}
Required
: no
Children
:
- [`<option>`](#templateSet__template__context__option)
Example
:
```xml
<context>
<option name="JAVA_CODE" value="true"/>
<option name="JAVA_COMMENT" value="false"/>
<option name="JAVA_STRING" value="false"/>
</context>
```
##### `option`
{#templateSet__template__context__option}
An entry specifying whether a given context type defined by the
`name` attribute is applicable for the template.
{style="narrow"}
Required
: no
Attributes
:
- `name` _(**required**)_<br/>
The context type name.<br/>
To implement a custom context type, see the
[context type implementation](providing_live_templates.md#implement-templatecontexttype)
tutorial.
- `value` _(**required**)_<br/>
A boolean value determining whether the context type defined with the
[`<option>`](#templateSet__template__context__option) element's
`name`
attribute is applicable for the template.<br/>
As context types are hierarchical, the `false` value can be used when the parent context type is applicable,
and it is required to disable the applicability of more specific child context types.
[//]: # (GENERATED CONTENT END)
<include from="snippets.md" element-id="missingContent"/>

4
topics/tutorials/live_templates/providing_live_templates.md
View File

@ -35,6 +35,10 @@ There are many [predefined functions](https://www.jetbrains.com/help/idea/templa
Once the Live Template produces the expected result, [export the Live Template](https://www.jetbrains.com/help/idea/sharing-live-templates.html).
The export produces a file called <path>Markdown.xml</path> with the following contents:
> See [](live_templates_configuration_file.md) for a detailed description of the templates XML file structure and elements.
>
{style="note"}
```xml
<templateSet group="Markdown">
<template