search

forem / forem

For empowering community 🌱
https://forem.com
GNU Affero General Public License v3.0
21.76k stars 3.97k forks source link

Interactive code snippets #9

Closed viebel closed 6 years ago

viebel commented 7 years ago

Dev.to looks awesome. Congrats!

I was thinking of an integration of the klipse plugin into dev.to to allow blog writers to have interactive code snippets in javascript, ruby, python, scheme or ocaml.

And write cool blog posts like:

What do you say?

benhalpern commented 7 years ago

I really love the idea of doing this, but I don't want to rush into this. Here are my concerns.

Performance

It's unclear how this could potentially degrade the user experience on lower-end devices and generally be weighty. I want this site to be broadly accessible. And playing around with the online REPL, seems like it can freeze the browser by adding arbitrarily difficult computations incidentally. I'm very anti-browser-jank. 😄

UX

I want to make sure this is needed and necessary for the articles we're creating. REPLs are not necessarily relevant for a lot of code snippets. Not really sure what percentage of code snippets the REPL does, in fact, make sense. I think it should be available when it is appropriate, but then you add the burden of choice when creating a post. I don't want to overcomplicate that part.

Future

If we roll this out for posts and decide this isn't what we want in the future, we are going to have some decisions about supporting existing posts that have the REPL.

These are my main concerns. I do think this is very exciting, and could be a huge boon to our site. I just want to get it right. Having you here to discuss this further is great. We could probably mix it in on a few posts and experiment with it for a bit.

bundance commented 7 years ago

@benhalpern, I can maybe add a few thoughts in based on my experience with using Klipse in my tutorials.

IMHO, REPL code snippets make a lot of sense when trying to explain small individual features of libraries, or syntax features of a specific language. For example, I used Klipse extensively with my series on Immutable.js (which @viebel mentioned, above), as it enables readers (and myself!) to experiment with Immutable's API.

Equally, I've written a bunch of tutorials on ES6 destructuring, again using Klipse, and again in order to help readers understand what was going on by being able to experiment with the code themselves.

I'm not sure I'd use it for a tutorial explaining a framework, or anything involving a large chunk of code, though (largely because Klipse only outputs the last line evaluated).

As for your concerns with the future should you decide not use it, it's no problem at all stripping it out, as it's just a JavaScript script tag to include the library, and then a simple pre and code tag around the snippet of code you want to make REPLable (I'm sure that's a word!). If you remove the Klipse script tag, you're left with un-REPLed code wrapped by a plain pre and code tag, which is just rendered as plain HTML.

I'm not sure about its impact on user performance. I probably should be, but I value the REPL in my tutorials so much, I'm prepared to ignore any jank (I use Immutable a lot in my day job, and find the Klipse examples I wrote invaluable, particularly when experimenting with the API and making sure a code snippet is returning the value I think it should).

jrheard commented 7 years ago

@benhalpern your comment is spot-on, these are all correct thoughts to be having / questions to be asking.

i can speak a bit to perf. here's some context in case it's helpful, apologies if you already know all this. the KLIPSE plugin is written in clojurescript, which is a language that's compiled to javascript and can then be further compressed using the Google Closure Compiler. there are a few different levels of compilation, but essentially there's advanced compilation and there's not-advanced compilation. advanced compilation is really good and can make clojurescript programs much smaller and faster, because it does all sorts of inlining and other compiler tricks - in particular, it can detect which parts of the compiled javascript are never actually used and remove those. this is called dead code elimination, and it's super great.

so, there are two different version of the KLIPSE plugin: one is compressed using advanced compilation, and one is not. my understanding (@viebel , can you confirm?) is that the advanced-compiled plugin can be used for all languages (python, javascript, etc) except clojurescript, but if you want to hook KLIPSE up to clojurescript snippets in your blog post you need to use the not-advanced one. i've heard that this is because self-hosted clojurescript can't be compiled using advanced mode, but i don't 100% understand what that means or why it's the case.

anyway, i said i'd be talking about performance. here are some numbers: http://blog.jrheard.com/procedural-dungeon-generation-cellular-automata is a post that uses the not-advanced version of the plugin, because it uses klipse for clojurescript snippets. on shaky coffeeshop wifi, it takes me 1.09s to download the plugin on a cache miss, and the plugin is about 990KB gzipped. once the plugin is downloaded, the page does lock up a bit for about two seconds while KLIPSE initializes itself and turns the posts's snippets into little REPLs.

i'd consider that about the worst case - i'd expect the advanced version of the snippet to be noticeably smaller and faster.

i don't have any posts of my own that use the advanced version, but http://untangled.io/immutable-js-an-introduction-with-examples-written-for-humans/ appears to. again on shaky coffeeshop wifi, i see it taking 309ms to download the 778KB advanced-compiled klipse plugin. once it downloads, i see it taking about 500ms for the plugin to initialize itself. it doesn't appear to lock up the window while it's doing that - this post is noticeably snappy to load and initialize.

