Skip to main content

Interface: API

_internal.API

Hierarchy

Properties

destroy

destroy: () => Promise<void>

Destroys the playground instance, and removes event listeners.

Further call to any SDK methods throws an error.

Example

import { createPlayground } from "livecodes";

createPlayground("#container").then(async (playground) => {
await playground.destroy();
// playground destroyed
// any further SDK call throws an error
});

Type declaration

▸ (): Promise<void>

Returns

Promise<void>

Defined in

models.ts:210


exec

exec: (command: APICommands, ...args: any[]) => Promise<{ output: any } | { error: string }>

Executes custom commands, including: "setBroadcastToken" and "showVersion".

See docs for details.

Type declaration

▸ (command, ...args): Promise<{ output: any } | { error: string }>

Parameters
NameType
commandAPICommands
...argsany[]
Returns

Promise<{ output: any } | { error: string }>

Defined in

models.ts:193


format

format: (allEditors?: boolean) => Promise<void>

Formats the code.

By default, the code in all editors (markup, style and script) is formatted. To format only the active editor, the value false should be passed as an argument.

Example

import { createPlayground } from "livecodes";

createPlayground("#container").then(async (playground) => {
await playground.format();
// code in editors is formatted
});

Type declaration

▸ (allEditors?): Promise<void>

Parameters
NameType
allEditors?boolean
Returns

Promise<void>

Defined in

models.ts:31


getCode

getCode: () => Promise<Code>

Gets the playground code (including source code, source language and compiled code) for each editor (markup, style, script), in addition to result page HTML.

See Code for the structure of the returned object.

Example

import { createPlayground } from "livecodes";

createPlayground("#container").then(async (playground) => {
const code = await playground.getCode();

// source code, language and compiled code for the script editor
const { content, language, compiled } = code.script;

// result page HTML
const result = code.result;
});

Type declaration

▸ (): Promise<Code>

Returns

Promise<Code>

Defined in

models.ts:105


getConfig

getConfig: (contentOnly?: boolean) => Promise<Config>

Gets a configuration object representing the playground state.

This can be used to restore state if passed as an EmbedOptions property when creating playgrounds, or can be manipulated and loaded in run-time using setConfig method.

Example

import { createPlayground } from "livecodes";

createPlayground("#container").then(async (playground) => {
const config = await playground.getConfig();
});

Type declaration

▸ (contentOnly?): Promise<Config>

Parameters
NameType
contentOnly?boolean
Returns

Promise<Config>

Defined in

models.ts:64


getShareUrl

getShareUrl: (shortUrl?: boolean) => Promise<string>

Gets a share url for the current project.

By default, the url has a long query string representing the compressed encoded config object. If the argument shortUrl was set to true, a short url is generated.

Example

import { createPlayground } from "livecodes";

createPlayground("#container").then(async (playground) => {
const longUrl = await playground.getShareUrl();
const shortUrl = await playground.getShareUrl(true);
});

Type declaration

▸ (shortUrl?): Promise<string>

Parameters
NameType
shortUrl?boolean
Returns

Promise<string>

Defined in

models.ts:48


onChange

onChange: (fn: (data: { code: Code ; config: Config }) => void) => { remove: () => void }

Runs a callback function when code changes.

Deprecated

Use watch method instead.

Type declaration

▸ (fn): Object

Parameters
NameType
fn(data: { code: Code ; config: Config }) => void
Returns

Object

NameType
remove() => void

Defined in

models.ts:141


run

run: () => Promise<void>

Runs the result page (after any required compilation for code).

Example

import { createPlayground } from "livecodes";

createPlayground("#container").then(async (playground) => {
await playground.run();
// new result page is displayed
});

Type declaration

▸ (): Promise<void>

Returns

Promise<void>

Defined in

models.ts:14


runTests

runTests: () => Promise<{ results: TestResult[] }>

Runs project tests (if present) and gets test results.

Example

import { createPlayground } from "livecodes";

createPlayground("#container").then(async (playground) => {
const { results } = await playground.runTests();
});

Type declaration

▸ (): Promise<{ results: TestResult[] }>

Returns

Promise<{ results: TestResult[] }>

Defined in

models.ts:134


setConfig

setConfig: (config: Partial<Config>) => Promise<Config>

Loads a new project using the passed configuration object.

Example

import { createPlayground } from "livecodes";

createPlayground("#container").then(async (playground) => {
const config = {
markup: {
language: "html",
content: "Hello World!",
},
};
const newConfig = await playground.setConfig(config);
// new project loaded
});

Type declaration

▸ (config): Promise<Config>

Parameters
NameType
configPartial<Config>
Returns

Promise<Config>

Defined in

models.ts:84


show

show: (panel: "result" | EditorId | "console" | "compiled" | "tests", options?: { column?: number ; full?: boolean ; line?: number ; zoom?: 1 | 0.5 | 0.25 }) => Promise<void>

Shows the selected panel.

See docs for details.

Example

await playground.show("style");
await playground.show("result", { full: true });
await playground.show("script");
await playground.show("result", { zoom: 0.5 });
await playground.show("console", { full: true });

Type declaration

▸ (panel, options?): Promise<void>

Parameters
NameType
panel"result" | EditorId | "console" | "compiled" | "tests"
options?Object
options.column?number
options.full?boolean
options.line?number
options.zoom?1 | 0.5 | 0.25
Returns

Promise<void>

Defined in

models.ts:118


watch

watch: WatchLoad & WatchReady & WatchCode & WatchConsole & WatchTests & WatchDestroy

Allows to watch for various playground events. It takes 2 arguments: event name and a callback function that will be called on every event.

event name can be one of: "load" | "ready" | "code" | "console" | "tests" | "destroy"

In some events, the callback function will be called with an object that supplies relevant data to the callback function (e.g. code, console output, test results).

The watch method returns an object with a single method (remove), which when called will remove the callback from watching further events.

See docs for details.

Example

import { createPlayground } from "livecodes";

createPlayground("#container").then((playground) => {
const codeWatcher = playground.watch("code", ({ code, config }) => {
// this will run on every code change
console.log("code:", code);
console.log("config:", config);
});

const consoleWatcher = playground.watch("console", ({ method, args }) => {
// this will run on every console output
console[method](...args);
});

const testsWatcher = playground.watch("tests", ({ results }) => {
// this will run when tests run
results.forEach((testResult) => {
console.log("status:", testResult.status); // "pass", "fail" or "skip"
console.log(testResult.errors); // array of errors as strings
});
});

// then later
codeWatcher.remove();
consoleWatcher.remove();
testsWatcher.remove();
// events are no longer watched
});

Defined in

models.ts:186