Internal browser and Executor.js API Documentation

The executor.js library provides an interface for web pages to interact with the Executor application. It allows for listening to events, retrieving data from Executor, and sending commands to control Executor's behavior.

In order for this to work the keyword command must contain $BCONNECT$ combined with one of the following internal browser open commands $B$, $BN$, $BROWSER$, $BROWSERNOFOCUS$. You can find out more about internal browser commands in the docs section.

Example of keyword command using local file:
file:///C:/projects/mystuff/test.html$BROWSER$$BCONNECT$
                
Example of keyword command opening an online resource
http://mysite.com/test.html$BROWSER$$BCONNECT$

Example of keyword command also sending Executor's input parameter
http://mysite.com/test.html?query=$U$$BROWSER$$BCONNECT$

Note: When using $BCONNECT$ and you change URL from within the internal browser session, Executor will only reconnect if running on the same domain or locally. Also if the internal browser is not visible in Executor (dismissed by user), it will not be connected (while not being visible).

Permissions

Executor has a connect permission security level that can be set in "Settings -> Browser". With this the user can make sure some connected browser commands are only run with their consent. The levels are listed below (default is 1). This is to protect the user from running potential malicious inputs.
When insufficient permission the user will be prompted the following options: "Allow once", "Always allow" (for the specific keyword using $BCONNECT$), "Don't allow".
Inside the keyword editor there's a "Remove connect permissions" link, if a keyword was "Always allowed". Additionally on mouse-over on that link you can see which permissions are granted.

• 0 = Always ask user permission no matter what command.
• 1 = Don't ask user for basic commands (setExecutorInput, showMessage, clearExecutorInput, getQuery, getColor, getBGColor, getCommand, getParameter, dismissBrowser, dismissExecutor, setFocusInput, setFocusBrowser).
• 2 = Don't ask for basic commands and open url (openUrl).
• 3 = Don't ask for basic commands, simulated browser clicks (using $BCLICK$) and open url.
• 4 = Don't ask for basic commands, run input command (runInput), browser clicks and open url.

Getting Started

First, include the executor-1.0.0.js script in your HTML file:

<script src="executor-1.0.0.js"></script>

You can download this and examples from the Executor community on Github

Most interactions with the Executor library should occur after it's ready. You can register a callback function using executor.onReady().

executor.onReady((executorInstance) => {
    console.log("Executor is ready!");
    // You can now safely call other executor methods
    // For example, set the page colors to match Executor:
    executorInstance.setColors();
    alert("Initial query: " + executorInstance.getQuery());
});

Event Listeners

These methods allow you to subscribe to events from the Executor application.

onReady(callback)

executor.onReady(callback)

Registers a callback function to be executed when the Executor library is initialized and ready for interaction. If the library is already ready when onReady is called, the callback is executed immediately.

executor.onReady((exe) => {
    alert('Executor is now ready!');
    exe.setColors(); // Match page colors to Executor's theme
});

onResponse(callback)

executor.onResponse(callback)

Registers a callback function to listen for JSON-RPC responses from Executor. This is useful for getting feedback on commands sent to Executor that have a messageId.

executor.onResponse((resp) => {
    console.log("Received response from Executor:", resp);
    if (resp.id === mySentMessageId) {
        console.log("This is the response to my specific command!");
    }
});

onInput(callback)

executor.onInput(callback)

Registers a callback function to listen for changes in the Executor input field.

executor.onInput((input, command, parameter) => {
    console.log("Executor input changed:");
    console.log("Full input: " + input);       // e.g., "google best movies"
    console.log("Command: " + command);         // e.g., "google"
    console.log("Parameter: " + parameter);     // e.g., "best movies"
    document.getElementById('current-input').textContent = input;
});

Data Getters

These methods retrieve data from the Executor application. They should be called after onReady.

getQuery()

executor.getQuery()

Returns any parameter text that might have been entered in Executor when launching the URL for this webpage.

const initialQuery = executor.getQuery();
console.log("Launched with query:", initialQuery);

getColor()

executor.getColor()

Returns the current text color used by Executor.

const textColor = executor.getColor();
document.getElementById('my-element').style.color = textColor;

getBGColor()

executor.getBGColor()

Returns the current background color used by Executor.

const bgColor = executor.getBGColor();
document.body.style.backgroundColor = bgColor;

getInput(getStart = false)

executor.getInput(getStart)

Returns the current full text from Executor's input field. If getStart is true, it returns the input text as it was when the page was initialized.

const currentInput = executor.getInput();
const initialInput = executor.getInput(true);
console.log("Current input:", currentInput);
console.log("Initial input:", initialInput);

getCommand(getStart = false)

executor.getCommand(getStart)

Returns the current command part of Executor's input. If getStart is true, it returns the command as it was when the page was initialized.

const currentCommand = executor.getCommand();
console.log("Current command:", currentCommand);

getParameter(getStart = false)

executor.getParameter(getStart)

Returns the current parameter part of Executor's input. If getStart is true, it returns the parameter as it was when the page was initialized.

const currentParameter = executor.getParameter();
console.log("Current parameter:", currentParameter);

Action Methods

These methods send commands to the Executor application. They should be called after onReady.

