What Are Insert/Replace Tags?

Insert/Replace Tags are special comment-based markers that JCB uses to identify and preserve your custom PHP, HTML, or JS code inside generated files. These tags allow you to inject logic, override behavior, or add UI without losing your changes when recompiling your component.

They are one of the foundational features of JCB’s round-trip development philosophy, enabling you to safely edit compiled code while maintaining upgradeability.

Key Features

• 🔖 Comment-Based Code Anchors: Use easy-to-read tag formats like /***[INSERT<>$$$$]***/ to mark where your code should appear.
• 🔄 Round-Trip Persistence: Custom code inside these tags survives every recompile — even if other parts of the file are regenerated.
• 🧠 Replace vs. Insert: Insert adds your code into a generated area. Replace completely overrides a section of generated code with your own.
• 🛠 Multi-Language Support: Works in PHP, HTML, XML, INI, and JavaScript files with appropriate comment syntax.
• 📦 Compiler Integration: During compile, JCB scans your existing files, extracts tagged blocks, and reinserts them in the correct locations.
• 🔍 Compiler Debug Logs: Logs include which tags were found, skipped, or updated — making troubleshooting easy.
• 🧾 Visual Markers in Code: Makes your logic clearly visible and easily editable in any IDE or text editor.
• 🧬 Used Across Views, Models, Templates: Insert/Replace works throughout JCB’s MVC structure, in site/admin views, helper files, forms, and more.

Use Cases

• Add extra buttons to a toolbar in a custom admin view
• Inject a helper method into a model or controller
• Override default output of a template block
• Add JavaScript to the document head only if needed
• Replace a generated field’s HTML with a custom layout
• Persist database manipulation logic in a model’s save method

How to Use Insert/Replace Tags

1. Open the compiled file where you want to insert logic.
2. Add a tag in the appropriate comment format:
   • Insert:/***[INSERT<>$$$$]***/ and /***[/INSERT<>$$$$]***/
   • Replace:/***[REPLACE<>$$$$]***/ and /***[/REPLACE<>$$$$]***/
3. Place your custom code inside the opening and closing tags:

/***[INSERT<>$$$$]***/
if ($this->item->price > 1000) {
    $this->item->priority = 'high';
}
/***[/INSERT<>$$$$]***/

4. Save the file.
5. On next compile, JCB will preserve or reinsert that code.

🧠 Pro Tip: Keep tag names descriptive and unique per file. Avoid duplicating tags with the same name in a single file.

Conclusion

Insert/Replace Tags are a cornerstone of JCB’s developer flexibility. They empower you to extend and personalize your component’s logic without fear of losing changes on rebuild. Whether you're injecting simple markup or overriding core controller logic, this system gives you safe, controlled customization with full round-trip support.