FTL Colorify
Syntax highlighting, rainbow indentation and format-on-save for Keycloak theme templates
(.ftl, FreeMarker). Built for login.ftl, template.ftl and friends, useful for any
FreeMarker + HTML template.
Features
Highlighting that separates FreeMarker from HTML
<#if>, <#list>, <#else>, <#import> and the other directives are colored as keywords,
<@layout.registrationLayout ...> macro calls as functions and ${...} interpolations get their
own punctuation color, so the template logic stands out from the markup.- Inside expressions, strings, numbers, built-ins (
?size, ?has_content), operators (??, !,
&&) and function calls (msg("...")) are colored like code.
- Works everywhere FreeMarker is allowed: inside tags (
<div <#if x>class="a"</#if>>), inside
attribute values (placeholder="${msg("enterEmail")}"), and inside <script> and <style>.
- HTML, JavaScript and CSS keep VS Code's normal coloring, with any color theme.
Rainbow indentation
Every indentation level gets its own translucent background color (four colors, cycling), so
deeply nested <#if> / <div> blocks are easy to follow. Indentation that is not a whole number
of levels is marked in red. Colors are configurable.
The extension registers a formatter for .ftl files and turns on editor.formatOnSave for them,
so every save re-indents the template, the way Prettier does for web files. It also works with
Format Document (Shift+Alt+F) and Format Selection.
What it does:
- Re-indents every line from the nesting of HTML elements, FreeMarker block directives
(
<#if>, <#list>, <#items>, <#switch>, <#macro>, <#function>, <#attempt>,
<#compress>, <#escape>, <#assign x>...</#assign> ...) and user directives
(<@layout.registrationLayout ...>...</@layout.registrationLayout>).
<#else>, <#elseif>, <#recover>, <#case> and <#default> are placed the way you expect.
- Uses the editor's tab size and spaces/tabs settings. For
.ftl files the extension defaults to
4 spaces, which matches Keycloak's own themes.
- Keeps the content of
<script>, <style> and <#noparse> exactly as you wrote it, shifted so it
sits one level inside the tag.
- Keeps multi-line tags readable: attribute lines go one level under the tag and keep their shape,
a line holding only
> or /> goes back out.
- Leaves
<pre> and <textarea> content untouched and keeps comments in shape.
- Trims trailing whitespace, collapses runs of blank lines (one by default) and ends the file with
a single newline.
- Tolerates the unbalanced markup that templates often contain (a
<div> opened in one <#if>
branch and closed after </#if>, <li> without </li>): nothing throws, the rest of the file
stays sensible.
What it does not do:
- It never changes your markup: no wrapping of long lines, no re-ordering of attributes, no quote
changes. Line content is preserved exactly, only leading whitespace changes.
- If the file has an unterminated
${, tag, string, comment or <script>, nothing is changed and a
message in the status bar says where the problem is.
To keep the formatter but turn off format on save for FreeMarker files only:
"[ftl]": { "editor.formatOnSave": false }
Settings
| Setting |
Default |
Description |
ftlColorify.format.enable |
true |
Register the formatter (Format Document, Format Selection, format on save). |
ftlColorify.format.maxBlankLines |
1 |
Maximum number of consecutive blank lines to keep. |
ftlColorify.format.trimTrailingWhitespace |
true |
Remove trailing whitespace (never inside <pre> or <textarea>). |
ftlColorify.format.insertFinalNewline |
true |
End the file with exactly one newline. |
ftlColorify.format.indentInnerHtml |
false |
Indent <head> and <body> inside <html>. Off matches Keycloak's base theme. |
ftlColorify.rainbow.enabled |
true |
Color indentation levels. |
ftlColorify.rainbow.colors |
4 translucent colors |
Background colors per level, any CSS color. Keep the alpha low. |
ftlColorify.rainbow.errorColor |
translucent red |
Color for indentation that is not a whole level. Empty string disables it. |
ftlColorify.rainbow.languages |
["ftl"] |
Language ids that get rainbow indentation. |
Indentation width and tabs vs. spaces come from the editor settings for the ftl language. The
extension sets these defaults, which you can override in your settings:
"[ftl]": {
"editor.formatOnSave": true,
"editor.tabSize": 4,
"editor.insertSpaces": true,
"editor.detectIndentation": false
}
Emmet abbreviations are enabled for .ftl files through emmet.includeLanguages.
Known limitations
- Only the angle bracket syntax (
<#if>) is recognized. The square bracket syntax ([#if])
is not, and Keycloak does not use it.
- VS Code's HTML tag completion and hover are only available for the
html language, not for ftl.
Development
npm install
npm test # compiles and runs the formatter tests (test/formatter.test.js)
npm run grammar-check # prints the scopes the grammar assigns to test/fixtures/login.ftl
npm run package # builds ftl-colorify-<version>.vsix
Press F5 in VS Code to launch an Extension Development Host with the extension loaded.
See PUBLISHING.md for publishing to the Marketplace.
License
MIT
| |
