/matlab-uihtml-app-builder

name: matlab-uihtml-app-builder
description: Build interactive web applications using HTML/JavaScript interfaces with MATLAB computational backends via the uihtml component. Use when creating HTML-based MATLAB apps, JavaScript MATLAB interfaces, web UIs with MATLAB, interactive MATLAB GUIs, or when user mentions uihtml, HTML, JavaScript, web apps, or web interfaces.
license: MathWorks BSD-3-Clause (see LICENSE)
metadata:
  author: MathWorks
  version: "1.0"

MATLAB uihtml App Builder

This skill covers how to build interactive web applications that combine HTML/JavaScript interfaces with MATLAB computational backends using the uihtml component. The HTML side handles the UI; MATLAB does the computation.

When to Use This Skill

• Building interactive MATLAB apps with HTML/JavaScript interfaces
• Creating web-based UIs for MATLAB applications
• Building responsive MATLAB GUIs with HTML/CSS/JS
• When user mentions: uihtml, HTML, JavaScript, web app, web interface, interactive GUI
• Combining web UI design with MATLAB computational power
• Creating calculator apps, data visualizers, or form-based MATLAB tools

Core Architecture

The Four Components

1. **HTML Interface** - User interface with buttons, forms, displays 2. **JavaScript Logic** - Event handling and UI interactions 3. **MATLAB Backend** - Computational engine and data processing 4. **uihtml Component** - Bridge between HTML and MATLAB

Communication Patterns

The uihtml component enables bidirectional communication between JavaScript and MATLAB through several mechanisms:

Pattern 1: MATLAB → JavaScript (Data Property)

**Use Case**: Sending data from MATLAB to update the HTML interface

% MATLAB side
h.Data = "Hello World!";

// JavaScript side
htmlComponent.addEventListener("DataChanged", function(event) {
    document.getElementById("display").innerHTML = htmlComponent.Data;
});

Pattern 2: JavaScript → MATLAB (Events)

**Use Case**: Triggering MATLAB functions from user interactions

// JavaScript side - send event to MATLAB
htmlComponent.sendEventToMATLAB("Calculate", expression);

% MATLAB side - receive and handle event
h.HTMLEventReceivedFcn = @handleEvent;

function handleEvent(src, event)
    eventName = event.HTMLEventName;
    eventData = event.HTMLEventData;
    % Process event...
end

Pattern 3: MATLAB → JavaScript (Custom Events)

**Use Case**: Sending computed results or status updates to JavaScript

% MATLAB side - send custom event to JavaScript
sendEventToHTMLSource(h, "ResultChanged", result);

// JavaScript side - listen for custom event
htmlComponent.addEventListener("ResultChanged", function(event) {
    document.getElementById("display").textContent = event.Data;
});

Pattern 4: Complex Data Transfer

**Use Case**: Passing structured data between MATLAB and JavaScript

% MATLAB side - struct data gets JSON encoded automatically
itemData = struct("ItemName","Apple","Price",2,"Quantity",10);
h.Data = itemData;

// JavaScript side - access as object properties
htmlComponent.Data.ItemName  // "Apple"
htmlComponent.Data.Price     // 2
htmlComponent.Data.Quantity  // 10

**Important: decoding is automatic in both directions.**

• A JS object sent via `sendEventToMATLAB` arrives on `event.HTMLEventData` already converted to a MATLAB struct. **Do not call `jsondecode`**; it will fail on a struct.
• A MATLAB struct sent via `sendEventToHTMLSource` arrives on `event.Data` already as a JavaScript object. **Do not call `JSON.parse`**; it will fail on an object.
• Field names round-trip exactly: a JS `{x0: 1}` becomes a MATLAB `struct('x0', 1)`, not `struct('x_0', ...)` or similar.
• Numeric scalars arrive as MATLAB `double`. Wrap field reads with `double(data.x0)` if you want to be defensive about types.

Critical Rules

Security Requirements

• **ALWAYS** set `HTMLSource = 'trusted'` when using local HTML files:

  h.HTMLSource = fullfile(pwd, 'myapp.html');
  % This is treated as trusted automatically for local files

• **MUST** validate all input from JavaScript before processing in MATLAB
• **NEVER** use `eval()` on user input without strict sanitization
• **ALWAYS** restrict allowed characters in user input for expressions

Error Handling

**ALWAYS wrap MATLAB event handlers in try-catch blocks:**

function handleEvent(src, event)
    eventName = event.HTMLEventName;
    eventData = event.HTMLEventData;

    try
        % Process the event
        result = processData(eventData);

        % Send result back to JavaScript
        sendEventToHTMLSource(src, 'ResultEvent', result);

    catch ME
        % Handle errors gracefully
        fprintf('Error: %s\n', ME.message);
        sendEventToHTMLSource(src, 'ErrorEvent', ME.message);
    end
end

Data Validation

**ALWAYS validate user input before processing:**

function result = validateExpression(expression)
    allowedChars = '0123456789+-*/.() ';
    if ~all(ismember(expression, allowedChars))
        error('Invalid characters in expression');
    end
    % Additional validation...
    result = true;
end

File Organization

**Follow this directory structure:**

project/
├── app.m           # Main MATLAB function
├── app.html        # HTML interface
├── README.md       # Usage instructions
└── examples/       # Additional examples (optional)

Complete Examples

Example 1: Simple Calculator App

**MATLAB Side (calculator.m):**

function calculator()
    % Create main figure
    fig = uifigure('Name', 'Calculator', 'Position', [100 100 400 500]);

    % Create HTML component
    h = uihtml(fig, 'Position', [25 25 350 450]);
    h.HTMLSource = fullfile(pwd, 'calculator.html');
    h.HTMLEventReceivedFcn = @(src, event) handleEvent(src, event);
end

function handleEvent(src, event)
    eventName = event.HTMLEv