Rework User Interface like Kiwix JS Windows

[Jaifroid]

This issue is a combination of #267, #304 and #337 (all of which are issues concerning the UI). The aim is to backport a version of the Bootstrap UI used in Kiwix JS Windows (originally used by @sharun-s in his fork of Kiwix JS). I think this work needs to be done before any more progress can be made on #127 and #173, for example. I'm opening a dedicated issue for this, so that we can set out a road-plan of what is desired and what is not desired before starting to backport, with the aim of avoiding undertaking unnecessary work.

[Jaifroid]

Let's break down the features of the reworked interface in Kiwix JS Windows. Refer to screenshot below:

1. Colour: in "light mode", the colour I adopted is light blue (both for top and bottom bar); in "dark mode", this changes to a very dark grey. The bottom bar is slightly translucent, so that upcoming content can be glimpsed through it as in current Kiwix JS. I don't propose to backport dark mode just yet, so the main decision here is the colour of the bars in light mode.

2. Mutating Home icon (top bar): The idea of the top-left icon is to provide some visual "branding" for the app, but it doubles as a Home icon. Because Kiwix JS has separate apps for Kiwix, WikiMed and Wikivoyage, I have code that mutates the Home icon, showing specific branded icons when WikiMed and Wikivoyage ZIMs are loaded. This means I don't have to maintain different code bases. For all other ZIM types, currently, the neutral Kiwix icon is used. Note that we are only using icons in this interface, there is no room for text as in the current Kiwix JS. How should I proceed? Shall we have a single neutral icon top left, or shall we mutate it? Note that the bottom bar also has a Home icon, but in this case, it is the standard "Home" symbol. An alternative design would be for the top-left icon to be a hamburger (sandwich) menu. Top-left is the traditional place in apps for hamburger menus.

3. Mutating Print/About icon: Due to lack of space, the last icon top right is a Print icon when an article is loaded in the iframe and is displaying, and is an About icon when there is no article loaded or when the Configuration page is showing. We have not yet implemented #350. I suspect we want a more elegant solution for Kiwix JS with regard to extensibility of features, as per #521. There @mossroy mentioned using a hamburger menu for extra features/content, such as About, Printing, Load all images. Traditional location for hamburger is top-left rather than top-right. We should decide this in advance of any coding.

4. As per #337 (last comment by @mossroy), it has been mooted in the past that we should provide the option to hide all bars (top and bottom) if the user wishes to work full-screen, and re-show them on user scroll and on keypress. What options do we wish to provide? My preference would be for a simple show all / hide all option in the interface, rather than detailed Show all / show only top bar / show only bottom bar / hide all. I think this needs to be decided before coding, even if the implementation of a hide navigation bars feature is in itself a separate issue.

5. Table of Contents: While this is a separate feature, it would be useful to know in advance if the solution provided in Kiwix JS Windows is an appropriate one for Kiwix JS, as it would affect the layout of the bottom bar. The solution I adopted was developed by Sharun-s originally.

6. Change font size: Although a separate a11y feature, should I allow space for something like this? It allows the user to set a base font size for displayed text of an article. It should be done differently from the way I do it in Kiwix JS Windows, and I don't propose to develop it as part of this backport, but the main question here is whether to allow for such a feature to be added to the bottom bar, or whether it should be (eventually) a feature for a hamburger menu. As an a11y feature, I felt it important to be readily accessible. Note that touch zoom doesn't work properly as in #25 and #163.

7. Extra Home button. Currently we have two of these in both Kiwix JS and Kiwix JS Windows, one in the top bar, one in the bottom bar. Is this necessary?

