I194 footnotes

[alexdryden]

This is the solution IOPN has been developing to address #194. It was derived from this plugin. The upstream source uses a Wikipedia style footnotes system where multiple in-text flags can point to a single footer notation (demo). We weren't going to use that feature, so I removed the UI elements that facilitated it and refactored out the logic that was strictly devoted to managing that feature.

However, it could still be refactored further. For example, the data object used in plugin.js here originally contained an associative array that counted occurrences of in-text flags per footer notation, in addition to the order of the notations . Now the data object just only contains the order of notes as an array, and would probably make more sense as a stand-alone array. Hopefully that background makes it a bit more readable, but I wanted to get the ball rolling on this issue while there was momentum.

[eloyer]

Hi @alexdryden , thanks so much for putting this together. On review, I think this would be a great addition to Scalar if we can work out a few details. Here are the major questions I have:

• Have you tested this system with the Editorial Workflow? This is the biggest potential hurdle I see, especially with the “track changes” feature that requires the user to accept or reject changes before making edits. Would need to test both that the additional markup is handled well by the changes algorithm and that the plug-in can be prevented from making updates to the text until outstanding changes have been accepted or rejected.
• How have you been handling the need for anchor offsets on the “return to text” links? This is something that’s been an issue for us with anchor links in general; the target ends up getting hidden by the Scalar header bar. Sometimes we manually tweak the placement of the anchors to get around this, but that wouldn’t work in this case.

I've got some other notes, but most are cosmetic -- let me know what you think about the questions above.

[alexdryden]

Great to hear @eloyer. On the first issue, very good question. I haven't done any testing with the Editorial Workflow yet. There is another issue I have had on my plate to test with the Editorial Workflow, and I have some time free tomorrow, so I'll let you know what I find. If I'm understating you, the testing steps would look something like this:

1. Test author adding footnotes before entering editorial process
   Enter editorial phase and send to editor
2. Test editor adding footnote
3. Test editor editing existing footnote
4. Test editor moving a footnote
5. Test editor deleting a footnote
   Finish edit phase and return to author
6. Test trying to use the footnote before all changes are either accepted or rejected
7. Test author accepting and rejecting those four kinds of editorial intervention

Is that right?

For the second issue, there are two complimentary ways I have been approaching it. The first is to use scroll-margin-top to prevent the target text from getting hidden, which looks something like

a[rel=footnote] {
  scroll-margin-top: 10em;
}

This seems to work well and I think it would do as a minimum viable solution. 10 may be a bit much because we have an additional branding header that adds space.

The other thing I've been playing with is using an animation to highlight the footnote/in-text marker so it is easier to find the correct note at the bottom of the page and then to find where you left off when you return to the text. I'm pretty sure I also borrowed this from a demo of the upstream footnote plugin, but it reminds me of the google feature that highlights the answer to the question you searched for when visiting the page with the answer. This is what I have right now:

