[Feature Request] Home screen (easy access to entries you're reading and recently added)

[jaredlt]

Background

I really like plex.tv. I use it heavily for TV and Movies and think they've nailed the user experience. I discovered Mango as I was looking for a Plex for Comics/Manga. One of the many things I like about Plex is their home screen:

They have:

• A Continue watching section that appears at the top when you are part way through an episode. When you have no episodes part way through this section disappears.
• An On deck section which shows you the next episode of any shows you are actively watching (ie. if you just watched Season 6 Episode 8 of The Office, it will show you Episode 9)
• A Recently added section which displays shows that have recently been added to the server. If multiple episodes of a show are recently added together it groups them and shows the episode count in the badge

Both Continue watching and On deck are fantastic for jumping back in where you left off, without having to remember where you were or what you were last watching. And Recently added is great for discoverability, especially for other users of the server.

Proposal

I would like to propose introducing this into Mango. Of course, this needs to be something that you think would benefit your vision for Mango, I don't want to step on your toes or take things in a direction you don't like :)

How would it work?

These are just my suggestions so far. All of it will need your feedback.

• Introduce new page Home at root /
• Keep existing Library page but move it to eg /library
• Add Library link to nav
• Home page would have the Plex features:
  • Continue reading - works exactly like Plex. Only shows if you are part way through an entry ie. progress > 0 and < 1
  • On deck - shows you the next entry if it exists. If in the future you add the next entry it will show here once the scan occurs. Ordered by last read time. I don't think the name 'On deck' is particularly clear but struggling to think of anything better. The obvious name is 'Continue reading' but that is taken by the section above and I think it's better suited there as there is more immediacy to an entry you are part way through reading. Once you understand the concept of On deck it becomes a non-issue.
  • Recently added - shows entries that have been recently added, ordered by most recent first

I have created a proof of concept for some of this:

Some notes:

• as well as introducing the Continue reading and On deck concepts I also played with the CSS to try and get it more 'Plex' like. This is obviously to be discussed, but I wanted to see what it could look like. I do think they made some good decisions around making the cover the centrepiece (no box joining the text below each), making the text smaller and without horizontal padding (allows longer titles to show more text). There is the maintenance burden to consider of customising the defaults from UI Kit. Something to discuss anyway. If the maintenance seems too high perhaps I could explore an alternative theme Eg. Light / Dark / Plex and this theme would hold all the custom stuff. Just thinking out loud.
• I was also playing around with the concept of the progress bar (again from Plex), as an alternative to the % badge (I think probably show one or the other but unsure yet). I would only show this for Entries, not Titles to convey that you are part way through reading that particular entry.
• Was also experimenting with showing pages read / pages in the badge, but just for Entries. I think you're using %s for progress to get around the fact that a single Title could potentially have volume and chapter zips, so you might have Vol 1.cbz, vol 2 ch 1.cbz, vol 2 ch 2.cbz and this would only have 3 entries but finishing the first entry and being 1/3rd through the entries is not a true indicator of progress. I think %s is definitely the best approach for Titles. Can't decide whether I prefer %s or pages for Entries. I guess it doesn't really matter :)

Your thoughts

I have the code in my fork but it is HORRIBLE :) I really wanted to propose this without delving too deep to see if it's a direction you like and if it's something we should explore further together. Let me know what you think.

---

Update: adding todos here for current work plus things we might do later so we don't forget about them

• New Home page
• Continue Reading section
• Store when entry was last read
• Confirm Time object String is stored with UTC offset for clarity
• Consider last read of previous entry for where progress == 1 (ie. next entry last read == nil)
• Order Continue Reading by last read
• Jump to title page
• Store when entry was added to Mango
• Handle existing entries for 'added'
• Recently added section
• Hardcode max entries for Continue Reading (8 or 12)
• Recently added cut off by date or entries?
• Onboarding for new users (home)

Later / other

• Configurable "Continue Reading" settings
• Onboarding for new users (empty library)
• Other possible sections for Home screen (eg. Recently Published, Start Reading, Rediscover, Top Rated)
• Filter Library by Date Added

[hkalexling]

