Interface: Playground
An object that represents the LiveCodes playground instance.
The object exposes multiple methods that can be used to interact with the playground.
See docs for details.
Extends
Properties
destroy()
destroy: () =>
Promise<void>
Destroys the playground instance, and removes event listeners.
Further call to any SDK methods throws an error.
Returns
Promise<void>
Example
import { createPlayground } from "livecodes";
createPlayground("#container").then(async (playground) => {
await playground.destroy();
// playground destroyed
// any further SDK call throws an error
});
Inherited from
Defined in
exec()
exec: (
command, ...args) =>Promise<object|object>
Executes custom commands, including: "setBroadcastToken" and "showVersion".
See docs for details.
Parameters
• command: APICommands
• ...args: any[]
Returns
Promise<object | object>
Inherited from
Defined in
format()
format: (
allEditors?) =>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.
Parameters
• allEditors?: boolean
Returns
Promise<void>
Example
import { createPlayground } from "livecodes";
createPlayground("#container").then(async (playground) => {
await playground.format();
// code in editors is formatted
});
Inherited from
Defined in
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.
Returns
Promise<Code>
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;
});
Inherited from
Defined in
getConfig()
getConfig: (
contentOnly?) =>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.
Parameters
• contentOnly?: boolean
Returns
Promise<Config>
Example
import { createPlayground } from "livecodes";
createPlayground("#container").then(async (playground) => {
const config = await playground.getConfig();
});
Inherited from
Defined in
getShareUrl()
getShareUrl: (
shortUrl?) =>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.
Parameters
• shortUrl?: boolean
Returns
Promise<string>
Example
import { createPlayground } from "livecodes";
createPlayground("#container").then(async (playground) => {
const longUrl = await playground.getShareUrl();
const shortUrl = await playground.getShareUrl(true);
});
Inherited from
Defined in
load()
load: () =>
Promise<void>
Loads the playground, if not already loaded.
When the embed option loading is set to "click", the playground is not loaded automatically.
Instead, a screen is shown with "Click to load" button. Calling the SDK method load() allows loading the playground.
If the playground was not loaded, calling any other method will load the playground first before executing.
Returns
Promise<void>
Defined in
onChange()
onChange: (
fn) =>object
Runs a callback function when code changes.
Parameters
• fn
Returns
object
remove()
remove: () =>
void
Returns
void
Deprecated
Use watch method instead.
Inherited from
Defined in
run()
run: () =>
Promise<void>
Runs the result page (after any required compilation for code).
Returns
Promise<void>
Example
import { createPlayground } from "livecodes";
createPlayground("#container").then(async (playground) => {
await playground.run();
// new result page is displayed
});
Inherited from
Defined in
runTests()
runTests: () =>
Promise<object>
Runs project tests (if present) and gets test results.
Returns
Promise<object>
results
results:
TestResult[]
Example
import { createPlayground } from "livecodes";
createPlayground("#container").then(async (playground) => {
const { results } = await playground.runTests();
});
Inherited from
Defined in
setConfig()
setConfig: (
config) =>Promise<Config>
Loads a new project using the passed configuration object. If the config is a string, it is assumed to be a URL to a JSON file that contains the configuration object.
Parameters
• config: string | Partial<Config>
Returns
Promise<Config>
Throws
It throws an error if the config object (or URL) is invalid.
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
});
Inherited from
Defined in
show()
show: (
panel,options?) =>Promise<void>
Shows the selected panel.
See docs for details.
Parameters
• panel: "editor" | "result" | EditorId | ToolName | "toggle-result"
• options?
• options.column?: number
• options.full?: boolean
• options.line?: number
• options.zoom?: 1 | 0.5 | 0.25
Returns
Promise<void>
Example
await playground.show("style");
await playground.show("toggle-result");
await playground.show("result", { full: true });
await playground.show("script");
await playground.show("result", { zoom: 0.5 });
await playground.show("console", { full: true });
Inherited from
Defined in
watch
watch:
WatchLoad&WatchReady&WatchCode&WatchRun&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" | "run" | "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
});