Invoke

Overview

Executes JavaScript code within the specified PrismaView. This method enables dynamic communication between your SKSE plugin and the web-based UI, allowing you to update the interface, call JavaScript functions, and retrieve data from the DOM.

Important

This method is only available after the PrismaView’s DOM tree has been initialized. Use the onDomReadyCallback in CreateView to ensure the DOM is ready before calling Invoke.

Syntax

void Invoke(
    PrismaView view,
    const char* script,
    JSCallback callback = nullptr
);

Parameters

view (required)

• Type: PrismaView
• Description: The PrismaView instance in which the script will be executed

script (required)

• Type: const char*
• Description: A string containing the JavaScript code to execute
• Examples: Function calls, variable assignments, DOM manipulations

callback (optional)

• Type: JSCallback
• Default: nullptr
• Description: An optional callback function that will be invoked with the script’s execution result
• Parameters: Takes a single argument - the data returned from JavaScript as a string

Return Value

This method returns void. Use the optional callback parameter to receive return values from JavaScript.

Usage Examples

Basic JavaScript Execution

// Simple JavaScript execution without return value
PrismaUI->Invoke(view, "setBodyBackgroundColor('red')");

// Corresponding JavaScript function
window.setBodyBackgroundColor = (color) => {
    document.body.style.backgroundColor = color;
};

With Return Value

// JavaScript execution with callback to receive return value
static void OnReceiveBackgroundColor(const char* data) {
    logger::info("Current background color: {}", data);
}

PrismaUI->Invoke(view, "getBodyBackgroundColor()", OnReceiveBackgroundColor);

// JavaScript function that returns a value
window.getBodyBackgroundColor = () => {
    return document.body.style.backgroundColor;
};

JSON Format Example

You can use the nlohmann/json library to easily send structured data from C++ to your web UI:

Simple JSON Example

#include <nlohmann/json.hpp>
using JSON = nlohmann::json;

void SendPlayerData() {
    // Create JSON object with player information
    JSON playerData = {
        {"name", "Dragonborn"},
        {"level", 25},
        {"health", 100},
        {"magicka", 150}
    };

    // Send JSON to JavaScript
    std::string script = "updatePlayerInfo(" + playerData.dump() + ")";
    PrismaUI->Invoke(view, script.c_str());
}

// JavaScript function to handle the JSON data
window.updatePlayerInfo = (playerData) => {
    document.getElementById('player-name').textContent = playerData.name;
    document.getElementById('player-level').textContent = playerData.level;
    document.getElementById('health-value').textContent = playerData.health;
    document.getElementById('magicka-value').textContent = playerData.magicka;
};

JSON Benefits

Using JSON provides type safety, easy serialization, and makes your data structure clear and maintainable. The nlohmann/json library automatically handles proper escaping and formatting.

String Escaping

Escape Characters Warning

When passing strings containing quotes, backslashes, or special characters to JavaScript, you must properly escape them to prevent syntax errors and potential security issues.

Escape Function Example

Here’s a utility function to safely escape strings for JavaScript:

std::string escapeStringForJavaScript(const std::string& input) {
    std::ostringstream ss;
    for (char c : input) {
        switch (c) {
        case '\'': ss << "\\'"; break;
        case '\"': ss << "\\\""; break;
        case '\\': ss << "\\\\"; break;
        case '\n': ss << "\\n";  break;
        case '\r': ss << "\\r";  break;
        case '\t': ss << "\\t";  break;
        case '\b': ss << "\\b";  break;
        case '\f': ss << "\\f";  break;
        case '/':  ss << "\\/";  break;
        default:
            ss << c;
            break;
        }
    }
    return ss.str();
}

Usage Example

// Unsafe - could cause JavaScript syntax errors
std::string someText = "I don't like Flash";
std::string script = "someFunction('" + someText + "')";  // WRONG!
PrismaUI->Invoke(view, script.c_str());

// Safe - properly escaped
std::string someText = "I don't like Flash";
std::string script = "someFunction('" + escapeStringForJavaScript(someText) + "')";
PrismaUI->Invoke(view, script.c_str());

Best Practices

Performance Tip

Batch multiple UI updates when possible instead of calling Invoke multiple times in rapid succession. This reduces overhead and improves performance.

• DOM Ready: Always ensure the DOM is ready before calling Invoke
• String Escaping: Always escape strings using the provided function or similar method
• Return Values: Use callbacks for JavaScript functions that return data
• Performance: Minimize frequent Invoke calls during game loops. If you need it, instead use InteropCall method

Common Issues

Troubleshooting

If Invoke doesn’t work as expected, check:

• The DOM is fully loaded (use onDomReadyCallback)
• JavaScript function names are spelled correctly
• Quotes and special characters are properly escaped
• The PrismaView instance is valid and not destroyed