This looks amazing! Thanks for taking the time to write this :D

I am a heavy user of Plex as well, and I agree we need a more refined home page. If you want, I can invite you as a collaborator and create a branch, so we can both work on it and experiment with it.

Regarding the details:

• I like the idea of adding the home tab and moving the original home to /library.
• Perhaps the On Deck section can be renamed to Up Next?
• I agree we should make the title text smaller. In the current version many long titles are truncated and it doesn't look good.
• A Plex theme sounds interesting. Feel free to experiment with it!
• Perhaps we can allow the users to toggle between percentage, read page and progress bar for entries? I agree showing percentage makes more sense for titles.

You proposed a few different new features (all inspired by Plex)

1. The new home tab with the "Continue Watching" and "On Deck (Up Next)" sections
2. Plex theme
3. New progress indicators (read page count and progress bar)

Maybe we should pick one and work on it first? I would vote for 1, but let me know what you think!

[jaredlt]

@hkalexling sounds great!

Agreed, let's focus on 1. I like Up Next too 👍

[jaredlt]

@hkalexling I started documenting the below requirements but now I'm wondering if we need both Continue Reading AND On Deck/Up Next.

Plex's logic displays in progress episodes in On Deck/Up Next too. I guess this may be a reason why Plex named it On Deck instead of Up Next. It represents all the shows you've started watching, including any episodes in progress. I think that makes sense. Continue watching is important for Plex because you can have multiple libraries eg. 1) TV 2) Movies. Movies will never be On Deck so it makes sense to highlight them in Continue Watching, and it would be confusing if this didn't also display TV Shows that are in progress too. If you go into the TV library dashboard of Plex it shows On Deck at the top (it has continue watching much further down and this displays all episodes that are in progress, even if from the same series).

If we just have a single library, could we have a single section called Continue Reading but it actually works like Plex's On Deck? It would show the next entry (or current entry if in progress). I'm leaning towards just one section now but let me know what you think.

---

I'll leave my original requirements below as is for your feedback. Either way we'll need to implement the On Deck functionality and after that it will be easy if we decide want to add the Continue Watching section too.

Continue Watching/Reading

• Display all entries which are 'in progress'

Scenarios

