Feedback on AnchorLinkPlugin

Enjoy!

-- Peter Thoeny - 2020-10-24

I think this is very convenient whenever you want to point others to a specific section in a long TWiki-based documentation. You can easily get it wrong when you copy the URL from the browser window (what if you started reading another section?). The usual workaround to send out the topic url "and then go to section Next Steps" is unnecessarily tedious (and sometimes error-prone) for the reader.

Maybe one could even get away without the extra configure settings... I wouldn't see any problem if simply all headings get the icon.

A possible enhancement: A new TWiki variable like %ANCHORLINK{"this place"}% could create a <a name="this place"> and the corresponding icon in arbitrary places which are not headings. Examples are a table or an image, or a tile in a dashboard. All these have "captions" but none of them translates to H elements.

-- Harald Jörg - 2020-10-24

Thanks Harald for the feedback!

On configure, the default is h2...h6, which is likely a default most people do not touch.

Yes, a new %ANCHORLINK{}% would be useful. I already had the idea in the shower h1 is at the top, so does not need an anchor.

Maybe better to not show any text to the user? But make the anchor link icon visible on hover of the parent element (table cell, list item, paragraph, …) where %ANCHORLINK{some_id}% is located?

-- Peter Thoeny - 2020-10-24

Yes, that's what I had in mind. As a TWiki variable, you would write e.g. %TABLE{ caption="%ANCHORLINK{table_1}%Table 1" }% to get the on-hover icon to the right place. Traditionally, you could write #table_1 for an in-page anchors before the table, but it would be hard to assign an element for the hovering icon.

-- Harald Jörg - 2020-10-25

I copied above conversation from an e-mail thread.

-- Peter Thoeny - 2020-10-25

In regards to "make the anchor link icon visible on hover of the parent element", I inspected the DOM. It mostly can work, except for paragraphs. TWiki renders paragraphs as follows:

<div class="patternTopic">
<h1><a name="#H1_Heading"> H1 Heading </h1>
<p></p>
Test paragraph 1.
<p></p>
Test paragraph 2.
<p></p>
Test paragraph 3.
<p></p>
<h2><a name="H2_Heading"></a> H2 Heading </h2>
<p></p>
Test paragraph H2 1.
<p></p>
Test paragraph H2 2.
<p></p>
</div>

That means, a top level paragraph's parent is a div that captures the whole topic content (excluding header and footer). For example, "Test paragraph H2 1" 's parent is <div class="patternTopic">. E.g. we have to find another solution to add a hover over paragraphs, because this is not usable for the ANCHORLINK use case.

What would work is if the TWiki rendering engine generates this HTML for paragraphs:

<div class="patternTopic">
<h1><a name="#H1_Heading"> H1 Heading </h1>
<p>
Test paragraph 1.
</p><p>
Test paragraph 2.
</p><p>
Test paragraph 3.
</p>
<h2><a name="H2_Heading"></a> H2 Heading </h2>
<p>
Test paragraph H2 1.
</p><p>
Test paragraph H2 2.
</p>
</div>

-- Peter Thoeny - 2020-10-25

I can't claim that I've thought this through

I sort of expected that it wouldn't be easy to find a good element for the :hover style attribute - but also, using ANCHORLINK on plain paragraphs doesn't seem to be necessary. My use cases for ANCHORLINK were situations where it is difficult to add an anchor with "traditional" TWiki methods like #anchor on a line of its own.

For anchors on headings, which are just there "for free", the value of the icon is in providing the exact link: No need to scroll up to the TOC (if there is one) or to view the source to obtain the anchor's value. ANCHORLINK, on the other hand, needs to be explicitly inserted by editing the source, so I'm supposed to know the anchor value I've chosen. I still need to append it to the topic URL, though, but saving the page (which redirects to view), scrolling down to the paragraph where I added the ANCHORLINK, finding the :hover element and then copying the link location is also several steps more than what's required to link to a heading.

For an ANCHORLINK to appear in flow text, there might be alternatives to activate them, like wrapping the first word in a span element (or more general: The word following ANCHORLINK). I don't dare to guess what happens when a series of paragraphs is interspersed with lists, tables or images - you'd need to close the paragraph element before any of these if you change the rendering, and open a new paragraph before next text paragraph. Nested elements are extremely difficult to handle with :hover because their areas overlap.

-- Harald Jörg - 2020-10-25

I implemented the ANCHORLINK variable. It currently works anywhere outside a top level paragraph, such as in bullet lists, tables, block quotes, divs etc. With DOM traversal you can't even get at the paragraph text between <p></p> and <p></p>.

The ANCHORLINK works also if placed deep in the DOM, such as with in a span located in a table cell, located in a bullet. The plugin recursively finds the first parent that is a TR, TABLE, LI, or heading tag: parentTag.match(/^(TR|TABLE|LI|H[1-6])$/)

-- Peter Thoeny - 2020-12-21