tessl/npm-node-json2html

HTML templating in pure javascript that transforms JSON objects into HTML using JavaScript template objects

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Component Management

Name: tessl/npm-node-json2html
Author: tessl

System for creating and managing reusable template components that can be referenced by name in templates. Components provide modularity and reusability across different templates and rendering contexts.

Capabilities

Add Components

/**
 * Add a single component with name and template
 * @param {string} name - Component name for referencing
 * @param {object} template - Template object defining the component
 */
function add(name, template);

/**
 * Add multiple components from an object
 * @param {object} components - Object with name:template pairs
 */
function add(components);

Usage Examples:

const json2html = require('node-json2html');

// Add a single component
json2html.component.add('user-card', {
  "<>": "div",
  "class": "user-card",
  "html": [
    { "<>": "h3", "text": "${name}" },
    { "<>": "p", "text": "Age: ${age}" },
    { "<>": "span", "class": "status", "text": "${status}" }
  ]
});

// Add multiple components at once
json2html.component.add({
  'header': {
    "<>": "header",
    "class": "page-header",
    "html": { "<>": "h1", "text": "${title}" }
  },
  'footer': {
    "<>": "footer",
    "class": "page-footer", 
    "html": { "<>": "p", "text": "© ${year} ${company}" }
  },
  'button': {
    "<>": "button",
    "class": "${@theme} btn",
    "text": "${label}",
    "onclick": function(e) {
      if (this.onClick) this.onClick(e);
    }
  }
});

Get Components

Retrieve registered component templates by name for inspection or programmatic usage.

/**
 * Retrieve a component template by name
 * @param {string} name - Component name
 * @returns {object|undefined} Component template object or undefined if not found
 */
function get(name);

Usage Examples:

// Retrieve a component
const userCardTemplate = json2html.component.get('user-card');
console.log(userCardTemplate);
// Returns: { "<>": "div", "class": "user-card", "html": [...] }

// Check if component exists
const buttonTemplate = json2html.component.get('button');
if (buttonTemplate) {
  console.log('Button component is registered');
} else {
  console.log('Button component not found');
}

// Get non-existent component
const missing = json2html.component.get('non-existent');
console.log(missing); // undefined

Using Components in Templates

Reference registered components in templates using the "[]" property and pass data through other properties.

/**
 * Component reference template structure
 */
interface ComponentTemplate {
  /** Component name reference */
  "[]": string;
  
  /** Inner HTML content for the component (optional) */
  "html"?: object[] | object;
  
  /** Any other properties are passed as data to the component */
  [property: string]: any;
}

Component Usage Examples:

// Register a flexible card component
json2html.component.add('card', {
  "<>": "div",
  "class": "card ${@variant}",
  "html": [
    { "<>": "div", "class": "card-header", "html": "${title}" },
    { "<>": "div", "class": "card-body", "html": "${html}" },
    { "<>": "div", "class": "card-footer", "text": "${footer}" }
  ]
});

// Use the component in templates
const template = {
  "<>": "div",
  "class": "container",
  "html": [
    {
      "[]": "card",
      "title": "Welcome",
      "footer": "Last updated: ${lastUpdated}",
      "html": [
        { "<>": "p", "text": "Hello ${name}!" },
        { "<>": "button", "text": "Get Started" }
      ]
    }
  ]
};

const data = { name: "Alice", lastUpdated: "2023-12-01" };
const html = json2html.render(data, template, { 
  props: { variant: "primary" } 
});

Component Properties and Context

Components receive data through template properties and can access the current rendering context.

/**
 * Component context and data flow
 */
// Properties passed to component template:
// - All properties except "[]" and "html" are available as data
// - "html" property provides nested content accessible via ${html}
// - Parent object data is available through normal interpolation
// - Global properties available via @property syntax

Component Context Examples:

// Register a list item component
json2html.component.add('list-item', {
  "<>": "li",
  "class": "${@itemClass}",
  "data-id": "${id}",
  "html": [
    { "<>": "span", "class": "label", "text": "${label}" },
    { "<>": "div", "class": "content", "html": "${html}" }
  ]
});

// Use component with various data sources
const template = {
  "<>": "ul",
  "html": [
    {
      "[]": "list-item",
      "id": "${id}",           // From current data object
      "label": "${name}",      // From current data object  
      "html": [
        { "<>": "p", "text": "${description}" },
        { "<>": "small", "text": "Created: ${@currentDate}" }  // From props
      ]
    }
  ]
};

const items = [
  { id: 1, name: "Task 1", description: "Complete the project" },
  { id: 2, name: "Task 2", description: "Review the code" }
];

const html = json2html.render(items, template, {
  props: { 
    itemClass: "task-item",
    currentDate: new Date().toLocaleDateString()
  }
});

Local vs Global Components

Components can be defined globally (available across all renders) or locally (specific to a single render call).

// Global components (persistent across renders)
json2html.component.add('global-header', { "<>": "h1", "text": "${title}" });

// Local components (specific to single render)
const html = json2html.render(data, template, {
  components: {
    'local-badge': { 
      "<>": "span", 
      "class": "badge ${@color}", 
      "text": "${count}" 
    }
  }
});

Local Component Priority:

// Global component
json2html.component.add('button', {
  "<>": "button",
  "class": "btn-default",
  "text": "${label}"
});

// Local component overrides global for this render
const html = json2html.render(
  { label: "Save" },
  { "[]": "button" },
  {
    components: {
      'button': {  // This overrides the global button component
        "<>": "button",
        "class": "btn-primary",
        "text": "${label}",
        "type": "submit"
      }
    }
  }
);
// Uses the local button component definition

Dynamic Component References

Component names can be dynamic using string interpolation, allowing for conditional component selection.

// Dynamic component selection
const template = {
  "[]": "${componentType}",  // Dynamic component name
  "data": "${.}"             // Pass current object as data
};

const data = [
  { componentType: "user-card", name: "Alice", type: "user" },
  { componentType: "admin-card", name: "Bob", type: "admin" }
];

// Register different components for different types
json2html.component.add('user-card', {
  "<>": "div", "class": "user", "text": "${name}"
});

json2html.component.add('admin-card', {
  "<>": "div", "class": "admin", "text": "Admin: ${name}"
});

const html = json2html.render(data, template);
// Renders different components based on componentType property