• 0 entries in progress: section should not appear, including not showing the heading
• 1 entry in progress: show entry
• 1 entry for Title A and 1 entry for Title B: show both entries
• 2 entries for Title A: Just show latest entry eg. vol. 2 30% and vol. 4 30% - just show vol. 4 (this follows Plex's logic which I think I agree with. Logically if you are reading a title, you read one entry at a time, in order. Therefore, if you have 2 entries for the same title 'in progress', it implies that you have read up to whatever the latest entry is. The earlier entry may be you just going back and re-reading something). This rule can be generalised to: Only show 1 'in progress' entry per title in Continue Reading and only show the latest entry.
• ORDER BY: 1 entry for Title A last read today and 1 entry for Title B last read yesterday: show Title A entry first, then Title B entry (NB. I believe this will require adding a new section into info.json unless this is stored somewhere I'm unaware of?) Eg.

{
  "comment": "Generated by Mango. DO NOT EDIT!",
  "progress": {
    "admin": {
      "Ghost in the Shell v1 (1995) (Uncensored)": 186,
      "Ghost in the Shell v2 (2010) (Digital) (danke-Empire)": 0
    }
  },
  "last_read": { // new section (need to consider methods to refactor eg. save_progress)
    "admin": {
      "Ghost in the Shell v1 (1995) (Uncensored)": "2020-05-18 12:12:36",
    }
  },
  //...
}

NB. In the future it may be worth exploring consolidating all of the info.json data in the database. This would allow you to add a user_entries table to avoid duplicating usernames in the json. It would also avoid modifying the user's library folder, which some users may not like, and could make some of these new features easier to deal with, especially for large libraries. This would change the source of truth from the file system to the db and there is much more to think about here. Out of scope for this feature :)

On Deck/Up Next

• Display the next entry to be read for each title you have started reading

Definitions

• title started - has at least 1 entry either in progress or completed
• entry started - is either in progress or completed

Scenarios

• 0 titles started: section should not appear, including not showing the heading
• 1 title started with 1.zip completed and no other entries (ie. title 100%): section should not appear, including not showing the heading
• 1 title started with 1.zip in progress and no other entries: show 1.zip (Plex's logic which shows in progress in Up Next too. Probably why they named it On Deck instead of Up Next)
• 1 title started with 1.zip in progress and 2.zip unread: show 1.zip (show current and not next entry if current is in progress)
• 1 title started with 1.zip completed and 2.zip unread: show 2.zip
• 1 title started with 1.zip completed and 2.zip in progress: show 2.zip
• 1 title started with 1.zip completed and 2.zip completed: section should not appear, including not showing the heading
• 1 title started with 1.zip completed and 2.zip completed and 3.zip unread: show 3.zip
• 1 title started with 1.zip completed and 2.zip in progress and 3.zip unread and 4 in progress: show 4.zip
• 1 title started with 1.zip completed and 2.zip unread and 3.zip completed: show 2.zip
• 1 title started with 1.zip completed and 2.zip in progress and 3.zip completed: show 2.zip
• ORDER BY: last read

[hkalexling]

I agree that the two sections can be merged. I think we need multi-library support later (see #13 ), but for now, merging the two makes more sense.

I try to avoid saving things to DB (unless absolutely necessary) due to the following reasons:

1. If we store the title and entry information (progress, display names, cover images, etc.) in DB, for example, how can we refer to a certain title in DB? The only way I can think of is to use the title's path (e.g., library/manga_A ). However, if the title folder is moved or renamed, we won't be able to update the path in DB and the information will be lost. This won't be a problem with the current info.json setup, as the title folder still contains the same JSON file after moving/renaming.
2. Mango is still in early development, and we might need to modify the DB scheme a lot if we are storing everything in DB. A simple JSON file is much more flexible.

It's a good point that users might not want the library folder to be modified. We need to plan carefully.

The rules you listed for displaying the sections are well-thought-out. I think we can go with that. Thanks for your efforts!

[jaredlt]

@hkalexling Proceeding with a single merged section for now 👍

RE: db vs file system - what you say makes perfect sense. And as you say, still in early development. Plex seem to handle moved files really well, by showing in the UI if they're missing and then knowing when they've come back, even if it's not the same file, but provided the naming and file structure is sufficient. I'll maybe have a poke around the Plex database to see if I can understand more how they do it, but yes, that is for much later on :)

I've pushed a new WIP branch up: feature/home. It includes:

• Moved current index to /library, renamed relevant files / routes and added new link to nav
• Created new view home and added new route
• Created new method for Title class get_on_deck_entry(username) - this works and returns an array of Entries but it's not very elegant code :/
• Fixed a typo on 2 of your existing methods load_percetage >> load_percentage

Comments

• I'm sure the new method I've introduced, and even the code in the / route, could be cleaner / simpler / more idiomatic. Would love some feedback from you here.
• Because the main object is an array of Entries, I'm unsure what the best approach is to get the percentage. I tried using as much existing code as possible and calling e.book.load_percentage(username, e) but this always returned 0.0 and also didn't feel very elegant. I found myself wanting to reach for a percentage method within an Entry object eg. in the view (or route) you would be able to just call e.percentage(username). Could I add this method into the Entry class? Didn't feel very DRY to do this though.
• I wonder if we can think about making the username attribute implicit? By this I mean: we know when calling load_progress that it will always be in connection to the logged in user, so it would be good if we could just call e.load_progress in the view without having to pass in the username variable. This isn't super important right now, just thinking out loud. Perhaps we need a separate UserEntry class or something? Maybe this is one of those things that we just ignore for now and revisit if/when things start feeling more painful :)

[hkalexling]

Thanks for the update!

I refactored the get_on_deck_entry method and the code for the home route, and it should be cleaner now.

I tried using as much existing code as possible and calling e.book.load_percentage(username, e) but this always returned 0.0

In the home route method, I tried

percentage = on_deck_entries.map do |e|
    e.book.load_percentage username, e.title
end

and it returns the percentage correctly.

Could I add this method into the Entry class? Didn't feel very DRY to do this though.

If we will be using the method a lot, feel free to add it, but I would suggest naming it Entry.load_percentage for consistency.

so it would be good if we could just call e.load_progress in the view without having to pass in the username variable.

We need the env variable in route methods to know who the logged-in user is. I can't think of a way to do it in the Entry class. Maybe I missed something? Also, could you elaborate a bit on the UserEntry class you mentioned? Why do we need it?

[hkalexling]

Also, the new section is titled "On Deck", but I think you mentioned that the section would be called "Continue Reading" but functions as the "On Deck" sections in Plex? I think "Continue Reading" is easier to understand, and it means pretty much the same thing in our case. Anyway, let me know what you think!

[hkalexling]

I saw your comment about DRY'ing the frontend HTML code, and I absolutely agree. The frontend code is ugly and it's getting harder to maintain. I have been planing to do a complete rewrite using a modern JS framework like React or Vue, but I just couldn't find the time to do it.

[jaredlt]

Much cleaner! Thank you :)

I've added your percentage approach and it worked fine. I must have been doing something wrong.

Have now refactored all "On Deck" references to "Continue Reading" (this was just a holdover from the old code I wrote before we agreed to merge the two sections).

RE: Frontend framework. Time is always the enemy! I've toyed a tiny bit with Vue and seemed to get on with it better than React. But Javascript has never been my strong point and don't think I have enough experience to recommend or be that much help in this area :/

Further ideas / still todo

The basic version of the feature is largely done. I have some further thoughts and ideas below but I'd like your feedback on a) what you agree with, and b) what should we include in this issue vs spinning off as a separate issues/features (I guess it's to decide if you're happy to keep iterating on the home screen here or if you want to close off the work and then explore further in new issues).

• Order by last read - I think people expect the most recent title they've read to be first in the Continue Reading list (ie. left most). If I'm reading 10 titles, I would expect the one I read yesterday to show before the one I last read a month ago. I believe this would require introducing a new section in info.json (I mocked up an example in this comment above)
• Configurable "Continue Reading" settings with sane defaults - At the moment we show all titles you have started reading, even if you last read it 2 years ago. Do we want to introduce some form of "max weeks" / "max total entries". There's a lot to think about here as if you are up to date with a manga and the only reason you haven't read a title in a while is because you're waiting for it to be published, ideally you would want this to show in "Continue Reading". Plex solves this by always showing season premieres ie. S0XE01 but it doesn't seem as straightforward with manga. There is an element of YAGNI / premature optimisation here and I'm inclined to spin this out to think about later. Plex settings as an example:
  
• Recently Added - New section on home page, under "Continue Reading". The purpose is to aid discoverability of new titles for users. The final form of this would ideally be intelligent enough to group multiple entries of the same title together (so you don't get one big long list of 20 entries for the same title). I think this would require adding another section to info.json eg. date_added as I don't think mtime will suffice.
• Onboarding for new users (empty home screen) - In its current form, new users and new libraries will hit an empty screen on / :( This could be partially offset by having the Recently Added section but I wonder if we have some explanatory text that explains to users what they'll see once they start reading and direct them to the Library page to get started? Quick mockup:
  
• Other possible sections for Home screen - eg. Recently Published, Start Reading, Rediscover, Top Rated. I think this should spin off into another issue. Some are possible eg. Start Reading, some depend on whether we implement other features above eg. Rediscover and some would only be possibly if we integrated with a 3rd party data source (Recently Published and Top Rated). If time was no object I think they would be nice features to have but I don't think these are a priority.

[jaredlt]

RE: UserEntry class. I clearly haven't properly thought this through :) I have most experience with Rails apps and using Rails with Devise (for auth) you get a really nice helper method current_user. In your controllers you create the objects needed in the view, and if the object should be limited to the user you can initialise it with eg. titles = current_user.context.library.titles (pseudo code). This means in your views, all of the attributes and class methods you reach for are already limited to what is available to the user:

<%- titles.each do |t| -%>
  <p>Percentage: <%= t.load_percentage %></p> <!-- Don't have to pass the user for each method -->
<%- end -%>

In a way this is just magic / syntactic sugar, but something like this could perhaps help down the line when you're looking to bring in filtering and visibility of multi libraries per user etc. Obviously I'm breezing over a lot of the complexity here and am probably being a bit naive with things. It's probably something you'd want to reach to a shard to help you solve. Anyway, this is way off scope. I'll leave this as food for thought for some future time!

[hkalexling]

I prefer keeping the relevant discussions in this issue as it's all about the home screen. We can open separate issues when working on the Plex theme or new progress indicators, etc.

I am thinking maybe we should allow the users to jump to the corresponding title page from a "Continue Reading" entry. Maybe we can add a "Go to Manga" button in the pop-up modal box? Let me know what you think :-)

Onboarding for new users

You are right and I haven't thought about this. I like your mockup and I can try to implement it. I think we should do something similar on the library page when the library is empty, but let's focus on the home screen first!

Order by last read and Recently Added

Yes I think we should have these two features ready before publishing a new version featuring the new home screen, and yes we should add the new fields in info.json. The "Recently Added" section would be particularly useful when we have the MangaDex auto-update feature (see #24). With the extra info saved in the JSON file, we can also have more sorting options in the library and title pages.

Your example info.json looks good, and I would suggest adding a time zone field just in case the local time zone changes. See https://crystal-lang.org/api/0.34.0/Time.html

Configurable "Continue Reading" settings

I think this feature would be nice to have but not pressing. It would be great if you have the time to work on it, otherwise, we can simply hardcode a limit (say 8 or 12) for the number of continue reading entries.

Other possible sections for Home screen

Yeah the extra sections you listed would indeed require external data sources, and I don't think a "Start Reading" section is necessary. The "Continue Reading" section we have now kind of acts like that, and the user can always visit the library page to "start reading". But maybe I misunderstood what you meant and in the case please let me know!

[jaredlt]

Jump to title page

Yes, definitely agree. There are quite a few buttons in the modal already and I've mocked up a slightly modified approach below. Inspired by Plex (as always!). My reasoning:

• Leave all the buttons to be about that specific entry
• Introduce a link (clear hierarchy of buttons for entry and links as secondary actions, while trying to not make the UI too busy)
• Use actual manga title as link text (there is a slight reduction in first time usability as users may need to click the link to learn where it goes, but after that it seems clearer that you click the actual title to go to the title. I did wonder if someone might see "Go to Manga" and be confused, asking "Aren't I already going to the manga? Ie. going to read this manga entry" <-- I could be over thinking this). I guess we could also try Go to [Ghost in the Shell] but the "Go to" will be superfluous after the first use.

Anyway, not beholden to any of this. Just an idea :)

Onboarding for new users

I'm happy to have a first go at this if it will help? I'm sure you have plenty of other things going on too.

Order by last read and Recently Added

Sounds good, I will proceed with these two.

Can you talk a bit more about the time zone field? I was planning to save the times in utc. Do you mean if the server time changes or the end user's? What is the implication?

Configurable "Continue Reading" settings

👍 I'll hardcode it for now but will have a think about this in the background.

Other possible sections for Home screen

By "Start Reading" I mean it would only show you titles for which you have not started at all. You're right that it's really just a shortcut to going to your library and sorting by Progress. I guess as your library gets bigger it might be a nice thing as a way to remind you of titles you haven't started. It's just another avenue for discoverability but don't think it's very important for now.

[hkalexling]

I'm happy to have a first go at this if it will help? I'm sure you have plenty of other things going on too.

Of course! That would be great 👍

Can you talk a bit more about the time zone field? I was planning to save the times in utc. Do you mean if the server time changes or the end user's? What is the implication?

Ah I thought you will just store the local time which might cause problems when the server time zone changes. If we are saving the time in UTC, perhaps we can make it more explicit? E.g.,

2016-02-15 10:20:30 UTC

One of the reasons I prefer using info.json over SQLite is that the data is more accessible to the users. Seeing implicit UTC time might be a bit confusing for them.

[hkalexling]

About the link to go to the title page, your mockup looks awesome! You're a great UX designer :D