Self-contained component to embed in websites for running Kotlin code
Component that creates Kotlin-aware editors capable of running code from HTML block elements.
Insert a <script>
element into your page and specify what elements should be converted in its data-selector
attribute.
<script src="https://unpkg.com/kotlin-playground@1" data-selector="code"></script>
Or, if you need to separate process of loading/conversion, omit the data-selector
attribute and use a second <script>
element like this:
<script src="https://unpkg.com/kotlin-playground@1"></script>
<script>
document.addEventListener('DOMContentLoaded', function() {
KotlinPlayground('.code-blocks-selector');
});
</script>
You can also overwrite the server where the code will be sent to be compiled and analyzed (for example if you host a server instance that includes your own Kotlin libraries). For that you can set the data-server
attribute.
And you can also set a default Kotlin version for code snippets to run on. Bear in mind that the version set per editor will take precedence though:
<script src="https://unpkg.com/kotlin-playground@1"
data-selector="code"
data-server="https://my-kotlin-playground-server"
data-version="1.3.41">
</script>
Fork & clone the old server repository or the new server.
Install Kotlin-playground as dependency via NPM.
npm install kotlin-playground -S
And then just use it in your code.
// ES5
var playground = require('kotlin-playground');
document.addEventListener('DOMContentLoaded', function() {
playground('code'); // attach to all <code> elements
});
// ES6
import playground from 'kotlin-playground';
document.addEventListener('DOMContentLoaded', () => {
playground('code'); // attach to all <code> elements
});
Kotlin Playground supports several events, and also Kotlin version or server URL overwriting passing an additional options
parameter on initialisation.
For example:
function onChange(code) {
console.log("Editor code was changed:\n" + code);
}
function onTestPassed() {
console.log("Tests passed!");
}
const options = {
server: 'https://my-kotlin-playground-server',
version: '1.3.50',
onChange: onChange,
onTestPassed: onTestPassed,
callback: callback(targetNode, mountNode)
};
playground('.selector', options)
Events description:
onChange(code)
— Fires every time the content of the editor is changed. Debounce time: 0.5s.
code — current playground code.
onTestPassed
— Is called after all tests passed. Use for target platform junit
.
onTestFailed
— Is called after all tests failed. Use for target platform junit
.
onCloseConsole
— Is called after the console's closed.
onOpenConsole
— Is called after the console's opened.
getJsCode(code)
— Is called after compilation Kotlin to JS. Use for target platform js
.
code — converted JS code from Kotlin.
callback(targetNode, mountNode)
— Is called after playground's united.
targetNode — node with plain text before component initialization.
mountNode — new node with runnable editor.
getInstance(instance)
- Getting playground state API.
instance.state // playground attributes, dependencies and etc.
instance.nodes // playground NodeElement.
instance.codemirror // editor specification.
instance.execute() // function for executing code snippet.
instance.getCode() // function for getting code from snippet.
Use the following attributes on elements that are converted to editors to adjust their behavior.
data-version
: Target Kotlin compiler version:
<code data-version="1.0.7">
/*
Your code here
*/
</code>
args
: Command line arguments.
<code args="1 2 3">
/*
Your code here
*/
</code>
data-target-platform
: target platform: junit
, canvas
, js
or java
(default).
<code data-target-platform="js">
/*
Your code here
*/
</code>
data-highlight-only
: Read-only mode, with only highlighting. data-highlight-only="nocursor"
- no focus on editor.
<code data-highlight-only>
/*
Your code here
*/
</code>
Or, you can make only a part of code read-only by placing it between //sampleStart
and //sampleEnd
markers.
If you don't need this just use attribute none-markers
.
For adding hidden files: put files between <textarea>
tag with class hidden-dependency
.
<code>
import cat.Cat
fun main(args: Array<String>) {
//sampleStart
val cat = Cat("Kitty")
println(cat.name)
//sampleEnd
}
<textarea class="hidden-dependency">
package cat
class Cat(val name: String)
</textarea>
</code>
Also if you want to hide code snippet just set the attribute folded-button
to false
value.
data-js-libs
: By default component loads jQuery and makes it available to the code running in the editor. If you need any additional JS libraries, specify them as comma-separated list in this attribute.
<code data-js-libs="https://my-awesome-js-lib/lib.min.js">
/*
Your code here
*/
</code>
auto-indent="true|false"
: Whether to use the context-sensitive indentation. Defaults to false
.
theme="idea|darcula|default"
: Editor IntelliJ IDEA themes.
mode="kotlin|js|java|groovy|xml|c|shell|swift|obj-c"
: Different languages styles. Runnable snippets only with kotlin
. Default to kotlin
.
data-min-compiler-version="1.0.7"
: Minimum target Kotlin compiler version
data-autocomplete="true|false"
: Get completion on every key press. If false
=> Press ctrl-space to activate autocompletion. Defaults to false
.
highlight-on-fly="true|false"
: Errors and warnings check for each change in the editor. Defaults to false
.
indent="4"
: How many spaces a block should be indented. Defaults to 4
.
lines="true|false"
: Whether to show line numbers to the left of the editor. Defaults to false
.
from="5" to="10"
: Create a part of code. Example from
line 5 to
line 10.
data-output-height="200"
: Set the iframe height in px
in output. Use for target platform canvas
.
match-brackets="true|false"
: Determines whether brackets are matched whenever the cursor is moved next to a bracket. Defaults to false
data-crosslink="enabled|disabled"
: Show link for open in playground. Defaults to undefined
– only supported in playground.
data-shorter-height="100"
: show expander if height more than value of attribute
data-scrollbar-style
: Chooses a scrollbar implementation. Defaults to overlay
.
yarn install
.yarn start
to start local development server at http://localhost:9000.yarn test
to run tests.
TEST_HEADLESS_MODE=true
to run tests in headless mode.yarn run build
to create production bundles.