HeartCore HTML BY NHUTPT

Creator: NHUTPT-LVN

HeartCore HTML BY NHUTPT is a Visual Studio Code extension for teams working with HeartCore CMS templates. It highlights every @@@...@@@ directive, guides you through HeartCore syntax with IntelliSense, and keeps Hearcode snippets readable inside larger HTML layouts.

Highlights

• Inline decorations colorize delimiters, commands, subcommands, parameters, and values so each part of a HeartCore directive stands out.
• Supports .hclv, .hclv.html, and regular .html files; language mode switches automatically based on the file name.
• Completion provider suggests HeartCore commands, subcommands, parameters, comparison operators, and known placeholders as you type :, =, @, or #.
• Placeholder cache lists every ###PLACEHOLDER### defined in the open document, making reuse fast and typo free.
• Lint diagnostics warn about mismatched @@@ delimiters and mispaired IF/ELSE/ENDIF blocks, preventing hard-to-debug template errors.
• Watches optional configuration files so custom completion rules reload the moment you edit them.

Quick Install

1. Run npm install once if you plan to build your own VSIX (installs @vscode/vsce).
2. Package the extension with npx @vscode/vsce package to produce hearcode-html-colorizer-x.y.z.vsix.
3. Install the VSIX in VS Code via code --install-extension hearcode-html-colorizer-x.y.z.vsix or through the Extensions view (More Actions -> Install from VSIX...).
4. Reload VS Code to activate the extension.

Using the Extension

1. Open or create a .hclv / .hclv.html file. VS Code should show Hearcode HTML in the status bar.
2. Type a directive such as @@@include:TABLE:ITEM1@@@ and note how each segment is colored differently.
3. Press Ctrl+Space (or start typing : / =) to accept completions for commands, subcommands, parameters, condition names, and comparison operators.
4. When you reuse placeholders, type ### and pick any available name from the completion list.
5. Hover HeartCore commands to read short explanations pulled from the built-in command metadata.
6. If a diagnostic appears, place the caret on the underlined range to read the warning and fix the directive before publishing.

Completion Reference

• include - render a single attribute or field. Offers include-mode suffixes (for example .div, .text, .html) and parameters like format, escape, and placeholder handling.
• list - iterate over database rows. Provides list parameters such as limit, start, order, entry, if, and filtering helpers.
• condition - manage conditional blocks with name-aware if, elseif, else, and endif directives. The provider suggests the same condition name to avoid mismatches.
• now - output the current time with optional offsets (day=+1, hour=-3) and formatting tokens (format=%Y-%m-%d).
• set / assign - update session, request, page, or cookie variables with scoped parameters (scope=local, scope=global) and formatting hints (type=text, type=html).
• search - run HeartCore search queries. Includes common arguments (query, database, mode, limit, orderby).
• extension / _extension - call custom extension functions defined in HeartCore. You can extend these completions via the configuration options below.

Configuration

All settings live under hearcodeHtmlColorizer.

• completionStructurePath: path to a JSON file that augments the built-in completion structure. Relative paths resolve against the first workspace folder; ~ expands to your home directory. The file is watched and reloaded automatically.
• customCompletion: in-editor JSON object that merges into the completion catalog. Ideal for per-project tweaks without committing a separate file.

Each custom completion entry can:

• Append new subcommands for a HeartCore directive.
• Supply extra parameter suggestions (scoped by parameter name or default fallback).
• Set "__replace": true to replace the built-in suggestions entirely for a command.

Customizing Colors

The extension ships sensible defaults for both light and dark themes, but you can override them through settings.json using editor.tokenColorCustomizations. The TextMate scopes exposed by the grammar are:

• meta.hearcode.block - entire @@@...@@@ region.
• entity.name.function.hearcode.command - command segment (for example include).
• entity.other.attribute-name.hearcode.subcommand - subcommands and include suffixes.
• variable.parameter.hearcode - parameter names.
• constant.other.hearcode.value - assigned values.
• punctuation.definition.hearcore.begin / punctuation.definition.hearcore.end - opening and closing @@@ markers.

Development

• Source entry point: extension.js (activation, decorations, completions, diagnostics).
• Grammar files: syntaxes/hearcode-html.tmLanguage.json (Hearcode language) and syntaxes/hearcode-html-injection.tmLanguage.json (HTML injections).
• Run code --extensionDevelopmentPath=<path-to-repo> to launch VS Code with the unpacked extension for debugging.
• Keep extension.js.bak or the packaged VSIX files as snapshots when experimenting with new features.

Known Limitations & Tips

• Extremely large templates may require a brief pause for the decoration engine to finish parsing. The debounce keeps the editor responsive but you might see colors appear after about 100 ms.
• Diagnostics focus on delimiter pairing and condition names; they do not currently validate parameter semantics.
• HeartCore control keywords must use the same condition label (for example @@@condition:if:CHK@@@ ... @@@condition:endif:CHK@@@). The warning helps catch mismatches before deployment.
• If the syntax coloring does not activate for an .html file, manually set the language mode to Hearcode HTML once; associations persist across sessions.
• Remember to distribute updated completion JSON files alongside your templates when collaborating so teammates see the same suggestions.

Happy HeartCore CMS coding!