intellij-sdk-code-samples/topics/tutorials/postfix_completion/advanced_postfix_templates.md

Advanced postfix templates provide additional features like editing possibilities, expression selector, etc.

While simple templates can be handled by extending PostfixTemplate class directly, more advanced templates require additional functionalities like selecting the expression that a template should be applied to or editing a template content. The IntelliJ Platform provides the base classes simplifying advanced template's features implementation.

Postfix Templates With Expression Selector

In some contexts, it is not obvious what expression a template should be applied to. Consider the following Java code with the var postfix template at the end:

order.calculateWeight() > getMaxWeight(order.getDeliveryType()).var

In the above code, a postfix template could be applied to the getMaxWeight() method invocation and the entire comparison expression depending on the user's intention. The postfix template implementation could automatically apply the template on the topmost or the closest applicable expression, but it is reasonable to leave the expression selection for the user.

Postfix templates with expression selector can be achieved by implementing PostfixTemplateWithExpressionSelector and PostfixTemplateExpressionSelector classes.

Example: IntroduceFieldPostfixTemplate introduces a Java class field, allowing to select one of the non-void expressions at the current offset.

Live Template Syntax-Based Postfix Templates

The IntelliJ Platform-based IDEs provide the Live Templates feature. It allows defining a template text with dynamic expressions, replaced with actual values depending on the context. If the implemented postfix template's expanding behavior can be achieved with the live template syntax, it is much easier to extend the StringBasedPostfixTemplate than implementing the expansion behavior programmatically.

Example: StreamPostfixTemplate wraps array expression within the Arrays.stream() method.

See the section in SDK Docs for information on implementing the live templates feature in a plugin.

{type="note"}

Editable Postfix Templates

All postfix templates that return true from the PostfixTemplate.isEditable() method and have a key starting with . (dot) can be edited. In the simplest case, only the template's name can be edited. To provide more advanced editing possibilities, like creating new templates in the settings dialog, editing the template's content, variables, expression conditions, etc., a plugin must implement the related PostfixTemplateProvider's methods:

• PostfixTemplateProvider.createEditor() - returns an instance of the PostfixTemplateEditor class which is responsible for building the UI settings for a particular template and creating a template from the settings provided in this UI. The editor UI may contain settings controls other than the textual editor, like lists, checkboxes, etc.
• PostfixTemplateProvider.writeExternalTemplate() and readExternalTemplate() - serializes/deserializes a given template to/from XML elements. Serialized template data is stored in the PostfixTemplateStorage persistent component.

Implementing template, editor, and serialization methods from scratch is a tedious task, so the IntelliJ Platform provides classes that help implement editable templates:

• EditablePostfixTemplateWithMultipleExpressions for editable templates with expression selector and conditions limiting the applicable contexts. Like , it is text-based and uses the same live template syntax.
• PostfixTemplateEditorBase for editors implementing the most common features like editing content, expression conditions, or using the topmost expression for template expanding
• Utility class PostfixTemplatesUtils providing methods related to editable template data serialization

Examples:

• JavaPostfixTemplateProvider providing Java editable templates
• JavaPostfixTemplateEditor implementing editor for Java editable templates
• ObjectsRequireNonNullPostfixTemplate implementing template wrapping the selected expression in Objects.requireNonNull() method

Surround Postfix Templates

Existing Surrounder implementations of the feature required to invoke the Code | Surround With... action can be reused for postfix completion by extending the SurroundPostfixTemplateBase class and returning the surrounder object from the getSurrounder() method.

Example: NotNullCheckPostfixTemplate surrounding the selected expression with an if statement checking if the expression is null.