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

a_p_g_robinson
Community Participant

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!

Labels (2)