App Actions

os.compileApp(appId: string, content: any): SetAppOutputAction

Compiles the app with the given ID to display the given content. Each time this function is called, the app will be cleared and will display the specified content.

Used in tandem with os.registerApp(portalId, bot) to create custom apps.

The first parameter is a string and is the ID of the app.

The second parameter is a any and

Examples

Display a header

os.compileApp('myApp', <h1>Hello World!</h1>);

Display a button

os.compileApp('myApp',
    <button onClick={ () => os.toast("You clicked the button!")}>
        Click Me!
    </button>
);

Display an input box

os.compileApp('myApp',
    <input onInput={ (e) => { tags.label = e.target.value } } />
);

Display a slider input

os.compileApp('myApp',
    <input type="range" min="0" max="100" onInput={ (e) => { tags.label = e.target.value } } />
);

os.listBuiltinTags(): string[]

Gets the list of tag names that are built-in to CasualOS.

Includes tags like #color and #gridPortal, but not user-defined ones like {@tag [dimension]}.

Examples

Get the list of built-in tags

const builtinTags = os.listBuiltinTags();
os.toast(builtinTags);

os.registerApp(portalId: string, bot: (string | Bot)): Promise<void>

Registers a app with the given ID, bot, and options. Returns a promise that resolves when the app has been registered. Can be called multiple times with new options to override previous options.

Once setup, CasualOS will send a @onAppSetup whisper to the given bot. At this point, you can call os.compileApp(appId, content) to set what the app displays.

CasualOS will also define a global variable {app}Bot that points to the given bot.

Apps work by running the HTML you give it by calling os.compileApp(appId, content) with the HTML you want the app to show. Since JavaScript does not natively support HTML, we are using a special extension called JSX that adds HTML-like syntax to JavaScript.

At the most basic, JSX is like writing HTML inside JavaScript:

let htmlData = <div>
    <h1>Hello World</h1>
</div>;

See this article for more information: Introducing JSX

CasualOS also includes a helper called html that can be used to make HTML objects out of a string. You can use it to convert a string into HTML by adding it before a string that uses backticks, like this:

let htmlData = html`
    <div>
        <h1>Hello World</h1>
    </div>
`;

JSX is the preferred way to write HTML inside JavaScript since CasualOS can properly detect it and add helpful features like syntax highlighting and error messages.

The first parameter is a string and is the ID that the app should have.

The second parameter is a (string | Bot) and is the bot that should represent the app. This is the bot that recieves the @onAppSetup whisper and should generally be in charge of calling os.compileApp(appId, content) .

Examples

Setup a basic app

await os.registerApp('basicApp', thisBot);
os.compileApp('basicApp', <h1>Hello World!</h1>);

Setup an app with a button

await os.registerApp('buttonApp', thisBot);

os.compileApp('buttonApp',
    <button onClick={ () => os.toast("You clicked the button!") }>
        Click Me!
    </button>
);

Setup an app with an input box

await os.registerApp('inputApp', thisBot);

os.compileApp('inputApp',
    <input onInput={ (e) => { tags.label = e.target.value } }>
);

os.registerTagPrefix(prefix: string, options?: RegisterPrefixOptions): Promise<void>

Specifies that the given prefix should be used to indicate that the tag contains script content. Use this function to specify custom prefixes that function similarly to @ or 🧬.

The first parameter is a string and is the prefix that should indicate that the rest of the tag value is a script.

The second parameter is optional and is a RegisterPrefixOptions and is the options that should be used for the prefix.

Examples

Add 📖 as an script prefix.

await os.registerTagPrefix("📖");

Register some arbitrary text as a prefix.

await os.registerTagPrefix("myPrefix");

Register a prefix as JSX code.

await os.registerTagPrefix("🔺", {
    language: "jsx"
});

Register a prefix with a name.

await os.registerTagPrefix("🔺", {
    language: "jsx"
    name: 'Triangle'
});

os.unregisterApp(appId: string): Promise<void>

Unregisters and removes the app with the given ID. Returns a promise that resolves when the app has been removed.

The first parameter is a string and is the ID of the app.

Examples

Unregister an app

await os.unregisterApp('myApp');