Alert mechanism

[coke]

It would be nice to have an alert popup available on the docs site for things like:

• Hey, we added an ebook
• Updated docs to include 2024.04 release
• 6.e dropped!

etc. Be nice if

• We could support at least one message at a time. We do NOT need to support multiples but it if it's easy...
• Once a user has hidden a message it goes away.
• We don't need an archive of messages.
• OK if we need to do a deploy to get a new message (don't need a way for admins to create it dynamically through the site)

[finanalyst]

Sounds interesting. Before thinking about how to do this, what would be the process? Something like:

• A moderator adds a message to the system. - - The message is incorporated into next build (this happens every 2hours?)
• A user opens website.
• Gets new message. Or messages?
• Could offer option to prevent popups
• ID/datestamp of message can be stored locally
• Only messages after last stored are popped.

What about accumulated messages?

On Tue, 7 May 2024, 16:43 Will Coleda, @.***> wrote:

It would be nice to have an alert popup available on the docs site for things like:

• Hey, we added an ebook
• Updated docs to include 2024.04 release
• 6.e dropped!

etc. Be nice if

• We could support at least one message at a time. We do NOT need to support multiples but it if it's easy...
• Once a user has hidden a message it goes away.
• We don't need an archive of messages.
• OK if we need to do a deploy to get a new message (don't need a way for admins to create it dynamically through the site)

— Reply to this email directly, view it on GitHub https://github.com/Raku/doc-website/issues/372, or unsubscribe https://github.com/notifications/unsubscribe-auth/AACYZHFV22XM77XGQUWPABTZBDZDVAVCNFSM6AAAAABHLIQ6XWVHI2DSMVQWIX3LMV43ASLTON2WKOZSGI4DGNRYG4YDEMY . You are receiving this because you are subscribed to this thread.Message ID: @.***>

[patrickbkr]

I like the idea.

What about accumulated messages?

I say lets display only the last message. If we want to make sure people have a chance to see older ones, we could have an "Announcements" page where the full history can be seen.

[finanalyst]

@coke @patrickbkr An announcements page is a good idea. So here's a suggested design:

• we create a Rakudoc page for announcements, and we have it included in the Introduction section, so it is available as a normal page (this is trivial)
• the format of the page would need to be strict to make parsing easier, perhaps:
  • =item B<date in yyyy-mm-dd>Announcement
  • choiice of format so no one confuses month and day (as European and US forms are inverted)
  • also easier sorting
• we add a local storage object,
  • contains the date of the last announcement shown to a user
  • a boolean for suppressing popups
• we add a function to the main js that has a DocumentLoaded listener
  • The js function contains the last announcement's HTML
  • The js is generated at Build time, so the announcement page has been rendered and the HTML is available.
  • the function gets the local storage object, checks the date of the last announcement,
  • checks if the popup is allowed
  • pops the announcement if the last two are true.
  • stores the date of the announcement in the local storage.
  • so, when popup is dismissed, it will not appear again until a new announcement is added.
• we add a button to the More dropdown that cancels/allows the popup.

So, all that is needed for the moderator is to change the Announcements page by adding an item to the top of the page.

Just some UX questions

• Bulma (the CSS framework used here) has a modal window, which we used. Examples can be found here
• the Bulma variant is the easiest is implement, and Bulma will ensure it is responsive and trans-browser. But it seems a bit too intrusive for my preferences.
• there is a js alert function, but I do not know how this is consistent across browsers/OS
• we could add a div to the navigation bar with a cancel button (this would be time consuming to get right)

[patrickbkr]

Sounds good.

[coke]

The bulma model is going to be a better experience than alert(), IME.

[finanalyst]

@coke @dontlaugh @lizmat A PRs to address this issue. It will be in the docs-dev branch, so the results will be visible on https://docs-dev.raku.org.

An issue to be resolved if the PR meets the requirements of the ask is where to put the 'announcements.rakudoc' page. For the PR, it is located in Website/structure-sources and so is local to this repo. However, this has the disadvantage that it will not be included in the Introduction page (tab). [This is a limitation of Collection's design, which I plan to remove once I start working on the replacement of Collection after RakuAST-RakuDoc is complete] Since Announcements is not listed, it cant be found onsite (of course we could include a link to it in eg About)

My preference would be to have announcements.rakudoc as a file in the Raku/docs repository immediately inside doc/.

[finanalyst]

@coke a small announcements.rakudoc file needs to be created. Is the test file OK?

[finanalyst]

@coke @dontlaugh @lizmat @patrickbkr PR now working on docs-dev deployment eg introduction. First time site opens, you get latest message. Then refresh page, and the modal pane will not fire! If you want to see all announcements (assuming you dont click on the link in the modal pane), this is the url. Suppress toggle is at navigation_bar->More->announcements If you want to test with fresh window, then on Firefox (I dont know the sequence for other browsers), goto developers window/tab (on Ubuntu its F12), then 'storage', then 'local storage', then the element labeled 'docs-dev.raku.org', then delete the item labelled 'announcementState'. See posts above about outstanding issues.

[finanalyst]

PR merged to main without an announcements.rakudoc page. I'll raise a PR on Raku/doc with a short source. Once that is merged into main, the announcements plugin will serve the topmost announcement after the next build here (about 2 hours later).

[finanalyst]

closing as completed