Handlebars Templator

A simple, framework-agnostic HTML templating system using Handlebars.

Overview

This templating system allows you to:

1. Create reusable HTML components
2. Load components dynamically using custom HTML tags
3. Bind data to components using Handlebars templates
4. Pass data through HTML attributes
5. Nest components within each other
6. Share global data across all components
7. Use any CSS framework or JavaScript library you prefer

Project Structure

handlebars-templator/
├── components/           # HTML component templates
│   ├── main.html
│   ├── top-navigation.html
│   ├── sidebar.html
│   ├── content.html
│   └── footer.html
├── data/                 # JSON data files for components
│   ├── global.json       # Global data available to all components
│   ├── top-navigation.json
│   ├── sidebar.json
│   ├── content.json
│   └── footer.json
├── js/
│   ├── templator.js      # Core templating functionality
│   └── debug.js          # Debugging utilities
└── index.html            # Main HTML file

How It Works

1. The system uses custom HTML tags like <load-component-name></load-component-name> to load components
2. Each component can have an optional JSON data file with the same name
3. Data can be passed through HTML attributes using data- prefix
4. Handlebars is used to render the templates with the data
5. Components can be nested within each other
6. The system dispatches events when components are loaded, allowing you to initialize any framework or library

Usage

Basic Usage

1. Create an HTML component in the components/ directory (e.g., my-component.html)
2. Optionally create a JSON data file in the data/ directory (e.g., my-component.json)
3. Use the component in your HTML with <load-my-component></load-my-component>

Component HTML Example

<!-- components/my-component.html -->
<div class="my-component">
  <h2>{{title}}</h2>
  <p>{{description}}</p>
  
  {{#if showButton}}
  <button>{{buttonText}}</button>
  {{/if}}
</div>

Component Data Example

// data/my-component.json
{
  "title": "My Component",
  "description": "This is a sample component",
  "showButton": true,
  "buttonText": "Click Me"
}

Global Data Example

// data/global.json
{
  "appName": "My Application",
  "version": "1.0.0",
  "company": "Example Corp",
  "copyright": "© 2025 Example Corp. All rights reserved.",
  "contact": {
    "email": "[email protected]",
    "phone": "+1-555-123-4567"
  },
  "theme": {
    "primaryColor": "#007bff",
    "secondaryColor": "#6c757d",
    "fontFamily": "Arial, sans-serif"
  },
  "navigation": [
    { "title": "Home", "url": "/" },
    { "title": "About", "url": "/about" },
    { "title": "Services", "url": "/services" },
    { "title": "Contact", "url": "/contact" }
  ]
}

Using global data in components:

<!-- components/footer.html -->
<footer>
  <p>{{appName}} v{{version}}</p>
  <p>{{copyright}}</p>
  <p>Contact: {{contact.email}}</p>
</footer>

Using Components

<!-- In any HTML file or component -->
<load-my-component></load-my-component>

Passing Data Through Attributes

You can pass data to components using HTML attributes with the data- prefix:

<!-- Simple attribute data -->
<load-my-component data-title="Custom Title" data-description="Custom description"></load-my-component>

<!-- JSON attribute data for complex objects -->
<load-my-component data-config='{"title":"JSON Title","showButton":true,"buttonText":"Click Me!"}'></load-my-component>

Attribute names are converted from kebab-case to camelCase:

• data-title becomes title
• data-button-text becomes buttonText

Nesting Components

Components can be nested within each other, and data can be passed from parent to child:

<!-- components/parent.html -->
<div class="parent">
  <h1>{{title}}</h1>
  <load-child data-title="{{childTitle}}" data-content="{{childContent}}"></load-child>
</div>

Load in plain HTML page

Install templator tool

npm install kisphp-templator

Add the following lines at the bottom of your html page:

<script src="node_modules/kisphp-templator/dist/templator.js"></script>

Or simply use the CDN and add the following lines at the bottom of your html page:

<script src="https://cdn.jsdelivr.net/npm/kisphp/templator/dist/templator.js"></script>

JavaScript API

The templator exposes a global templator object with the following methods:

// Load a component dynamically
templator.loadComponent('my-component', containerElement);

// Load a component with attribute data
templator.loadComponent('my-component', containerElement, {
  title: 'Dynamic Title',
  description: 'Dynamic description',
  showButton: true,
  buttonText: 'Dynamic Button'
});

// Process all components in a container
templator.loadAllComponents(containerElement);

// Get the global data
const globalData = templator.getGlobalData();

// Update global data
templator.updateGlobalData({
  version: '1.1.0',
  newProperty: 'New Value'
});

// Reset global data to what's in the file
await templator.resetGlobalData();

Events

The templator dispatches the following events:

1. templator:loaded - Fired when all components are loaded
2. templator:componentLoaded - Fired when a specific component is loaded

Example:

// Listen for all components loaded
document.addEventListener('templator:loaded', function(e) {
  console.log('All components loaded at', e.detail.timestamp);
  
  // Initialize your framework here
  if (window.jQuery) {
    $(document).foundation();
  }
});

// Listen for specific component loaded
document.addEventListener('templator:componentLoaded', function(e) {
  console.log(`Component ${e.detail.componentName} loaded`);
  
  // Initialize specific components
  if (e.detail.componentName === 'slider') {
    // Initialize slider
  }
});

Debugging

The templator includes debugging utilities in debug.js:

// Check if all components loaded successfully
checkComponents();

// Force reload a specific component
reloadComponent('my-component');

// Create a new component dynamically
createComponent('my-component', containerElement);

// Create a new component with attribute data
createComponent('my-component', containerElement, 'append', {
  title: 'Debug Title',
  showButton: true
});

// Show global data
showGlobalData();

// Update global data
updateGlobalData({
  version: '1.1.0',
  newProperty: 'New Value'
});

// Reset global data to what's in the file
await resetGlobalData();

Running the Project

You need to serve the files from a web server due to CORS restrictions when loading local files.

Using Python:

python -m http.server

Using Node.js:

npx http-server

Then open http://localhost:8000 (or whatever port your server uses) in your browser.

Customization

You can use any CSS framework or JavaScript library with this templating system. Simply:

1. Include the CSS and JavaScript files in your HTML
2. Initialize the library after components are loaded using the templator:loaded event
3. Use the library's classes and attributes in your component HTML

Data Merging Priority

When multiple data sources are available, they are merged in the following priority order (highest to lowest):

1. HTML attribute data (data- attributes)
2. JSON data file (data/component-name.json)
3. Global data file (data/global.json)

This means attribute data will override component-specific JSON data, which will override global data when there are conflicts.

NPM :: Publish new version

• Change the version in package.json file
• Create tag on git repository
• Run npm publish

Create json data files

for i in $(ls components); do JS=$(echo $i | cut -f1 -d'.'); echo $JS; echo '{}' >> "data/${JS}.json"; done