This is an automated email from the ASF dual-hosted git repository. lukaszlenart pushed a commit to branch docs/ognl-color-settings in repository https://gitbox.apache.org/repos/asf/struts-intellij-plugin.git
commit 9c10029082192ed2adf85c56d6a37fd1b287dd37 Author: Lukasz Lenart <[email protected]> AuthorDate: Fri Nov 13 12:43:53 2026 +0100 docs: specify the OGNL color settings page migration (#151) Record the agreed registration, page id, and verification before implementation. Co-authored-by: Cursor <[email protected]> --- .../specs/2026-11-13-ognl-color-settings-design.md | 142 +++++++++++++++++++++ 1 file changed, 142 insertions(+) diff --git a/docs/superpowers/specs/2026-11-13-ognl-color-settings-design.md b/docs/superpowers/specs/2026-11-13-ognl-color-settings-design.md new file mode 100644 index 0000000..1e16658 --- /dev/null +++ b/docs/superpowers/specs/2026-11-13-ognl-color-settings-design.md @@ -0,0 +1,142 @@ +# OGNL Color Settings Page on `colorSettings` + +**Date:** 2026-11-13 +**Status:** Draft for review +**Issue:** [#151](https://github.com/apache/struts-intellij-plugin/issues/151) + +## Problem + +IntelliJ Platform 2026.3 deprecates `com.intellij.colorSettingsPage`. The replacement is `com.intellij.colorSettings`. The IDE builds Settings | Editor | Color Scheme from that declaration and creates the `ColorSettingsPage` only when the page is opened. + +`src/main/resources/META-INF/ognl.xml` still registers the old extension: + +```xml +<colorSettingsPage implementation="com.intellij.lang.ognl.highlight.OgnlColorSettingsPage"/> +``` + +The plugin already targets 2026.3 only (`pluginSinceBuild = 263`, `pluginUntilBuild = 263.*`). The old extension does not need to stay for older IDEs. + +## Goals + +1. Register the OGNL color page with `com.intellij.colorSettings`, with display name `OGNL` and page id `OGNL`. +2. Make `OgnlColorSettingsPage.getId()` return that same id. +3. Leave the page's descriptors, demo text, highlighter, and icon as they are. +4. Keep the page in the language group at weight 0 by omitting `priority` and `groupWeight`, which is the extension default. +5. Record the move in `CHANGELOG.md`. + +## Non-Goals + +- Implementing `DisplayPrioritySortable`, or setting `priority` and `groupWeight` in XML. +- Registering `colorSettingsPage` beside `colorSettings`. +- A message bundle for the page name. +- Changing attribute keys, descriptor labels, demo text, the highlighter, or the file-type icon. +- A platform, Gradle, or since-build bump. +- An automated test of the Settings tree, or of applying a scheme color to an editor. + +## Decision + +Change the existing page class in place. The declaration carries the name and the id. The class returns the same id and the same display name. Order stays the extension default: language group, weight 0. The class does not implement `DisplayPrioritySortable`, so the declaration does not set `priority` or `groupWeight`. + +The values in the declaration must match the class. The tree reads the declaration. The opened page reads the class. The IDE reports a mismatch. This change adds no plugin-side check. + +## Registration + +In `src/main/resources/META-INF/ognl.xml`, replace the `colorSettingsPage` element with: + +```xml +<colorSettings implementation="com.intellij.lang.ognl.highlight.OgnlColorSettingsPage" + displayName="OGNL" + pageId="OGNL"/> +``` + +`pageId` sets the page id. The common extension `id` attribute does not. + +`displayName` is the literal `OGNL`. It matches `OgnlColorSettingsPage.getDisplayName()`, which returns `OgnlLanguage.INSTANCE.getDisplayName()`. `OgnlLanguage` does not override `getDisplayName()`, and its id is `OGNL`, so that call returns `OGNL`. + +## Page class + +In `OgnlColorSettingsPage`, add: + +```java +@NotNull +@Override +public String getId() { + return OgnlLanguage.ID; +} +``` + +`OgnlLanguage.ID` is `"OGNL"`. The class continues to implement `ColorSettingsPage` only. + +These members stay: + +| Member | Behavior | +|---|---| +| `getDisplayName()` | `OgnlLanguage.INSTANCE.getDisplayName()` | +| `getIcon()` | `OgnlFileType.INSTANCE.getIcon()` | +| `getAttributeDescriptors()` | The twelve descriptors below, in this order | +| `getColorDescriptors()` | `ColorDescriptor.EMPTY_ARRAY` | +| `getHighlighter()` | `new OgnlHighlighter()` | +| `getDemoText()` | The current OGNL sample | +| `getAdditionalHighlightingTagToDescriptorMap()` | `fqnType` → `OgnlHighlighter.FQN_TYPE` | + +Descriptor labels, in order: + +1. Background +2. Expression bounds +3. Keyword +4. Operations +5. Identifier +6. String +7. Number +8. Comma +9. Parentheses +10. Brackets +11. Braces +12. Class reference + +Attribute keys stay on `OgnlHighlighter`. Saved color schemes keep their OGNL colors because those colors are stored under the keys, and the keys do not change. + +## Changelog + +Under `CHANGELOG.md` `[Unreleased]` → `Changed`, add: + +- Migrate the OGNL color settings page to the declarative colorSettings extension ([#151](https://github.com/apache/struts-intellij-plugin/issues/151)) + +## Testing + +### Automated + +Add `src/test/java/com/intellij/lang/ognl/highlight/OgnlColorSettingsPageTest.java`. It extends `LightPlatformTestCase`, in the same style as `OgnlHighlightingLexerTest`, and it starts with that file's Apache license header. It constructs `OgnlColorSettingsPage` and asserts: + +- `getId()` equals `OgnlLanguage.ID` and equals `"OGNL"` +- `getDisplayName()` equals `"OGNL"` +- attribute descriptor display names are the twelve labels above, in that order +- `getColorDescriptors()` is empty + +Run: + +```bash +./gradlew test --tests "OgnlColorSettingsPageTest" -x rat +./gradlew test -x rat +./gradlew runPluginVerifier +``` + +`runPluginVerifier` must complete successfully, and its output must not mention `colorSettingsPage`. + +### Manual + +With `./gradlew runIde`: + +1. Open Settings | Editor | Color Scheme | OGNL. +2. Confirm the twelve descriptors are listed. +3. Change the Keyword color. +4. Confirm an OGNL fragment uses the new Keyword color. + +## Files + +| File | Change | +|---|---| +| `src/main/resources/META-INF/ognl.xml` | Replace `colorSettingsPage` with `colorSettings` | +| `src/main/java/com/intellij/lang/ognl/highlight/OgnlColorSettingsPage.java` | Add `getId()` | +| `src/test/java/com/intellij/lang/ognl/highlight/OgnlColorSettingsPageTest.java` | New test | +| `CHANGELOG.md` | One `Changed` bullet under `[Unreleased]` |
