API Communication

Control embedded SGApps web applications from your parent page using the WindowSocket postMessage bridge.

Setup

Include the WindowSocket library and create a connection to the iframe:

<iframe id="app" src="https://sgapps.io/online/webapp/photo-editor"></iframe>

<script src="https://sgapps.io/components/window-socket/index.js"></script>
<script>
    var iframe = document.getElementById('app');
    var socket = new WindowSocket(iframe.contentWindow);
    socket.start();
</script>

Sending Commands

Send commands to the app using socket.fire():

socket.fire("webapp::instance::request", eventName, arg1, arg2, ..., callback);

The eventName is mapped to api-request::instance:{eventName} inside the app. Each app defines its own set of API request events.

Examples

// Reset the photo editor canvas
socket.fire("webapp::instance::request", "reset", function (err) {
    console.log("Done");
});

// Get image data from photo editor
socket.fire("webapp::instance::request", "getDataBase64", "image/png", function (err, dataUrl) {
    // dataUrl is a base64 PNG
    document.getElementById("preview").src = dataUrl;
});

// Set editor content in code editor
socket.fire("webapp::instance::request", "active-file:codeEditor:value", "console.log('hello');", function () {
    console.log("Content set");
});

Built-in Events

These events are available for all apps:

webapp::instance::embed-mode

Toggle embed mode (hide/show window chrome):

// Enable: hides title bar, maximizes app
socket.fire("webapp::instance::embed-mode", true, function (err, isEmbedded) {
    console.log("Embedded:", isEmbedded); // true
});

// Disable: restores window chrome
socket.fire("webapp::instance::embed-mode", false, function (err, isEmbedded) {
    console.log("Embedded:", isEmbedded); // false
});

webapp::instance::require-redraw

Force a UI redraw (useful after container resize):

socket.fire("webapp::instance::require-redraw");

webapp::connection::ping

The app sends periodic ping messages to the parent after loading:

socket.on("webapp::connection::ping", function (appName) {
    console.log("App connected:", appName);
});

webapp::instance::error

Fires when the app fails to load:

socket.on("webapp::instance::error", function (errorMessage) {
    console.error("App error:", errorMessage);
});

App-Specific Events

Each app has its own set of api-request::instance:* events. When using socket.fire("webapp::instance::request", ...), the first argument after the event string becomes the event name suffix.

Photo Editor

// Apply sepia + brightness filter chain
socket.fire("webapp::instance::request", "applyFilters", [
    { name: "sepia", params: { level: 0.8 } },
    { name: "brightness", params: { level: 0.2 } }
], function () {
    console.log("Filters applied");
});

// Export as JPEG at 80% quality
socket.fire("webapp::instance::request", "getDataBase64", "image/jpeg",
    function (err, dataUrl) {
        // upload dataUrl to your server
    },
    0.8
);

SVG Editor

// Get SVG source from the editor
socket.fire("webapp::instance::request", "getSVGSource", function (err, svgString) {
    console.log("SVG:", svgString);
});

Code Editor

// Set code content
socket.fire("webapp::instance::request",
    "active-file:codeEditor:value",
    "function hello() { return 'world'; }",
    function () { console.log("Set"); }
);

// Read code content
socket.fire("webapp::instance::request",
    "active-file:codeEditor:value",
    function (value) { console.log("Code:", value); }
);

// Change syntax to Python
socket.fire("webapp::instance::request", "active-file:codeEditor:syntax", "python");

// Make editor read-only
socket.fire("webapp::instance::request", "active-file:codeEditor:options", { readOnly: true });

// Insert text at line 5
socket.fire("webapp::instance::request", "active-file:codeEditor:insertText",
    "// inserted comment\n", { line: 5, col: 1 }
);

// Set error markers
socket.fire("webapp::instance::request", "active-file:markers", [
    { startLine: 10, startCol: 1, endLine: 10, endCol: 20, message: "Unused variable", severity: 4 }
]);

// Get current selection
socket.fire("webapp::instance::request", "active-file:codeEditor:selection",
    function (err, sel) { console.log("Selected:", sel.text); }
);

Media Player

// Play a video from URL
socket.fire("webapp::instance::request", "source", "https://example.com/video.mp4");
socket.fire("webapp::instance::request", "play");

// Get playback status
socket.fire("webapp::instance::request", "getStatus", function (err, status) {
    console.log("Time:", status.currentTime, "/", status.duration);
});

// Seek to 30 seconds, set volume to 50%
socket.fire("webapp::instance::request", "seek", 30);
socket.fire("webapp::instance::request", "volume", 0.5);

XTerm (Terminal)

// Send a command to the shell
socket.fire("webapp::instance::request", "sendInput", "ls -la\r");

// Write text directly to the display
socket.fire("webapp::instance::request", "write", "\x1b[32mHello from parent page!\x1b[0m\r\n");

// Get terminal size
socket.fire("webapp::instance::request", "getSize", function (err, size) {
    console.log("Terminal:", size.cols, "x", size.rows);
});

File Manager & Archive Viewer

Both apps share the same filesystem API. All operations work on the input:// in-memory storage without server access.

Sandbox: All fs:* operations are restricted to the input:// protocol (browser-only in-memory storage). Server paths are not accessible via the API. App paths must start with https:, http:, data:, blob:, or input:.

// Create a project structure in memory
socket.fire("webapp::instance::request", "fs:mkdirp", "input://my-project/src/");
socket.fire("webapp::instance::request", "fs:write",
    "input://my-project/index.js", "console.log('hello');");
socket.fire("webapp::instance::request", "fs:cwd", "input://my-project/");

// List files
socket.fire("webapp::instance::request", "fs:ls", "input://my-project/",
    function (err, files) { console.log(files); });

Writer

Spreadsheet

GCode Editor

Complete Integration Example

<!DOCTYPE html>
<html>
<head>
    <title>My Image Editor</title>
    <style>
        #editor-frame { width: 100%; height: 500px; border: 1px solid #ccc; }
        .toolbar { padding: 10px; display: flex; gap: 8px; }
    </style>
</head>
<body>
    <div class="toolbar">
        <button id="btn-sepia">Apply Sepia</button>
        <button id="btn-export">Export PNG</button>
        <button id="btn-embed">Toggle Embed Mode</button>
    </div>

    <iframe id="editor-frame"
        src="https://sgapps.io/online/webapp/photo-editor"
        allow="clipboard-write"
    ></iframe>

    <img id="preview" style="max-width: 300px; margin: 10px;">

    <script src="https://sgapps.io/components/application-prototype/ApplicationPrototype.js"></script>
    <script src="https://sgapps.io/components/window-socket/index.js"></script>
    <script>
        var socket = new WindowSocket();
        socket.start();

        var embedded = false;

        document.getElementById('btn-sepia').addEventListener('click', function () {
            socket.fire("webapp::instance::request", "applyFilters", [
                { name: "sepia", params: { level: 0.9 } }
            ], function () {
                console.log("Sepia applied");
            });
        });

        document.getElementById('btn-export').addEventListener('click', function () {
            socket.fire("webapp::instance::request", "getDataBase64", "image/png",
                function (err, dataUrl) {
                    document.getElementById('preview').src = dataUrl;
                }
            );
        });

        document.getElementById('btn-embed').addEventListener('click', function () {
            embedded = !embedded;
            socket.fire("webapp::instance::embed-mode", embedded, function (err, state) {
                console.log("Embed mode:", state);
            });
        });
    </script>
</body>
</html>

WindowSocket Reference