What Is Smart Template Merging?

Smart Template Merging in JCB allows you to update templates, layouts, or snippets across projects while preserving your custom modifications. When JCB detects that a template used in your component has changed (e.g., in a newer blueprint version or updated from Git), it intelligently merges the new changes with your existing logic.

Instead of blindly overwriting or forcing you to manually diff changes, Smart Merging ensures that reusable elements — like Layouts, Snippets, Templates, and Library assets — stay in sync without data loss.

This feature is essential for teams or users working with shared templates, community blueprints, or versioned component boilerplates.

Key Features

• 🧠 Merge-Aware Updating: When a linked template, layout, or snippet is updated:
  • JCB checks for changes since your last use
  • Presents differences and potential merge paths
  • Merges logic if possible or flags conflicts for review
• 📂 Supported Entities: Smart merging works with:
  • Snippets (HTML, JS, PHP)
  • Layouts and Templates
  • File Templates
  • Linked Custom Code blocks
  • Shared Admin View Templates
• 🧪 Conflict Awareness: If a conflict is detected:
  • Review both versions
  • Choose to merge, override, or keep your version
• 🔁 Preserves Round-Trip Tags: Insert/Replace tags and dynamic placeholders remain untouched for safe rebuilds.
• 🔧 Manual or Automatic Control:
  • Manual (default): review before accepting
  • Automatic: apply when safe (no conflicts)
  • Git-based: sync templates via Git, then merge
• 📘 Template Versioning: Templates can include internal version markers or changelogs for auditing and tracking.
• 📤 Ideal for Shared Blueprints: Upgrade demo components or imported packages without losing custom logic.

Use Cases

• 🧩 Updating a layout used in multiple components (e.g., a Bootstrap 5 card view)
• 🔄 Pulling in template improvements from Git or the JCB community repo
• 👥 Working in a team where shared templates evolve over time
• 🛠 Applying UI fixes or enhancements without rebuilding the whole component
• 🚀 Keeping your custom logic while benefiting from upstream changes

How to Use Smart Template Merging

1. Link reusable templates, snippets, or layouts to your component.
2. If a new version is pulled in (via Git, JSON, or blueprint import), JCB checks for changes.
3. During editing or build:
   • JCB notifies you if the source template has changed
   • Shows diffs between your version and the update
4. Review and resolve:
   • Apply the new version
   • Keep your existing version
   • Merge changes manually
5. Compile the component. The updated, merged template is included.

🧠 Tip: Use version numbers (e.g., // v1.0.1) in template comments to help track and manage changes over time.

Conclusion

Smart Template Merging bridges the gap between reuse and flexibility. Whether you're maintaining your own boilerplates or collaborating with others, it gives you the confidence to adopt improvements without breaking your customizations. Stay in sync — without starting over.