[data-footnote-id]:target, [rel="footnote"]:target {
        animation: hilite-background 5s;
        moz-animation: hilite-background 5s;
        ms-animation: hilite-background 5s;
        o-animation: hilite-background 5s;
        webkit-animation: hilite-background 5s;
    }
    @-webkit-keyframes hilite-background {
        0%   { background-color: transparent; }
        30%  { background-color: #fbff0f; }
        100% { background-color: transparent; }
    }
    @-moz-keyframes hilite-background {
        0%   { background-color: transparent; }
        30%  { background-color: #fbff0f; }
        100% { background-color: transparent; }
    }
    @-ms-keyframes hilite-background {
        0%   { background-color: transparent; }
        30%  { background-color: #fbff0f; }
        100% { background-color: transparent; }
    }
    @-o-keyframes hilite-background {
        0%   { background-color: transparent; }
        30%  { background-color: #fbff0f; }
        100% { background-color: transparent; }
    }
    @keyframes hilite-background {
        0%   { background-color: transparent; }
        30%  { background-color: #fbff0f; }
        100% { background-color: transparent; }
    }

It would be nice if it would highlight a line of the text in the body immediately before the footnote, but I've not come up with a good way to implement that. The example I have to demo this is behind our campus firewall, but I can put something together in our sandbox to share publicly while I'm testing tomorrow.

Thanks for your willingness to engage with this pr.

[eloyer]

Yes, that should cover it re: Editorial Workflow. Would be very interested to see what's possible with highlighting, and the scroll-margin-top sounds like a good approach. Thanks!

[alexdryden]

Your instincts were spot on abut the Editorial Workflow. I tried doing all the tests in a single page, but it was pretty badly broken once the edits got back to the author for review (footnote section numbering was wrong and even after clicking "accept all" I couldn't move it to the next editorial phase), so I'll have to tease out each test in a separate page.

One of the major issues I know I'll have to tackle is how to handle approval for changes that are decoupled by the track changes feature (like deleting a note--you could accept the deletion of the in-text anchor but reject the deletion of the footnote below). I think I'll need a better understanding of how the editorial system is implemented before I can devise a solution. Can you point me to that component and/or any documentation for it?

[eloyer]

OK, yes it sounds like it'll need some careful attention — the diff handling has been notoriously difficult to troubleshoot in the past. The CKEditor plugin that handles EW functions is here and fairly well documented, feel free to send along any questions.

[alexdryden]

Awesome, thanks Erik. I'll start digging through the EW plugin over the next two weeks and being to map out a plan.

[alexdryden]

Just a follow up to update on progress, and to prevent this pr from going stale. Integrating with the editorial workflow did prove difficult, particularly with the diff. We have a version that is working now and have some additional beta testing planned with a class that will be using the footnote feature next semester. So, hopefully we'll have an updated pr to review later in the spring of 2023.

[eloyer]

Thanks for the update, looking forward to the results of your testing!

[alexdryden]

Hello again! The feature has been pretty well received among our group of users and, importantly, I think I've come up with a plan to make it more compatible with the editorial interface if you are still interested in the pr. The new approach is based on the way Wordpress uses shortcodes to implement features, including how Pressbooks implements their footnote/endnote solution.

So, the current workflow in this widget involves putting the marker- and note-ordering logic within the scope of the WYSIWYG, which creates a lot of opportunities for bugs to crop up in the editorial workflow, especially if notes are moved, deleted or otherwise renumbered. Instead, for the Wordpress shortcode inspired approach, the widget would simply insert a <span class='footnote'>, or similar, around the footnote content at the place in the body of the text where the footnote marker will appear. Inside the WYSIWYG, the footnote text would be:

Lorem ipsum dolor sit amet, consectetur adipiscing elit.<span class="footnote">the footnote text goes here</span> Nullam tellus ipsum, cursus nec quam eu, ultrices condimentum odio.

with some kind of visual indicators around the footnote text. And then the placement of the markers and assembly of the footnote section would happen through DOM manipulation when the page is being built for readers. With this approach, from the perspective of the diff algorithm, the footnotes don't add any additional complexity because within the WYSIWYG they don't appear or behave differently from any other text.

What do you think? Does this sounds like a reasonable approach?

[craigdietrich]

Hi @alexdryden

This approach looks good to me. I'm newer to this thread so don't know for sure, but it seems this new solution allows footnote text to show up in the WYSIWYG for editing? In which case editors and authors can work on footnote texts right there in the editor along with the main content body? This sounds exciting!

What would be next steps?

[alexdryden]

@craigdietrich great! Yeah, you have it right in terms of how authors and editors could see and edit footnote text in the WYSIWYG. For next steps, I'll go ahead and get started on the new approach and update the pull request.

[freedmancenter]

@alexdryden @craigdietrich @eloyer Hello Guys, My be this question do not belong here but I did not find any forms or blog. I am new to scalar and started my new job few months ago at Case western University. We are using sclar installed on our server. How can I check which version we are using and what is best way to upgrade to current version.

https://scalar.case.edu/archives/index