search

johnjung / bmrcportal

GNU General Public License v3.0
1 stars 1 forks source link

documentation: how does the curated topic feature on the home page work? #145

Closed MomoMoses closed 2 years ago

MomoMoses commented 2 years ago

We have documented that it changes weekly and "cycles through" all the live pages. Can you give more detail about how that cycle is performed? This is so that the inner workings of the portal are explained and understood, especially for people who don't or can't read the code itself.

johnjung commented 2 years ago

I added a more complete explanation of how the curated topic feature is calculated to the Wagtail admin for the PortalHomePage in https://github.com/uchicago-library/bmrc/commit/6b667669b4949e8da997c6b47345fd281f8fa152. This is now live on the server.

MomoMoses commented 2 years ago

Um, OK. I see that. However clear this is to programmers, it could use a little tweaking for non-programmers. For example, how do we know what order they topics appear in the database (which governs how they are arranged, which, I presume, governs when they are displayed)? And how does that order interact (if it does) with the calculation of number of weeks since January 1, 1970 (which is kind of a peculiar place to start!)? "Then it calculates that week number modulo the number of live curated topic pages," i.e. the remainder after dividing week number by number of live pages. (Is this clarification in fact correct?) That number (the remainder-right?) is the zero-based index of the curated topic page to display. OK, so we have to have zero-based index because the remainder could potentially be zero, correct?

I'm unclear on how this informs me about the order of the topics to be displayed. 🤷

johnjung commented 2 years ago

Please feel free to supply the exact text you'd like to use. Here is an edit I suggest, based on your comment:

The featured curated topic automatically changes every week, cycling through all live CuratedTopicPages. Only currently live curated topics are considered for this display. Curated topics are arranged in the order in which they appear in the database- this is mostly likely the order in which they were created. To determine the curated topic that should appear, the system counts the number of weeks since January 1, 1970. Then it finds the remainder of the week number divided by the number of live curated topic pages. That number is the index of the curated topic page to display. Set the image that appears for the currently selected curated topic on that specific CuratedTopicPage.

January 1, 1970 is a common start date in code. It's a way to say "a date in the past that has no significance other than the fact that it's known to be in the past."

MomoMoses commented 2 years ago

The featured curated topic automatically changes every week, cycling through all live CuratedTopicPages. Curated topics are arranged in the order in which they appear in the database--most likely the order in which they were created. To determine the curated topic that should appear, the system counts the number of weeks since January 1, 1970. Then the number of weeks is divided by the number of live curated topic pages. The remainder (including 0 for dividing evenly) is the index of the curated topic page to display. Go to the individual CuratedTopicPage to set the image that appears with the Topic in the display.

johnjung commented 2 years ago

This is now fixed in https://github.com/uchicago-library/bmrc/commit/c5c0ffb28be9c11020623c845647e9ce9351b86c and live on the server. Please take a look to be sure everything is ok, and if so, please close out this issue. Thanks!

MomoMoses commented 2 years ago

Looks fine. :)