Add new platform selection mechanism #87
Conversation
Uses Bootstrap pills. Includes many TODOs, but mostly functional. Also included test page for platform content. Still need to format selectors on page (including labels and a flyout), implement load/save/defaults, and add nested options.
|
Looks like a good start. One key feature I would like to have is to be like msdn where you have the tabs (or pills or whatever) to switch for each place on the page where there are platform specific bits rather than just one place to change it at the top of a page (unless of course the whole page is different). For example, on this page, there are 3 different places where you can switch between C# and VB, but if you change one, not only does it change all 3 on that page, it also sets the default for the entire site until you change it again. |
|
My plan is to do it as you mentioned, except have a single control on the page to control that (because it is changing it for the whole page anyway). More like a configurable setting. So yes, my plan is that "not only does it change all 3 on that page, it also sets the default for the entire site until you change it again". Do you think it makes more sense to do it with the tabs instead of the page-level option? It basically comes down to whether or not you think of it as a global option to choose which type of documentation you are viewing or a localized option that changes a section of the docs that also saves it for convenience. The main idea that I see is that, because you are likely going to continue using the same platform for all your documentation browsing, we don't need to take up space in the content of the page for the options. That MSDN page that you linked to does the "whole-page" thing for the .NET version (in the upper corner below the title) as well as the language selection. In terms of scale, the PC OS is probably something that changes the whole page while the ev3dev hardware only changes one or two details, so maybe I should make it so that you can set the mode (tabs or page-wide) in the markdown and have it render accordingly. Whatever you want me to do here, it will only be a few small changes to make it serve either function. |
|
By the way, this PR is not dead -- it's just deprioritized 😉 I have local changes that partially implement platform versioning, but I haven't had time to finish it up and push. One day... |
…nto new-platform-selection
For some reason the click + switch logic isn't working on nested items. Other than that, this should be completely functional. This is pretty ugly code, so hopefully it can be significantly cleaned up.
|
@dlech I have made some changes to this PR that get the platform selection fully-functional, barring the UI/UX. So, how would you like to have it laid out on the page? I see two major options for this. One is to treat the platform as a "global preference": the header has some sort of control that lets the user select their platform (the options would probably be in an options pane/flyout), and they see content that is appropriate for that platform. There wouldn't be a visual distinction between platform-specific content and generic content; to them, it would just be like a different page for each platform. This would likely include an icon to tell the user that their content is being modified for those preferences (which are accessible because the navbar is fixed in the viewport). The second option is to have the platform control show up so that it is tied to each section of platform-specific content. In this model, the special content would be made visually distinct (maybe with a different background color?) and it would be presented to the user as a special section that could be changed to match their target. This would likely have the control either above or to the side of the section, and when the user clicks it it would expand into a full options pane. We could also have a hybrid of these two modes; while the control is in the header, the platform-adapted content is still separated from the rest so that it is clear what content is different. I think that this decision mainly comes down to how we intend to use the platform selection and how we want a reader to perceive it. For something like the getting started guide, for example, chances are that the platform-specific content is broken up into small chunks. In that case, having multiple selector controls in view at once may get confusing. On the other hand, if there is a large page with large blocks of platform text, it might be easier to understand if there is always a control clearly associated with adapted content. Separately, we currently author the platform content in a |
How would this work on mobile?
This is more like the way I envisioned this working.
This is pretty much how I plan on using it. Most of the content on all pages applies to all platforms. Then we have small sections that are platform-specific. The user should only see the platform they are interested in and the rest should be hidden so they don't have to scroll past irrelevant content.
If you can figure out a foolproof way to match divs to tabs, then great. Markdown requires careful indentation management no matter what you do, so I don't really see much of a benefit here. For me, the less HTML mixed in with the markdown the better. |
Theoretically, adding a special control to the header should let it flow just like other controls, although we might want to make it permanent on the nav bar instead of in the hamburger menu if we decide to go down that route. The other option is to have it sit at the top of the page so that you scroll to the top to access it.
I think that that format makes the case for the "whole-page" platform selection. If the content that changes is only small sections (but there may be a lot of them), having a control for each place that changes seems like it would probably be weird. To a typical user, seeing a bunch of the same UI on different parts of the page that are tied together would not be natural, and it would be especially awkward if each of those regions were colored separately from the rest of the page.
Yep, I think we're on the same page there.
Since it looks like you aren't sold on this idea, I'm going to leave it until I get to the point where I need to transfer pages over to the new selection system; then we can sort out how we want to do this. |
Realization of ev3dev/ev3dev#474.
This is still WIP at the moment, so don't merge it (or look at it expecting it to be useful). But I have implemented the core of what was discussed in the issue linked above, so I figured I'd open this PR so that it can be discussed.
This just includes the basic JS needed to do the page content transformations and a test page that demonstrates the features. The code was originally a copy of the tab code, but as you can probably tell it has diverged to the point where there is very little resemblance (although the first 4 lines are mostly unchanged 😉). I also removed some functionality that I haven't yet reimplemented -- those items (and some others) are listed below. It also includes some notes-to-self and misc TODOs which will be cleaned up and removed in the future.
You can see the live test page here.Mygh-pagesbranch is currently preoccupied. I will remove this strikethrough once the test page is back up.Still unfinished: