Thoughts on a project to practice the module dev process

[gornycreative]

So I have been digging more deeply into processwire working under the hood and I would like to try building a module.

So there are two defunct modules I'd like to synthesize - or at least put the pieces together to make work for some of the more serious writing sites I've worked on.

In WordPress, there was a plugin called Side Matter: https://wordpress.org/plugins/side-matter/

This plugin allowed a person to use a shortcode to indicate a reference [ref] - the original plugin would:

• process the shortcode contents (the note)
• look for nested [ref] shortcodes (and ignore them),
• process the shortcodes found in the note (if any),
• assign a note number or letter (depending on the type of numbering you wanted to use)
• replace the original shortcode with a linked superscript to an ref-1 anchor (optional)
• add the identifier and reference content to an aggregate div stack
• feed the content of that aggregate div stack into a second [ref_list] shortcode

There was then a jquery script that would look at a stated 'parent' container and normally you would have an aside widget where you would put the [ref_list] shortcode or something like that. What you'd end up with was a height matched set of side notes next to the main article content. If you were crafty and used responsive frameworks like UIKit, the jquery code made a point of making sure two notes never overlapped and never were higher on the page that the original article reference. So in the case of having a responsive layout where the aside slipped beneath the article, the sidenotes would convert very conveniently into footnotes.

I was looking at this module - which has been orphaned at WP for years, and I was also looking at the MarkupShortcodes by @Nico Knoll to manage the shortcode processing - at least as a starting point:

https://github.com/nicoknoll/MarkupShortcodes

Both of these codebases are pretty old, has this sortof plugin already been tried? Are there more recent resources/examples I should use to approach this properly? I think both of these plugins were released in PHP5 - I've been trying to get caught up on the architectural changes of PHP7 (it has been a while).

Any thoughts or advice more specific to the kind of project I am looking at would be appreciated - would it be better to complete start from scratch using a more modern template?

Thanks!

[MoritzLost]

I see three different approaches for this:

1. You can already build footnotes using superscript, anchors and links inside the CK Editor without any additional programming or plugins. You need to write the footnotes manually (possibly in a seperate CK Editor field if you want to output them in a different place than the main content), create anchors on them, and then link to those anchors from within your text. For the link inside the text you can just use a numbers in superscript. This becomes very tedious to maintain though, especially if you have lots of footnotes. So this only works well for a couple of footnotes here and there.
2. You could do this with Hanna Code, which is very similar to WordPress's shortcodes, only you create shortcuts through the GUI instead of code. One [[ref]] shortcode that gets replaced with a link to the footnotes and collects all footnotes in a global variable, and another [[footnotes]] shortcode that outputs the collected list of footnotes. You can get very fancy with additional parameters for different lists of footnotes etc.
3. Write your own Textformatter module that works in a similar way to the shortcode approach mentioned above. Might be more flexible in the long run, though it's definitely more work than using Hanna Code. You can look at the source code of Hanna Code which you can adapt to your specific use-case. If you want a more current example of a textformatter, take a look at my TextformatterPageTitleLinks module which is written for PHP 7 exclusively.

Quote

There was then a jquery script that would look at a stated 'parent' container and normally you would have an aside widget where you would put the [ref_list] shortcode or something like that. What you'd end up with was a height matched set of side notes next to the main article content. If you were crafty and used responsive frameworks like UIKit, the jquery code made a point of making sure two notes never overlapped and never were higher on the page that the original article reference. So in the case of having a responsive layout where the aside slipped beneath the article, the sidenotes would convert very conveniently into footnotes.

Not completely sure what the script does, but this is something that I would never do in a JavaScript. You can probably do the same thing or something better in CSS with flex or grid.

[gornycreative]

Thanks for those thoughts. I did consider using Hanna Code - I think for collecting the information that is a solid recommendation on its own. If all I was interested in was collecting footnotes, that would be ideal.

The secret sauce of the plugin was what Jquery was used for - and while I agree that I'd rather not rely on javascript for the functionality, I don't know if the same effects could be achieved with pure CSS, but I will look into it.

What the vanilla jquery placement function does is wicked simple:

function placeNotes() {
	for (n = 1, refCount = $('a.side-matter-ref').length; n <= refCount; n++) { // Iterate through notes and position each
		var ref = '#ref-' + n; // Reference anchor
		var note = '#note-' + n; // Sidenote
		var refPosition = $(ref).position().top; // Position of reference anchor
		var notePosition = $(note).position().top; // Position of sidenote
		var noteOffset = refPosition - notePosition - noteAdjust; // Get current offset between reference and note, minus noteAdjust
		var finalOffset = (noteOffset < 0) ? 0 : noteOffset; // If offset is negative, set to 0 (prevents layout problems)
		$(note).css('marginTop', finalOffset); // Position note
	}
}

noteAdjust is a tuning parameter you set on the admin side that allows for you to adjust the height in case there is a difference between your article parent and your notes aside - but in my implementation I replaced this because it was simple enough to calculate so long as you could name the containers where both the article and the aside would sit.

I also had to make some adjustments to prevent notes from stacking on each other by keeping tracks of an aggregate lastNoteBottom that made sure the note top would not blindly go next to the two refs on two consecutive lines and overlap each other - but I think perhaps setting the note to clear would resolve that issue.

I'll take a look at your textformatter plugin.

Thanks for the feedback!