Embedding Kotlin Playground

Oh yes, this is a runnable Kotlin snippet embedded right in the blog post.
Note that you can not only run it, but you can also change the code:

Cool, isn’t it? Note that completion works too.

Often you don’t want to show all the code in the snippet, but instead only the most interesting and substantial parts of it. This is possible as well.

You can also add tests:

You can use JavaScript as a target or even draw on a canvas:

Sometimes you don’t need or can’t make a runnable sample. In that case you can apply a highlight-only attribute and get the snippet exactly in the same style, but without the ability to run it.

Embedded Kotlin playground and how it’s done

Historically, thousands of newcomers used try.kotlinlang.org as an interactive way of learning the language. In particular, Kotlin Koans online have been extremely popular. More advanced users use this playground for trying small snippets without opening an IDE, for example before pasting code as an answer on StackOverflow.
Embedded Kotlin Playground works on the same technology, but lets you write and run samples on your webpages. It compiles code on our backend server and then runs either in your browser (if the target platform is JS) or on a server (if the target is set to JVM).

Frontend

Adding an embedded Kotlin playground is as easy as writing a single line in the page header:

Now all the code blocks on the page will be converted to runnable Kotlin snippets. Of course, data-selector is customizable and you can apply the script only to some particular class. There’s also an option to configure a Kotlin playground manually:

There’re also a lot of different installation and customization options. Read more in the documentation.

Backend

The backend part of the playground compiles the code and provides information for completion and highlighting. Generally, you shouldn’t need to bother about the backend and you may stick with our server unless you want to reference custom JVM libraries.

For writing examples that use some external library, for example when you’re creating interactive documentation for your library, you will have to configure and run your instance of the playground backend. It’s very easy to do: you’ll just need to add any dependencies, run two predefined Gradle tasks, then docker-compose up, and voila – the server is running. See these instructions for details.

Where it’s already used

  • We already extensively use this technology for writing Kotlin documentation on the official website. All new bits of documentation are written using runnable samples (see Basic syntax, What’s new in 1.1 and 1.2, Lambdas and Coroutines. For some functions from the standard library, there are live examples as well (see groupBy for example).
  • Kotlin By Example is written with Kotlin-Playground live samples.
  • We’ve also released a plugin for WordPress. It adds a [kotlin] shortcode which allows embedding an interactive Kotlin playground in any post. All the samples on this page are written with the help of this plugin.
    preview
  • On the Kotlin forum, you can use the run-kotlin language in markdown syntax to answer questions, with full correctness guaranteed.
    discuss3

Where this can be used

Kotlin Playground improves the reading experience and increases the expressiveness of code examples. It allows readers to not only see the code but also run it, change it, play with it, and run it again. We encourage all authors to use runnable Kotlin snippets, especially when creating:

  • Learning courses
  • Supplementary materials for slides and books
  • Documentation for libraries and frameworks
  • Examples in blog posts

Later we are going to support scripting in Kotlin Playground as well.

This entry was posted in Playground, Releases, Tools. Bookmark the permalink.

15 Responses to Embedding Kotlin Playground

  1. Nick Apperley says:

    Is the Kotlin playground coming to the Medium blogging platform?

  2. Simon says:

    I integrated this fantastic feature on my blog to see how it works:

    https://kotlinexpertise.com/coping-with-kotlins-scope-functions/

    It’s super easy and I love it! Yet, I’d love to have the code formatted with Darcula theming, is this possible or at least planned?

  3. Anonymous says:

    Clicking the plus icon on the JS-target canvas drawing example almost crashed my Chrome, froze it for about 10 seconds.

    Other than that, great work with this!

  4. Andrey Mischenko says:

    Do you plan to support dependencies out of the box? At least Kotlinx dependencies, such as kotlin-reflect, kotlinx.coroutines, kotlinx.serialization, kotlinx.html, ktor etc

    • jtonic says:

      Hi,

      Great work!

      This is amazing for kotlin articles. As Andrey spotted out it would be great to have some libraries included out of the box (those mentioned by Andrey plus one of my favourites – arrow).

    • prendota says:

      We have some basic libraries like kotlinx.coroutines. You need to set the import before code snippet, for example: “import kotlin.coroutines.experimental.*”.

  5. Hardzsi says:

    It’s an impressive feature, I really like it!

    However, I completely missed it when studied Basic Syntax etc. – not knowing about it’s importance, I missed to press the green play and unhide (+) buttons… This turned out to be an error, because unhiding the whole code snippets make me understood those way better…

    So, for other Kotlin starters/users not to make this mistake, I would suggest to make these featues more transparent somehow. Maybe a sentence about this interactive feature on top of pages where those were included -with play and unhide icons- would be enough.

    Also, I would suggest some way (keyboard shortcut?) to expand or collapse ALL embedded code snipplets on page AT ONCE; for printing or to save the page as PDF, it would be nice.

  6. I was wondering about the line “Later we are going to support scripting in Kotlin Playground as well.” – what kind of scripting?

    One feature that I miss is a web interface that could run code inside my running applications (like the Grails web console plugin), it is extremely useful for debugging live systems and their 3rd party collaborators.

    I would ideally want a library that I can hook up to my web framework (so authentication etc. can be handled by my framework) and a way to provide some objects for the submitted code to use (e.g. services, DAO instances, Spring beans.. – the submitted code should perhaps implement an interface or a function type of mine to access them?).

    Sandboxing the incoming code isn’t really an issue because such a feature would only be available to a narrow group of developers anyway.

    Could something like this be realistically be built using the Kotlin Playground infrastructure?

  7. Eric Hubbard says:

    How does the code completion work? is there a set of steps to show it in action? I couldn’t seem to get anything like that to work..

  8. Holger Brandl says:

    Great feature. Is there some keyboard shortcut to execute the code cell (that is “clicking” the green play button without the mouse)?

Leave a Reply

Your email address will not be published. Required fields are marked *