setColors()

executor.setColors()

A helper function to set the document.body text color and background color to match the current Executor theme colors.

executor.onReady((exe) => {
    exe.setColors();
});

setExecutorInput(inputText, hintText, inputFocus, messageId)

executor.setExecutorInput(inputText, hintText, inputFocus, messageId)

Sets the text in Executor's input field. Note: If Executor recognizes your input as something it knows, hintText will be ignored.

const msgId = executor.setExecutorInput("new search query", "Search the web", true);
if (msgId) {
    console.log("setExecutorInput command sent with ID:", msgId);
}

showMessage(inputText, hintText, inputFocus, messageId)

executor.showMessage(inputText, hintText, inputFocus, messageId)

A helper function that sets Executor's input to a message that Executor will not try to resolve (by prepending "-> " to the input).

executor.showMessage("Operation successful!", "Status update");

clearExecutorInput()

executor.clearExecutorInput()

Helper function to clear Executor's input field.

executor.clearExecutorInput();

openUrl(urlToOpen, dismissExecutor = true, dismissBrowser = true, addToHistory = true, messageId)

executor.openUrl(urlToOpen, dismissExecutor, dismissBrowser, addToHistory, messageId)

Instructs Executor to open a URL. Note: If the user has set Executor to auto-hide in settings, then Executor will still hide even if dismissExecutor and/or dismissBrowser is set to false.

executor.openUrl("https://www.google.com", true, true, true);

runInput(inputText, dismissBrowser = true, addToHistory = true, messageId)

executor.runInput(inputText, dismissBrowser, addToHistory, messageId)

Runs an input text in Executor. Note: Some inputs might behave in a special way that might override dismissBrowser and addToHistory parameters.

executor.runInput("time");

dismissBrowser(messageId)

executor.dismissBrowser(messageId)

Hides this webpage and its browser view from Executor.

// Example: close this web view after some action
document.getElementById('closeButton').onclick = () => {
    executor.dismissBrowser();
};

dismissExecutor(messageId)

executor.dismissExecutor(messageId)

Hides the Executor application window.

executor.dismissExecutor();

setFocusInput(selectAll = false, setCursorAtEnd = false, cursorPos = -1, messageId)

executor.setFocusInput(selectAll, setCursorAtEnd, cursorPos, messageId)

Sets window focus to the Executor input field and optionally controls text selection/cursor position.

// Focus input and select all text
executor.setFocusInput(true);

// Focus input and place cursor at the end
executor.setFocusInput(false, true);

// Focus input and place cursor at position 5
executor.setFocusInput(false, false, 5);

setFocusBrowser(messageId)

executor.setFocusBrowser(messageId)

Sets focus to the internal browser displaying this webpage.

// Useful if you want to ensure the browser has focus for keyboard input
executor.setFocusBrowser();

Internal Properties and Methods

The following properties and methods are used internally by the executor.js library. You should generally not need to interact with them directly.

• _isReady (Boolean)
• _autoId (Number)
• _readyCallbacks (Array)
• _responseCallbacks (Array)
• _inputCallbacks (Array)
• _data (Object)
• sendCommand(data)
• sendMessage(data)
• ready()
• response(rpc)
• input(input, command, parameter)
• createCommand(f_method, f_params, f_id)

Some notes

• For debugging etc. You can right-click the internal browser and select "inspect" or make sure focus is on the internal browser and press F12. This will open the DevTools of the internal browser, with a console, and you can delete/modify storage/cookies/cache, debug etc.
• The list where the internal browser is displayed can have all sorts of sizes (some skins like "scale" type, allow resizing of width and height of the list), so you should consider using responsive design.
• The user might set Executor to flush the data folder of the internal browser aggressively, so using local storage and cookies etc. is not reliable.
• In case the user have denied permission to a function call, the response will have a error.code of 403
• The user agent of the internal browser per default contains "Executor/X.X" (X.X being version). The user however can disable this in settings for any privacy concerns, or define their own user agent. Of course if you want to do some design specially for a connected Executor ($BCONNECT$), you would not have to look at the user agent, as you can get this info from JavaScript, if Executor is the one opening the page (using executor.js).
• External browser windows opened by $BROWSERWIN$, $BROWSERWINEXE$ will not be connected despite the originated keyword having $BCONNECT$.

More examples

Checking response:

<script src="executor-1.0.0.js"></script>
<script>
    executor.onResponse((resp) => {
        console.log("Response received:", resp);
        if (resp.id === "customId123") {
            alert("Executor acknowledged: " + resp.result); // Assuming result field for success
        }
    });

    executor.onInput((input, command, parameter) => {
        console.log(`Input changed: Full='${input}', Cmd='${command}', Param='${parameter}'`);
    });

    executor.onReady((exe) => {
        console.log("Executor.js is ready. Instance:", exe);
        console.log("Initial Query:", exe.getQuery());
        console.log("Initial Input:", exe.getInput(true));
        console.log("Initial Command:", exe.getCommand(true));
        console.log("Initial Parameter:", exe.getParameter(true));

        // Example usage of onResponse
        const myMessageId = "customId123";
        exe.showMessage("Hello from the web page!", "Info", false, myMessageId);
    });    
</script>