New guide for the EditContext API

[captainbrosset]

Description

This PR introduces a guide page for the EditContext API.

Motivation

I wrote the EditContext API reference docs recently, but didn't have the time to write a tutorial then. This PR introduces a longer tutorial that goes over all of the steps required to build a rich text editor by using the EditContext API. It puts all of the concepts together into one logical demo, so that users can understand how everything fits.

Additional details

• Ref doc: https://developer.mozilla.org/en-US/docs/Web/API/EditContext_API
• A demo I built, which this tutorial is based on: https://microsoftedge.github.io/Demos/edit-context/
  Note: this demo lives on a Microsoft Edge demo repo, because that's where I originally built it. I'm moving it to dom-examples in New EditContext API demo dom-examples#248 (in fact, the tutorial already references this location).

Related issues and pull requests

mdn/mdn#493

[github-actions]

Preview URLs

• /en-US/docs/Web/API/EditContext_API/Guide

External URLs (2)

URL: /en-US/docs/Web/API/EditContext_API/Guide
Title: Using the EditContext API

• <(https://github.com/mdn/dom-examples/tree/main/edit-context/html-editor/converter.js)> (2 times) (Note! This may be a new URL 👀)
• https://mdn.github.io/dom-examples/edit-context/html-editor/ (2 times) (Note! This may be a new URL 👀)

(comment last updated: 2024-03-18 21:36:15)

[captainbrosset]

@dandclark could you please take a look at this new tutorial, and let me know if you see anything wrong with the steps and code?

[skyclouds2001]

some macros usage and a typo fix

[dandclark]

Thanks for creating this, I think it will be really helpful for people.
I just had some small suggestions.
GitHub won't let me mark this Approved because I don't have the right permissions in the repo, but consider it approved from me. :)

[wbamberg]

Thank you for this Patrick! I'll take a look.

[wbamberg]

I've had a read through this and more or less understand the pieces. I think it's great. But I had a question though - how closely tied do you want this tutorial to be, to the working example? Or to put things another way, do you expect that someone should just be able to follow this through, step by step, and have something working at each stage?

Because at the moment there's quite a bit of divergence between this guide and the working sample code, and there are things not covered, that people need to do if they are to have things work.

So for instance, in Make the editor editable you instantiate editContext, but it's inside an if block. So then in Render the text, if I naively add editContext.addEventListener("textupdate", (e) => {..., it won't work.

In your working example, of course, it's a bit different, you have the instantiation and the event listener inside an IIFE, so it works.

Quite often on MDN we make tutorials work step-by-step, like the WebGL tutorial for instance (https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API/Tutorial/Getting_started_with_WebGL). That tutorial tries to be very explicit about what code to add when, and when to check the result, and what you should see (and not see) at each point. It's not necessarily wrong, the way you have it, but it should anyway be an explicit choice.

An alternative I suppose is where you don't follow the tutorial step by step, but instead you have the code open next to the guide, and the guide talks through the code, which is closer to what you have here. But even then there are things missing - for example the guide talks about the CSS for the editor div and the custom highlight, but not for the tokens.

[captainbrosset]

Great point @wbamberg. I decided to go with the latter option. There is a lot of code in the demo app that isn't necessarily related to the EditContext API, and I didn't want that to lead to a much longer tutorial that would contain unnecessary details.

So, I changed the way the code snippets are introduced, by instead saying things like "The demo app uses this event to do that", followed by code snippets that, now, don't need to be complete.

I hope this approach works. Let me know what you think.

[wbamberg]

Hope these comments are helpful. Mostly I've tried to play reading the guide with the code alongside, and noting places where there was some friction.

One other comment that I could not fit anywhere else: the code has a "debug" mode that adds some complexity but is not explained in the guide. If it were up to me I would just omit the debug code. Or even maybe have a separate version of this demo with the debug code in?

[captainbrosset]

@wbamberg thanks for the great review comments. I think I've addressed them all. Let me know what you think.

[wbamberg]

👍 thank you Patrick, this looks great!