Add append, prepend and replace operations

[marcoroth]

Type of PR

Enhancement

Description

Adds three new operation to CableReady. After using jQuery for many years and never remembering the spelling of insertAdjacentHTML and the option it takes I thought it would make sense to introduce the append, prepend and replace operations.

Why should this be added

Coming from jQuery or even native JS the terms and methods append, prepend and replace are easier to remember and could be more familiar in my opinion.

Also see:

• jQuery append() and ParentNode.append()
• jQuery prepend() and ParentNode.prepend()
• jQuery replaceWith() and ChildNode.replaceWith()

Checklist

• My code follows the style guidelines of this project
• Checks (StandardRB & Prettier-Standard) are passing
• This is not a documentation update

[marcoroth]

I thought about calling it just replace, but since we always use the same name as the JavaScript method I kept it replaceWith.

[hopsoft]

Agree with keeping the same names provided by the DOM. I'm good to add these methods given that they all accept a DOMString as well as a Node.

[hopsoft]

This should work by passing a DOMString, so there isn't a requirement to construct a Node.

[marcoroth]

@hopsoft I tried that. But it always just added the HTML as actual text (that's the difference to insertAdjacentHTML).
So you can't just pass a HTML String, unless you can somehow convert a regular String to a DOMString.

[hopsoft]

In that case I propose that we use template rather than div, similar to what we're doing on morph.

[hopsoft]

The next question is whether or not there's a material difference in the following methods.

• append, prepend vs insertAdjacentHTML
• replaceWith vs outerHTML

I'm mostly curious... as I think this PR is a good addition for developer happiness.

[leastbad]

lol... there's an echo in here

[marcoroth]

There isn't really a difference from a user perspective other than the method names.

I first wanted to implement these operations with method aliasing, but then I realized that the DOM even offers such methods. Since we always used the DOM method corresponding to the CableReady operation I thought I will do the same here.

Also: If we would go the alias way, we have the problem with the events. If you alias it in the backend then the event in the frontend wouldn't match anymore and if you alias it in the frontend then both the method and the alias method events would get triggered.

That's why I went with the DOM methods in this implementation in the first place.

Regarding the differences: This answer here summarized it pretty good in my opinion: https://stackoverflow.com/a/16127049/5052329

Since we always just have a HTML string we need first to construct a Node in order to use append, prepend and replaceWith methods. This is probably also the reason why we just have insertAdjacentHTML, innerHTML and outerHTML now, because they just take a HTML String and convert it to a Node on their own.

But if you have the feeling that we should go the "Alias-Way" we can swap out the JS implementation. So we should just call insertAdjacentHTML('beforebegin', html) in the frontend append implementation. But I don't know if this is even more confusing tbh.

[hopsoft]

Ah ok. Does that mean we could the simplify the implementation to something like this then?

  append: detail => {
    activeElement = document.activeElement
    const { element, html, focusSelector } = detail
    dispatch(element, 'cable-ready:before-append', detail)
    element.insertAdjacentHTML('beforeend', html)
    assignFocus(focusSelector)
    dispatch(element, 'cable-ready:after-append', detail)
},

// etc...

[hopsoft]

Also, for the record.

I realized that the DOM offers such methods [append, prepend, replaceWith]

👆🏻 This is the primary reason why I think adding these methods is a good idea.

[marcoroth]

Ah ok. Does that mean we could the simplify the implementation to something like this then?

Exactly! If you think this approach is better I'm happy to rewrite it.

[hopsoft]

There doesn't appear to be a material difference, so my vote is to converge on a single internal implementation by effectively delegating to the existing methods.

[leastbad]

How would this delegation work?

I am hoping to keep things pretty obvious.

[hopsoft]

#90 (comment)