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 #[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');