MarkBind / markbind

MarkBind is a tool for generating content-heavy websites from source files in Markdown format
https://markbind.org/
MIT License
135 stars 124 forks source link

Add a toasts component #1960

Open ang-zeyu opened 2 years ago

ang-zeyu commented 2 years ago

Please confirm that you have searched existing issues in the repo

Yes, I have searched the existing issues

Any related issues?

No response

What is the area that this feature belongs to?

Other

Is your feature request related to a problem? Please describe.

One use case discussed in #1560 is for supporting an alternative to a sticky announcement bar.

But it can also be useful for highlighting some page-wide information / warnings.

Describe the solution you'd like

Integrate an external alerts library, e.g. https://alertifyjs.com/notifier.html into a MarkBind component.

<toast>
...
</toast>

Some considerations:

Describe alternatives you've considered

No response

Additional context

No response

lhw-1 commented 1 year ago

Update on the issue:

I have opened a Pull Request #2117 some time ago that should have closed this issue. However, the PR is currently still at the draft stage because I am facing an error that I cannot seem to find a straightforward solution to. This update is (1) for documentation purposes, and (2) a call for feedback on how to tackle this issue :sweat_smile:

I have confirmed that with the current implementation using alertifyjs as suggested by the original issue, most of the features requested by the original issue are working as intended (more details can be found in the description for #2117). alertifyjs is ideal for our purposes as it allows some level of flexibility with custom css, and is a relatively small npm package.

The main issue I was facing was that two toasts are created upon serving a new MarkBind page. Meaning, if a toast component is declared in a page, then it will create two toasts to be displayed on the top-right of the page, like so:

image

But this seems to only occur for the first toast component of any page, e.g. if I have 2 toasts on a page, only the first will be duplicated, resulting in 3 toasts; if I have 3 toasts on a page, it will result in 4 toasts, and so on. After some investigations and discussions (thanks @jovyntls!), we managed to track down the likely culprit to alertifyjs itself - importing any alertifyjs function causes the DOM to be loaded twice, resulting in duplication of the toasts on the DOM, thereby causing mismatches in DOM during the hydration process and eventually resulting in a hydration issue. For the past few weeks, I have tried some of the methods suggested on the Internet like this one and this one, but to no avail.

The first (and the preferrable) alternative would be to consider using another package. If alertifyjs is causing issues with Vue, then we simply need to use a package that has already (seemingly) addressed this issue, such as vue-alertify or even vue-toast-notification. However, the reason I was not keen on doing this was concern with long-term maintenance - e.g. vue-alertify is stated to be for Vue 2.x, which means that we are introducing yet another possible breaking change in the future if we were to migrate to Vue 3.x, and would need to have another discussion on changing packages. vue-toast-notification is a possibility as well and apparently supports both Vue 2.x and Vue 3.x, but the required node version is Node 18 and above (we are still at Node 14 and, at the time of writing, are considering migration to Node 16).

The second alternative is to implement a toasts component within MarkBind from scratch (or perhaps using other libraries that provide more basic functionalities), but I am unsure of how complex this could end up being. At the very least, I can think of using base HTML / CSS / JS to have a CSS that appears with window.onload in a specified position, but thoughts on possible incompatibility of this approach with Vue (or lack of) would nevertheless be appreciated!

At the moment, I am still planning to look at other alternatives to alertifyjs, but I am posting this update to check if anyone has an idea on either how to resolve the issue, or if they have an opinion on which alternative to pursue (e.g. if anyone has another idea on how to implement our own toasts component in MarkBind).

lhw-1 commented 1 year ago

Update on the issue:

After a discussion with @damithc, we have decided to put this issue on hold for now.

In terms of the current use case, the sticky announcement bar (example: CS2103T AY20/21 Website) is sufficient to show a site-wide warning, and a better suggestion would be to create a separate component (can be named something like announcement) that displays a dismissable, customizable sticky bar above / below the navbar. If we go for this approach, then we would not necessarily need a toast component, since the only use case (that we can think of) is to be able to support general conversions from other tools that allow a toast component (e.g. bootstrap).

We will lower the priority and put the issue on hold, unless we encounter a strong enough use case that necessitates us to implement a toast component.