Hidden code feature?

[shiffman]

This is a feature request / idea that I am curious about. I am working on a new version of Nature of Code and am revamping the interactive examples with p5.js. I think that p5.js-widget could work really well for some/all of the code examples. One thing I do sometimes for long examples is show only part of the code in the book (esp if it's just a change from a previous example). I wonder if it would work to have a widget that has invisible code behind the scenes for a full example and show / makes editable a shorter snippet.

Am I making sense?

I am still probably a couple weeks from getting to this part of the project, but thought I would file this while the idea is fresh in my head.

[toolness]

Oh yeah, this is definitely something that I'd like to support with the widget!

I'm curious what the best UI for this is, both from the authorial standpoint and the end-user standpoint. Here's one idea...

function setup() {
  createCanvas(200, 200);
  fill(255, 0, 200);
}

// WIDGET: BEGIN SNIPPET
function draw() {
  ellipse(mouseX, mouseY, 50, 50);
}
// WIDGET: END SNIPPET
</script>

Basically the widget would see the comments // WIDGET: BEGIN SNIPPET and // WIDGET: END SNIPPET and only show the user the code between them by default. The actual sketch that runs, though, would "splice" whatever edits the user made into the full sketch.

In some sense the existing implicit setup() functionality is a specific instance of this generalized behavior, as it allows the code the user sees (and potentially tinkers with) to run within the context of something bigger.

There could also be some kind of "show all code" button on the widget that allows the user to "pop open the hood" and see the entire sketch, not just the snippet you want to show by default.

Does this make sense?

[toolness]

Another thing that'd be neat would be the ability to actually define a sketch "template" that multiple widgets build off of, to address the case where a new snippet is just a change from a previous example. This would allow authors to have widgets that represent lots of minor changes to an initial sketch without violating DRY, but it could also get complicated... hmm. Could just leave it to the author to use some kind of JS templating engine to populate the <script type="text/p5"> tags before passing them on to the widget for rendering if they really want to explore such an option, too.

[iamjessklein]

Yes! This kind of goes along with this idea that I have been having around the widget. We've received feedback from a few educators that the widget doesn't allow students to have that a-ha - wow! "this is a web page?!" moment. One thought that I had to support this (and I think would help the challenge that @shiffman is facing) is to have an expand button within the widget that would take the user to the IDE. This will provide learners a way to have real context and allow them to slowly level up their skills.

I tried to capture it in a few sketches.

[shiffman]

Wow, this is an amazing discussion! I'm actually already using a similar mark-up in my book related to how code comments are styled and formatted. It looks like this:

// [full] This comment relates to the next two lines of code
int x = 100;
int y = 100;
// [end]
void setup() {
  size(400, 400); // [bold] this line is bolded
  // This is just a regular comment
  background(0);
}

The book is now built with something called Magic Book developed by @runemadsen there might be something we could align here in terms of discussion / ideas.

[runemadsen]

Awesome. This is super exciting. I'm doing code-splitting in Magic Book using the newly published magicbook-codesplit plugin. So in this case, we could use that plugin to do the codesplitting, and then add the P5.js widget on top of the parsed code easily. That's what I'm planning to do. https://github.com/magicbookproject/magicbook-codesplit

[runemadsen]

Oh, I guess that doesn't make much sense, as you need the full example to run in the widget. Anyway, I'll be happy to align.

[toolness]

Cool, that is totally doable!

Is there documentation or a specification for the comment mark-up format? One option is for Magic Book and p5.js-widget to implement "conformance" to this standard separately, or, since it looks like Magic Book is also in JS, we could have a separate npm module that does the parsing logic, and both tools can share that.

[toolness]

Hi again @runemadsen and @shiffman! I'm just circling back to see how soon you need this kind of functionality, and if you have any details on the specification for the mark-up format. No worries if you're too busy or anything, there's no rush on my end--I'd just like to make sure the feature is ready if/when you need it!

[shiffman]

Thanks for the ping! I've been slow to keep up with my work on the nature of code book so there is no rush right now, but I will be in touch soon as I get a bit further along!