what this all means is that you can expect posts that use the advanced-compiled version of the KLIPSE plugin (which can be used for snippets that aren't in ClojureScript) to have a negligible (IMO) performance hit. posts that use the non-advanced version of the plugin will be noticeably slower to load, by about two seconds. you could mitigate this by either only allowing the advanced version of the plugin to be used, or by warning authors that if they want to use the non-advanced version so they can write a post with interactive ClojureScript snippets, their posts will have that on-load perf hit i've mentioned.

i don't really know what dev.to is and i've gotta get back to some other stuff i was doing, i just saw a post that asked for info on KLIPSE performance and figured i'd leave a drive-by comment :) i hope this is helpful! good luck!

benhalpern commented 7 years ago

Thanks for the great feedback, guys. It's a lot of great stuff to consider. Will play around with it soon, and there's a good chance I can include it. I'll report back any further thoughts. More input is certainly welcome.

@jrheard dev.to is our platform for programmers to write about programmers and share ideas. It's growing. You should write a post 😉

viebel commented 7 years ago

I can confirm what @jrheard wrote about the two versions of klipse:

The reason is that for the moment, self-host clojurescript (the engine that evaluates clojure code snippets) doesn't support advanced compilation.

@benhalpern don't hesitate to contact me on the klipse repo if you need further help for experimenting the integration.

viebel commented 7 years ago

@benhalpern did you have time to play around with klipse?

benhalpern commented 7 years ago

@viebel getting to this as we speak. I made a public declaration of this as well 😁 https://dev.to/ben/probably-coming-soon-to-devto-interactive-code-snippets

viebel commented 7 years ago

Cool. I believe it will be a big differentiator vs. medium. As it is impossible to load external scripts on medium.

On Sun, 8 Jan 2017 at 18:27 benhalpern notifications@github.com wrote:

@viebel https://github.com/viebel getting to this as we speak. I made a public declaration of this as well 😁 https://dev.to/ben/probably-coming-soon-to-devto-interactive-code-snippets

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/thepracticaldev/dev.to/issues/9#issuecomment-271161516, or mute the thread https://github.com/notifications/unsubscribe-auth/AA6VPni8wmvOnPL1Ey05YSZkpkZjK9Sqks5rQQ6GgaJpZM4LNvF8 .

benhalpern commented 7 years ago

Here's the first Klipse post on dev.to:

https://dev.to/ben/bringing-live-repl-functionality-to-devto-posts

One thing I am concerned about is people executing malicious code of some kind, since this will all be user-generated content. @viebel, can you comment on whether there are any built-in restrictions with the library that could prevent against certain code execution?

viebel commented 7 years ago

I am sharing your concern @benhalpern. I am working on a sanitized eval function that will block access to the DOM.

The problem with that is that it won't allow dev.to bloggers to write articles like Islands in clojure, Procedural texture geneation in javacript, fractals with python turtle...

It's hard to find the correct trade-off between security and coolness...

viebel commented 7 years ago

A first attempt to be secured is demonstrated here where the klipse snippets are embedded in an iframe with limited sandbox privileges.

In this approach klipse snippets are embedded in the source page with the klipse-snippet tag.

It provides both secured sandbox and allows snippets to manipulate the dom inside the iframe.

The main drawback is that data and code are not shared between snippets.

What do you think @benhalpern ?

amasad commented 7 years ago

I think this is a great idea. We'd be happy to augment the languages that Klipse support with the ones that we at Repl.it support (on the backend). A couple of ways we can help:

Edit: here is the list of languages that we support. Additional benefits include a full access to system resources, like writing to disk and seeing files live

benhalpern commented 7 years ago

@viebel Sandbox mode as demonstrated looks great. My expectation would be that data and code would not be shared between snippets as a default, but you have more experience thinking about these use-cases, so what do you think the consequences are to how people like to use the tool?

@amasad Awesome! Checking repl.it out now, really happy to explore integration opportunities with you. FYI, the Gist-like snippets page loads the scripts via http on an https page, so they were being blocked by my browser.

jrheard commented 7 years ago

Sharing data/code between snippets is really useful in blog posts, when you want to explain a program/algorithm by writing it from scratch one function at a time, eg http://blog.jrheard.com/procedural-dungeon-generation-drunkards-walk-in-clojurescript . Blog authors could fake this functionality in sandbox mode using the data-preamble feature, but that only works for ClojureScript snippets.

viebel commented 7 years ago

@jrheard I also feel that sharing code between snippets is an important feature. Then you can build a story. Your blog post becomes kind of literate programming.

BTW, node data-preamble works for all languages...

jrheard commented 7 years ago

Oh nice, I didn't know that - my mistake!

amasad commented 7 years ago

@benhalpern oops, fixed, thanks for pointing that out https://amasad.me/hello-world

viebel commented 7 years ago

@benhalpern how would you like to progress on the integration of Klipse?

viebel commented 7 years ago

@benhalpern there is now a secured mode inside KLIPSE that prevents malicious code.

benhalpern commented 7 years ago

Awesome!!! Just getting back around to this. Will be implemented for good shortly. Thanks a lot.

viebel commented 7 years ago

@benhalpern providing a 100% secured version of javascript eval is a tough task.

At the beginning, it would be better no to open it too widely but start with a group of bloggers that you trust.

Makes sense?

jessleenyc commented 7 years ago

@viebel just following up on this --- we've had it available to a limited amount of users. Is there any updates on your end regarding security?

viebel commented 7 years ago

@jessleenyc No updates yet regarding security. Could you share some examples of interactive blog posts with Klipse?

I'd like to see how bloggers use it in order to design a proper secure solution (it will probably require to cut some features).

benhalpern commented 6 years ago

Hey, we're going to close this for now because we sort of let our implementation rot and it wouldn't be fair to keep you hanging while we sit on our hands and deal with other priorities. But we do plan to revisit this once our codebase is open sourced.