Add title case macro docs IJSDK-698

This commit is contained in:
JohnHake 2020-03-17 18:38:07 -07:00
parent a1ca07f066
commit 48d7203567
12 changed files with 118 additions and 26 deletions

View File

@ -141,13 +141,14 @@
## Part V - Features
* Navigation
* Go To Symbol
* Editing
* [Editing](basics/editing.md)
* Code Completion
* Templates
* [Templates](basics/templates.md)
* [Live Templates](tutorials/live_templates.md)
* [1. Adding Live Template Support](tutorials/live_templates/template_support.md)
* [Adding Live Templates to a Plugin](tutorials/live_templates/template_support.md)
* [Creating New Functions for Live Templates](tutorials/live_templates/new_macros.md)
* Surround Templates
* File Templates
* Surround Templates
* QuickDoc
* [Intentions](tutorials/code_intentions.md)
* Analysing

9
basics/editing.md Normal file
View File

@ -0,0 +1,9 @@
---
title: Editing
---
<!-- Copyright 2000-2020 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
* Code Completion
* [Templates](/basics/templates.md)
* QuickDoc
* [Intentions](/tutorials/code_intentions.md)

10
basics/templates.md Normal file
View File

@ -0,0 +1,10 @@
---
title: Templates
---
<!-- Copyright 2000-2020 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
* [Live Templates](/tutorials/live_templates.md)
* [Adding Live Templates to a Plugin](/tutorials/live_templates/template_support.md)
* [Creating New Functions for Live Templates](/tutorials/live_templates/new_macros.md)
* Surround Templates
* File Templates

View File

