[ARCHIVED] How to put Comments into your code in the HTML Editor

[a_p_g_robinson]

I have been playing around trying to figure out a persistent way of leaving comments in the html code of canvas pages for a while.

There have been various discussions in various threads as to whether or not we should be using comments in our code. I am not going to address that in this post, but rather just how to do it within the restrictions of the Canvas sanitizer.

My primary requirement was that the code I use should be persistent. It is possible in certain cases to save from the html editor and have something in the canvas page, but then see it stripped out by the sanitizer the moment you reopen for editing, as it always starts up in the rich text editor.

My secondary requirement was no unwanted changes to the look of the page as rendered by the browser, and to minimise the need to impose additional style on tags to achieve this.

The third requirement was to minimise the chance of impacting on APIs or anything else that may be using the various html attributes.

Lastly I wanted to try to minimise the semantic impact, ie not to introduce tags with semantic meaning unnecessarily. For instance a <div> marks a subsection of a page in semantic terms, and therefore an empty <div> is not necessarily a good thing.

Finally before going in to some examples, all of this is non-standard canvas usage. Whilst it appears to work, there is no guarantee that it will continue to do so if the canvas backend is changed. It is worth saving any significant lengths of code offline so that you don't find that everything you've added is stripped out when Instructure roll out a change.

There are three usage scenarios I wanted to address:

1) The ability to temporarily comment out a section of the page as displayed in the browser.
2) The ability to comment on individual elements
3) The ability to introduce general comments without changing the look of the page.

Here's what I have come up with (there may be better ways):

1) If you want to remove a section of the page from display in the browser, but leave it in the source code you can use:
        <div style="display: none;">

               ....Code to Remove Here

        </div>

The code will still be visible if someone looks at the page source, but will be removed from the browser display. It would be more semantically correct if we could use the 'hidden' attribute, but that is stripped out in canvas. Some screen-readers may read out elements marked 'display:none', but most apparently ignore it. This method is dependent on the 'display:none' attribute not being redefined in the css, but that it unlikely I would have thought.

2) If you want to comment on an individual tag you can take advantage of the data-* attribute. Canvas will pass this through for (almost) all whitelisted opening or single element tags as far as I can see (but will strip it from closing tags).
The * can be anything you like, so you can use it like this:

<p data-comment-abc123="THIS IS THE FIRST PARAGRAPH">content here</p>
<table data-comment-abc123="This is a table"><tr><td></td></tr></table>

and so on. I have tested all of the tags and found the following:

The <caption> tag is removed and any data-* attribute is lost.
The <b> tag is changed to strong, but the data-* attribute is retained.
The <br> tag is converted to <p> </p> and any data-* attribute is lost.

For all other cases the attribute appears to be retained.

Note the letters/numbers after "data-comment-". It is not inconceivable that an API could make use of an attribute called "data-comment" so stick your initials or something on the end to make a clash unlikely.

3) To put in a general comment without changing the look of the page is a subset of the ideas for (2). In general quite a few of the tags will be stripped out if they are empty (ie is there is nothing between the opening and closing elements). Others will be surrounded with <p></p> if not in a paragraph structure. Both of those things are undesirable for usage three. Safe tags are:
<div></div>
<h1></h1> - <h6></h6>
(possibly one or two others).

My preference here would then be to do something like this:

<div data-comment-abc123="This is a general comment that does not affect the look of the page"></div>

or

<h6 data-comment-abc123="This is a general comment that does not affect the look of the page"></h6>

Tested, on one browser and one os, in the current main stream canvas distrib. Your mileage may vary, but hopefully some people find this useful!

[Stef_retired]

Thank you for sharing this,  @a_p_g_robinson ‌! I've shared this helpful resource with the https://community.canvaslms.com/groups/designers?sr=search&searchId=8ddb4df4-df48-42a4-ae5f-f01edb0e...‌ group, as those folks are the ones most likely to benefit from commenting in the HTML Editor. If you're not yet a member of that group, you can easily join by clicking on the link to the group and selecting Join Group from the Actions menu at the upper right of the page.

[ronmarx]

Hi Alex,

What an amazing post, thank you!

Your comments about an empty <div> section made me cool to the idea too, and the way you differentiated this issue into its component parts was really excellent. I wasn't able to do that in my previous posts, and as a result, came across as slightly mean to one of our colleagues. (That's the advocate in me, I guess, wanting change while those changes are still relevant. In the here and now, rather than the we'll see and later.)

BTW, is the <br> tag replaced to <p> </p> because of UDL/WCAG/ADA guidelines, do you know? I'm trying to understand the reasoning behind the Canvas sanitizing engine—they implemented for a reason, n'est pas?

Finally, I really hope those Canvas engineers and product managers responsible for white-listing decisions are reading these threads. From the beginning of my Canvas course development, even before I knew the basics, I saw this missing feature as critical. Just as teachers should make learning fun, driven by curiosity and inquisitiveness, so too should Instructure make designing in Canvas fun and compelling by removing the tedious tasks that could be easily automated. Selecting multiple objects for manipulation, nesting modules, grouping components, are all Ideas I've posted in CC, and all apparently have died on the vine (not receiving requisite number of votes).

To Biray and the other sysops here, is there other news on these development themes that I've missed?

Thanks again, Alex. Excellent post!

[a_p_g_robinson]

>BTW, is the <br> tag replaced to <p> </p> because of UDL/WCAG/ADA guidelines, do you know? I'm trying to understand the reasoning behind the Canvas sanitizing engine—they implemented for a reason, n'est pas?

Not sure if it came specifically from the accessibility guidelines, but possibly. Certainly in semantic HTML <br> is supposed to be restricted to only two usage cases - lines in an address and lines in a poem. The argument is that in every other case a newline means that you are beginning a new semantic object and should therefore use one of the other tags, such as p or a list or so on. That would certainly also feed in to screen-reader implementation I'd have thought, hence an accessibility argument too.

>Finally, I really hope those Canvas engineers and product managers responsible for white-listing decisions are reading these threads. From the beginning of my Canvas course development, even before I knew the basics, I saw this missing feature as critical.

I see why they did it - you can use comment tags to hide a javascript in the page. Still it's nice to have an alternative.