8. "Unclicking" icons. The way to move between Article / Config / About without reloading the article (#127) in Kiwix JS Windows is to "unclick" a clicked/pressed icon. The visual clue is that the icon remains depressed while a specific page is open (except the article itself). I assume we want this feature for Kiwix JS.

That's all I can think of for now.

Top bar:

Bottom bar:

[mossroy]

Thanks a lot for this detailed inventory! You did not mention the fact that the search field has been merged with the top bar, which is a great idea that should be backported for kiwix-js. If we don't have enough space, clicking on the search icon could make the search field appear (above some other content) and disappear.

Here is my point of view for each feature (open to discussion) :

1. Color of the bars in light mode

I don't have a strong opinion on that. I like this light blue and would suggest to keep it unless you have another idea.

2. Mutating Home icon (top bar)

Until we implement #292, kiwix-js is a generic ZIM reader. So I would keep the neutral icon. Maybe the Home button of the bottom bar could be removed, as it's redundant and we try to save some space. Regarding the position of this icon and the hamburger menu, I don't have a strong opinion. https://ux.stackexchange.com/questions/115468/what-the-difference-between-the-2-menu-icons-3-dots-kebab-and-3-lines-hambur give names to this kind of icons : 3 lines = hamburger menu, 3 dots = kebab menu. It also leads to these Android guidelines for mobile apps : https://material.io/design/components/app-bars-top.html#anatomy, where the hamburger menu is in top-left (called "navigation icon") and the kebab menu is in top-right (called "overflow menu", with some contextual actions). Maybe we could simply follow these guidelines? (or some other ones) instead of trying to invent something else (we're not UX/UI specialists, at least for me). I see that they display no application icon : maybe we could display it on the right of the hamburger menu, only when the screen is large enough? (it should be doable with bootstrap)

Following these Android guidelines, we might put in the hamburger menu the 3 sections (home, settings, about), and in the kebab menu the not-so-common actions (random, print, display/hide images, back/forward, zoom in/out etc). If we implement that with bootstrap, it might automatically decide if the screen is large enough to put these actions in the top bar or in the kebab menu. But it's just an idea.

3. Mutating Print/About icon

Combining both actions on a single icon might be un-necessary if we implement what is suggested above

4. Hide top/bottom bars

I think we should completely remove the bottom bar. It gives many technical and usability issues. A few thoughts on where we could move its icons :

• home button : might be removed, or moved in the kebab menu
• back/forward : many devices already have another way to go back to the last page. We might move them in the kebab menu
• table of contents : kebab menu?
• zoom in/out : kebab menu?
• go to top : might be replaced by an overlay arrow icon that would appear at the top-right of the screen when the users scrolls up (and disappear when he scrolls down, or after a timeout)

As the top bar would be merged with the search field, I believe it already saves enough vertical space : it would not be necessary to add another feature to hide the top bar.

5. Table of Contents

I would not backport this feature as it is now. @kelson42 is working on an API (part of the OpenZIM spec) that could be used to get this ToC in a generic way : I think that's what we should implement (when it's ready)

6. Change font size

It's worth backporting this in kiwix-js, but only if it's done in a generic way. Maybe it could be a general setting, applied on all subsequent pages/articles. In this case, it might be enough to put it in the kebab menu?

7. Extra Home button

See above. Maybe it should be kept in the kebab menu, so that it's still possible to do it if we hide the Kiwix icon.

8. "Unclicking" icons

I found this behavior intuitive. But it only works if the icons are visible in the top bar. If they can be moved in a menu (depending on the screen size), it won't work. Another way to do it would be to replace the hamburger menu icon by a "back" icon on top-left (only when in the settings or about section). It appears to be a classical way to do that on mobile apps.