@ -16,12 +16,9 @@ repositories {
// See https://github.com/JetBrains/gradle-intellij-plugin/
intellij {
version 'LATEST-EAP-SNAPSHOT'
// Sets <idea-version> in plugin.xml
version '201-EAP-SNAPSHOT'
sameSinceUntilBuild = true
}
patchPluginXml {
// Sets <version> in plugin.xml
version = project.version
}

View File

@ -8,7 +8,6 @@ import com.intellij.openapi.util.text.StringUtil;
import org.jetbrains.annotations.NotNull;
public class TitleCaseMacro extends MacroBase {
public TitleCaseMacro() {
super("titleCase", "titleCase(String)");
}
@ -22,9 +21,11 @@ public class TitleCaseMacro extends MacroBase {
@Override
protected Result calculateResult(@NotNull Expression[] params, ExpressionContext context, boolean quick) {
// Retrieve the text from the macro or selection, if any is available.
String text = getTextResult(params, context, true);
if (text != null) {
if (text.length() > 0) {
// Capitalize the start of every word
text = StringUtil.toTitleCase(text);
}
return new TextResult(text);

View File

@ -2,15 +2,12 @@
<idea-plugin>
<!-- Unique id for this plugin. Must stay constant for the life of the plugin. -->
<id>org.intellij.sdk.liveTemplates</id>
<!-- Text to display as name on Preferences/Settings | Plugin page -->
<name>SDK: Live Templates Sample Project</name>
<!-- The <version> of this plugin is set by patchPluginXml.version in build.gradle -->
<!-- The <idea-version> compatibility of this plugin is set by intellij.sameSinceUntilBuild in build.gradle -->
<!-- Product and plugin compatibility requirements -->
<depends>com.intellij.modules.lang</depends>
@ -34,11 +31,8 @@
<vendor url="https://plugins.jetbrains.com">IntelliJ Platform SDK</vendor>
<extensions defaultExtensionNs="com.intellij">
<!-- Declare where the IntelliJ Platform should look to find XML-based Live Templates -->
<defaultLiveTemplates file="/liveTemplates/Markdown"/>
<!-- Declare the implementation for determining the context for applying Live Templates -->
<defaultLiveTemplates file="/liveTemplates/Markdown.xml"/>
<liveTemplateContext implementation="org.intellij.sdk.liveTemplates.MarkdownContext"/>
<!-- Declare implementation-based Live Template -->
<liveTemplateMacro implementation="org.intellij.sdk.liveTemplates.TitleCaseMacro"/>
</extensions>

View File

@ -15,7 +15,7 @@
description="SDK: Convert to title case"
toReformat="true"
toShortenFQNames="false">
<variable name="TITLE" expression="titleCase(SELECTION)" defaultValue="the quick brown fox jumped over the lazy dog" alwaysStopAt="true" />
<variable name="TITLE" expression="titleCase(SELECTION)" defaultValue="the quick brown fox" alwaysStopAt="true" />
<context>
<option name="MARKDOWN" value="true" />
</context>

View File

@ -3,14 +3,21 @@ title: Live Templates
---
<!-- Copyright 2000-2020 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
*Live templates* are customizable rules that allow developers to abbreviate repetitive patterns of text in the editor. When a user types the designated abbreviation followed by a configurable *expansion key* (usually `Tab`), the IDE will transform the preceding input sequence to its full-length output, and update the cursor position. For example, consider a `for` loop. Typically, the end user would need to type `for(int i = 0; i < 10; i++) {<Enter><Tab><Enter><Enter>}<Up>`. This pattern may be shortened to `fori<Tab>` and the remaining contents will be expanded, leaving the following structure:
*Live Templates* are customizable rules that allow developers to abbreviate repetitive patterns of text in the editor.
When a user types the designated abbreviation followed by a configurable *expansion key* (usually `Tab`), the IDE transforms the preceding input sequence to its full-length output, and update the cursor position.
For example, consider a `for` loop. Typically, the end user would need to type `for(int i = 0; i < 10; i++) {<Enter><Tab><Enter><Enter>}<Up>`.
This pattern may be shortened to `fori<Tab>` and the remaining contents will be expanded, leaving the following structure:
```
for(int i = [|]; i < []; i++) {
[]
}
```
As the user completes each section of the `for` loop and presses `Tab`, the cursor will advance to the next position in the editor. For more information about creating your own Custom Live Templates, you may refer to the [corresponding documentation](https://www.jetbrains.com/idea/help/creating-and-editing-live-templates.html). In this tutorial, we will illustrate how to add default Custom Live Templates to an IntelliJ Platform plugin, and assign valid contexts where these templates can take on added functionality based on the surrounding code and file type. We will discuss how to export existing live templates, and bundle them within a plugin to give users added typing efficiency when using a custom language.
* [1. Create a new Live Template](live_templates/template_support.md)
As the user completes each section of the `for` loop and presses `Tab`, the cursor advances to the next position in the editor.
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.
* [Adding Live Templates to a Plugin](live_templates/template_support.md)
* [Creating New Functions for Live Templates](live_templates/new_macros.md)
* Surround Templates

Binary file not shown.

After

Width:  |  Height:  |  Size: 114 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 164 KiB

View File

@ -0,0 +1,70 @@
---
title: Creating New Functions for Live Templates
---
<!-- Copyright 2000-2020 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
The [Predefined Functions](https://www.jetbrains.com/help/idea/template-variables.html?s=quick#predefined_functions) are the building blocks for creating [Parameterized Templates and Surround Templates](https://www.jetbrains.com/help/idea/using-live-templates.html?s=quick#live_templates_types).
However, sometimes the Predefined Functions are not enough.
This tutorial illustrates how to add custom functions to an IntelliJ Platform plugin and make them available for use by Live Templates.
As an example, a function is created to convert a selection to Title Case.
Refer to the SDK code sample [`live_templates`](https://github.com/JetBrains/intellij-sdk-docs/tree/master/code_samples/live_templates).
* bullet
{:toc}
## Implementing a New Function
Under the hood, the predefined functions for Live Templates are called _macros_.
A new custom function for Live Templates is implemented in `TitleCaseMacro`, which extends [`MacroBase`](upsource:///platform/lang-impl/src/com/intellij/codeInsight/template/macro/MacroBase.java).
Three `TitleCaseMacro` methods are of particular interest:
* The `TitleCaseMacro()` constructor passes the name and description of the macro to the parent constructor.
* The `isAcceptableInContext()` method tests whether the macro is available in the current context.
The test relies on the [`MarkdownContext`](template_support.md#implement-templatecontexttype) object previously defined in the `live_templates` plugin.
* The `calculateResult()` method gets invoked when the titleCase function is used in a Live Template.
The text to be capitalized is retrieved from the Live Template and converted to Title Case.
```java
{% include /code_samples/live_templates/src/main/java/org/intellij/sdk/liveTemplates/TitleCaseMacro.java%}
```
## Adding a Live Template
Using the procedures previously discussed for [Template Creation](template_support.md#template-creation) and [Export the Live Template](template_support.md#export-the-live-template), add a Live Template to the [Markdown.xml](https://github.com/JetBrains/intellij-sdk-docs/tree/master/code_samples/live_templates/src/main/resources/liveTemplates) file for the plugin.
The XML representation of an example Live Template using the new `titleCase` function is listed below.
There is only one variable, `TITLE`.
The expression for `TITLE` evaluates to the `titleCase` function provided by the plugin.
The argument to the `titleCase` function is `SELECTION`, which tells the IntelliJ Platform to operate on the current selection.
```xml
<template name="mc"
value="$TITLE$"
description="SDK: Convert to title case"
toReformat="true"
toShortenFQNames="false">
<variable name="TITLE" expression="titleCase(SELECTION)" defaultValue="the quick brown fox" alwaysStopAt="true" />
<context>
<option name="MARKDOWN" value="true" />
</context>
</template>
```
## Register Extension Point
Using the `com.intellij.liveTemplateMacro` extension point, register the implementation with the IntelliJ Platform.
```xml
<extensions defaultExtensionNs="com.intellij">
<liveTemplateMacro implementation="org.intellij.sdk.liveTemplates.TitleCaseMacro"/>
</extensions>
```
## Check Plugin
Now verify the plugin is working correctly.
* Run the plugin in a Development Instance.
* Create a new file `testing.md` and enter several words in lower case.
* Highlight the text and enter <kbd>⌥⌘J</kbd> to open the Select Template popup.
Confirm that the _SDK: Convert to title case_ is available in the popup, and select it.
![Convert to title case](img/invoke_titleCase.png){:width="700px"}
Test that the Live Template works by entering <kbd>m</kbd> or <kbd>return</kbd>.
The text will change to have each word capitalized:
![Converted to title case](img/applied_titleCase.png){:width="700px"}

View File

@ -1,9 +1,13 @@
---
title: 1. Adding Live Template Support
title: Adding Live Templates to a Plugin
---
<!-- Copyright 2000-2020 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
This tutorial is based on the SDK code sample [`live_templates`](https://github.com/JetBrains/intellij-sdk-docs/tree/master/code_samples/live_templates).
This tutorial illustrates how to add default Custom Live Templates to an IntelliJ Platform plugin, and assign valid contexts for these templates based on the surrounding code and file type.
In addition, the tutorial discusses how to export existing Live Templates, and bundle them within a plugin.
Any Live Template that can be created and exported can be added to a plugin by following the Template Creation, Export, and Extension Point Registration processes.
This tutorial uses the SDK code sample [`live_templates`](https://github.com/JetBrains/intellij-sdk-docs/tree/master/code_samples/live_templates).
* bullet
{:toc}
@ -77,10 +81,9 @@ For 2020.1 and later, follow this section to register the extension points and t
#### Register Extension Points
Using the `com.intellij.defaultLiveTemplates` and `com.intellij.liveTemplateContext` extension points, register the implementations with the IntelliJ Platform.
The `file` attribute in the `defaultLiveTemplates` element specifies `path/filename` under the `src/main/resources` folder.
The filename does not include the file extension.
```xml
<extensions defaultExtensionNs="com.intellij">
<defaultLiveTemplates file="/liveTemplates/Markdown"/>
<defaultLiveTemplates file="/liveTemplates/Markdown.xml"/>
<liveTemplateContext implementation="org.intellij.sdk.liveTemplates.MarkdownContext"/>
</extensions>
```