In any case, I think we should try to not reinvent the wheel, both for the UI ideas and for the code. We already use bootstrap and should probably carry on using it as much as possible instead of coding things ourselves (and upgrade bootstrap if it's necessary)

[Jaifroid]

Thanks for the full response, @mossroy . This all seems sensible. The only thing I'm not too keen on is removing the bottom bar entirely. For anyone who wants to browse one-handed (in app context), it's essential to have minimal controls at the bottom, where the thumb easily reaches on all mobile sizes, even when you have a very large-screen handheld device. For accessibility, we mustn't assume all users have use of both hands. I'm also not sure it's technically possible to replace back/forward buttons with swipes (which would be one option), since we often have content that overflows the screen (large-width images, for example). However, if we dedicate the bottom bar to navigation only, it can be made to disappear when reading (a couple of seconds after scroll stop), and re-appear on scroll (or navigation key press), which should remove the technical issues we've experienced with it. Or it could be made never to show if a user wishes.

A compromise might be to allow the user to choose the position of a single bar, either top or bottom. However, I have my doubts that we can fit everything that needs to be on-screen (not hidden behind kebab) in a single bar. I'd have to experiment.

I like the idea of hamburger top-left and kebab/overflow top-right. Though I also like an application icon, but it's not a big issue. Usability is the most important. Thank you for your ideas. I don't think I'm going to be able to do substantial work on this for a few weeks due to commitments, but it's good food for thought. I completely agree on using Bootstrap. It would be major major work to use any other framework.

In the meantime, do we have enough new features for new release, before a UI change?

[mossroy]

We probably have enough new stuff for a 2.6 release, you're right. I just created #525 for that.

Regarding the bottom bar: It is useless in browser extensions (where the user should use the built-in buttons of the browser). On mobile, I agree with you that it's useful to be able to easily go to the previous page ("back" button), while I think the "forward" button is much less useful. Having this bar disappear/reappear might be a good idea.

[Jaifroid]

The first stage in implementing this issue is #527.

[Jaifroid]

@b16r05 commented in #265:

@Jaifroid

[ ...snip... ]

I finally, finally, tried Kiwix-js 3.1.0 ... and, wow, wow, wow : ) Very nice! Color is nice. Inversion-based theme works well.

Suggestions:

1. I, personally, don't like the spinning circle... but, not a problem. Links are fast enough.
2. SEARCH and RANDOM take up space. They can put on the same line as Kiwix logo (version) [I will call this MENU line), placed on the right side.
3. Navigation bar at the bottom still does not make sense. We are in a browser after all. HOME link can be programmed on top of the kiwix name (top left). BACK and FORWARD link not required (We are in a browser). SCROLL TO TOP could be moved up, on the MENU bar for now.

...

Moving items to menu bar:

KIWIX 3.1.0 || HOME || CONFIG || ABOUT || SCROLL TO TOP ICON || SEARCH || RANDOM

Rearranging items on menu bar:

KIWIX 3.1.0 || SEARCH || RANDOM || SCROLL TO TOP ICON || CONFIG || ABOUT

Now, that is a professional look. Making the font of the menu bar items even more compact, will give readers even more digital real-estate for... reading :)

[Jaifroid]

@b16r05 Take a look at the layout of the PWA (Progressive Web App) version of this app:

https://pwa.kiwix.org/

(you can use this with an existing ZIM you have on your machine). Is that a better layout? Also, if you load up a ZIM and navigate to an article, you will see that the top and bottom bars slide away when you scroll down, and slide back in when you scroll up. It's the direction we have planned to go in in #523 , but are just lacking time to implement this in the short term. The reason it already exists in PWA form is that I implemented that layout some time ago in Kiwix JS Windows based on the old Bootstrap 3, whereas in the meantime Kiwix JS (the app you are using) advanced to Bootstrap 4 which is different enough to make this non-trivial.

I believe that a bottom bar is necessary, because it is more accessible to one-handed users of mobile devices than the top bar (I don't just mean those who are missing a hand: we all use mobile devices one-handed at times). But it can be made optional or scroll-away.

Note that Kiwix JS is not just a browser-based app: it is used on Ubuntu Touch, Firefox OS and Windows UWP touch-based devices, and the PWA version can be used and installed on Android (though I wouldn't yet recommend it over the standard Android app, because it is slower and until the File System Access API is implemented on Android Chromium browsers, the user has to pick the file every time, unlike with the PWA version on Chrome/Edge on PC).

EDIT: I should clarify that the PWA version is based on Kiwix JS Windows, which is itself based on Kiwix JS, but has more experimental features, and is not 100% in sync with Kiwix JS (I keep the backend in sync). My aim is to converge the apps towards the best tried-and-tested generic features in the medium term.

[b16r05]

@jaifroid ... Comments + Feedback

Wow! That is a lot of work... versions to keep track of and keep them updated! Thank you for all the hard work. I was just trying to help, but now, I am trying to follow all that you do :)

PWA version... I had no idea. Yes, the layout is much better and yes, it is slower. Top and bottom bars sliding away works great.

Bootstrap... don't know what that is, but, that is for me to research.

The logic of the bottom bar is great. Scroll-away is good, but having it as an optional feature for users to enable/disable, is even better.

TOC works great, but does take some getting use to. I will again, highly encourage you / dev team to take a look at this stylish theme: https://userstyles.org/styles/154881/wikipedia-clean-dark Your TOC implementation is horizontal; sylish theme's TOC implementation is vertical. I don't know how that will work/integrate with your TOC (IF you decide to use some code), but someone more creative might be able to work it out OR get ideas from it.

Ubuntu Touch, Firefox OS and Windows UWP touch-based devices... never tried it and still don't understand... javascript can run on them like an app? Okay! PWA interface is great, but, yes it is slow. It flashes a white background as it loads a page and then, it gets to the dark theme.

What about Firefox browser? Is File System Access API already implemented, going to happen or not at all? Because, I use FF and PWA version was slow.

I think converging the development is a good idea. I am sure it will help with keeping track of different projects... and alignment can help with replicating code (if that even works) and faster updates!

[Jaifroid]

@b16r05 Thanks for the feedback. If you experience slowness on the PWA version (assuming you're using a PC), it's not related to the UI, it's could be related to slightly less functional caching in that version, which needs working on. Personally I don't see a noticeable difference in speed, on Chrome or Firefox. On Android there is a big difference, though: see #581.

The sliding away is indeed optional (see Configuration), and would also be in Kiwix JS when we port that. We haven't decided on ToC, that's a prototype, so we'll look at the Stylish theme version.

Flashing white first, or occasionally flahsing black first, can be a problem with white- and dark-mode switching, and it's hard to deal with! I don't actually see this with the PWA version on Firefox, if I've set both the UI and the ZIM content to display in dark mode, and the Firefox browser UI also to dark. On Chromium, with the installed app, it does flash white first.

Most platforms can run apps that are written in JavaScript. In Windows, JS UWP apps are now being downplayed in favour of light-weight PWAs which are cross-platform and can be installed from a Web page (no need for a Store), and work offline. Android can install PWAs too without needing a Store, but as mentioned Android web apps have particularly slow filesystem access with large ZIM files.

Firefox has patchy support for PWA technologies to date. The File System Access API is not implemented yet in Firefox, nor is the "before install" prompt API, meaning it's not possible to provide an install button in the UI for an app that is not already installed. Firefox does not support installing a PWA on PC or Mac either, but it can be bookmarked and will work offline.

Definitely want to converge development, but while I'm still supporting the UWP app for Windows touch-based devices, and also Electron and NWJS apps, I need a separate codebase. Not enough time for these projects!

[Rbcoder1]

Is this issue is solved or not

Can I try it

[Jaifroid]

@Rbcoder1 Please see above. This issue is not solved. It's a bit complicated, but if you have the experience, we'd welcome a PR. Please read https://github.com/kiwix/kiwix-js/blob/main/CONTRIBUTING.md very carefully (and all the way through), and then experiment with the implementation to see if it is viable for you to fix it. Compare with https://pwa.kiwix.org. When you feel you have a solution, please describe how it will work technically, and I can assign you.

[Rbcoder1]

Let's break down the features of the reworked interface in Kiwix JS Windows. Refer to screenshot below:

1. Colour: in "light mode", the colour I adopted is light blue (both for top and bottom bar); in "dark mode", this changes to a very dark grey. The bottom bar is slightly translucent, so that upcoming content can be glimpsed through it as in current Kiwix JS. I don't propose to backport dark mode just yet, so the main decision here is the colour of the bars in light mode.
2. Mutating Home icon (top bar): The idea of the top-left icon is to provide some visual "branding" for the app, but it doubles as a Home icon. Because Kiwix JS has separate apps for Kiwix, WikiMed and Wikivoyage, I have code that mutates the Home icon, showing specific branded icons when WikiMed and Wikivoyage ZIMs are loaded. This means I don't have to maintain different code bases. For all other ZIM types, currently, the neutral Kiwix icon is used. Note that we are only using icons in this interface, there is no room for text as in the current Kiwix JS. How should I proceed? Shall we have a single neutral icon top left, or shall we mutate it? Note that the bottom bar also has a Home icon, but in this case, it is the standard "Home" symbol. An alternative design would be for the top-left icon to be a hamburger (sandwich) menu. Top-left is the traditional place in apps for hamburger menus.
3. Mutating Print/About icon: Due to lack of space, the last icon top right is a Print icon when an article is loaded in the iframe and is displaying, and is an About icon when there is no article loaded or when the Configuration page is showing. We have not yet implemented Add a "print" feature to print the contents of the article iframe #350. I suspect we want a more elegant solution for Kiwix JS with regard to extensibility of features, as per Use a custom context menu for extra features #521. There @mossroy mentioned using a hamburger menu for extra features/content, such as About, Printing, Load all images. Traditional location for hamburger is top-left rather than top-right. We should decide this in advance of any coding.
4. As per Rework the bottom bar #337 (last comment by @mossroy), it has been mooted in the past that we should provide the option to hide all bars (top and bottom) if the user wishes to work full-screen, and re-show them on user scroll and on keypress. What options do we wish to provide? My preference would be for a simple show all / hide all option in the interface, rather than detailed Show all / show only top bar / show only bottom bar / hide all. I think this needs to be decided before coding, even if the implementation of a hide navigation bars feature is in itself a separate issue.
5. Table of Contents: While this is a separate feature, it would be useful to know in advance if the solution provided in Kiwix JS Windows is an appropriate one for Kiwix JS, as it would affect the layout of the bottom bar. The solution I adopted was developed by Sharun-s originally.
6. Change font size: Although a separate a11y feature, should I allow space for something like this? It allows the user to set a base font size for displayed text of an article. It should be done differently from the way I do it in Kiwix JS Windows, and I don't propose to develop it as part of this backport, but the main question here is whether to allow for such a feature to be added to the bottom bar, or whether it should be (eventually) a feature for a hamburger menu. As an a11y feature, I felt it important to be readily accessible. Note that touch zoom doesn't work properly as in Enable pinch to zoom #25 and Zooming with the fingers should only zoom the article content, not the UI (menus, bottom bar etc) #163.
7. Extra Home button. Currently we have two of these in both Kiwix JS and Kiwix JS Windows, one in the top bar, one in the bottom bar. Is this necessary?
8. "Unclicking" icons. The way to move between Article / Config / About without reloading the article (Reopen the last article after switching between menu items #127) in Kiwix JS Windows is to "unclick" a clicked/pressed icon. The visual clue is that the icon remains depressed while a specific page is open (except the article itself). I assume we want this feature for Kiwix JS.

That's all I can think of for now.

Top bar:

Bottom bar:

So I Just Solved This Problem's / Issues Ok

[Jaifroid]

@Rbcoder1 Yes, those are the steps I already put in this issue. Do you feel confident you can undertake this issue? It's not trivial...

[Rbcoder1]

So I got It And I Am Working On It . If Any problem I Will share ok

On Sat, 8 Apr 2023, 6:03 pm Jaifroid, @.***> wrote:

@Rbcoder1 https://github.com/Rbcoder1 Yes, those are the steps I already put in this issue. Do you feel confident you can undertake this issue? It's not trivial...

— Reply to this email directly, view it on GitHub https://github.com/kiwix/kiwix-js/issues/523#issuecomment-1500882748, or unsubscribe https://github.com/notifications/unsubscribe-auth/AZRVEQRRDAIZGNKV4XPRGQ3XAFLKRANCNFSM4H3BXKGQ . You are receiving this because you were mentioned.Message ID: @.***>

[Rbcoder1]

We will be make the both top and bottom bar like PWD ,That is scrolling I like this idea and we will also implement it in kiwix js

[Rbcoder1]

2. Mutating Home icon (top bar):
3. Extra Home button

Yes In Kiwix Js Their Is No Icon Used Currently. I think we need to used hamburger on the place of top left icon because using hamburger we will solved the problem of multiple home icons . Also we will add more item in hamburger and remove the problem of lack of space so our application is become neet & clean.

[Jaifroid]

@Rbcoder1 The current interface uses the hamburger when the screen size is small, and removes the hamburger when the screen size is large. You could maintain that functionality, but it might be tricky to make it work with the scroll-away function. I'm not sure. In https://pwa.kiwix.org I removed the hamburger functionality because it was a bit clunky. I think it's good to maintain it, but only for very narrow screen sizes.

[Rbcoder1]

Yes hamburger removed from https://pwa.kiwix.org/

It will show when the screen size is small or we say in mobile view

But i think we will place it on desktop view also . And yes we will maintain it with scroll away function also.

[Jaifroid]

There was some discussion of the hamburger in #293. I think the conclusion was that it should be for really narrow screens. May not be necessary on all mobiles. But I look forward to seeing a test implementation. The way it currently works in Kiwix JS is quite clunky and wastes a lot of screen space.

NB, you might consider breaking this issue down into smaller PRs to work in stages:

• PR 1: Change text to icons in top bar and move random icon
• PR 2: Move search bar to top menu
• PR3: Re-engineer the collapsing, with proposals for a hamburger menu and, if necessary, a kebab menu
• PR4: Implement option to hide bars (scrollaway)

That's just a suggestion. It could be a different order.

[Rbcoder1]

Definitely It Is Very Easy To Implement in different stages I Am Working as per this.

[Rbcoder1]

I have setup the kiwix js on my local machine and install all dependency as per package.json And then start server using NPM RUN SERVE and it will showing two port’s one is localhost and another one is router network port.

If I Change Any HTML File then it reflect on this http://192.168.43.129:8080 this port not on localhost or http://127.0.0.1:8080 port. If I am changing Code in index.html under ./www folder I then it will reflect on port but if I am changing the app.js or require.js file then it will not reflecting on any port. Suppose I delete all code from app.js then also it will showing in our source tab of chrome developer tool mean not reflecting any changes. Please can you explain me how can I setup and edit it on my local machine. Once I understand the codebase then I will definitely give my best.

[Jaifroid]

@Rbcoder1 As it says in CONTRIBUTING, the app caches its own code. In order to get changes reflected, you need to do three things:

• Tick the box "Bypass AppCache" under Expert Settings
• Open DevTools and go to the Network tab. Tick "Disable Cache" (see screenshot)
• Then, when you make a change, use Ctrl-Shift-R to force-refresh the whole app.

When you do that, the cache will be cleared, the Service Worker will be re-loaded, and changes you have made will be reflected in localhost:8080. Note that you only need to do Ctrl-Shift-R when you make subsequent changes. You don't need to do all the other things again (unless you've changed any of those settings in the meantime).

[Jaifroid]

NB DevTools must be open for Ctrl-Shift-R to work consistently.

[Rbcoder1]

Ok thanks you so much

On Fri, 21 Apr 2023, 7:25 pm Jaifroid, @.***> wrote:

NB DevTools must be open for Ctrl-Shift-R to work consistently.

— Reply to this email directly, view it on GitHub https://github.com/kiwix/kiwix-js/issues/523#issuecomment-1517871373, or unsubscribe https://github.com/notifications/unsubscribe-auth/AZRVEQTPQMMLY2LTAFHMJM3XCKGUJANCNFSM4H3BXKGQ . You are receiving this because you were mentioned.Message ID: @.***>

[Rbcoder1]

I Changed The UI From

To

This is the first PR task I Completed

[Rbcoder1]

Is it right

[Jaifroid]

Looks great to me! When you're ready, please make a PR.

[Rbcoder1]

Yes I will raise PR just Finished The responsive task Today.

[Rbcoder1]

I maka pull request and it's my first pull request But showing an error to me

[Rbcoder1]

I make a new PR please Check it revokNavbar