Tour of BioMixer

[everbeek]

Is there a web app oriented thing similar to Tours that we could use to guide new users?

[everbeek]

I asked Laura, and she directed me to this: http://tourmyapp.com/

I will look at it, and search for alternatives now that I have this lead.

I expect everything I find to be via sequential popups rather than more fully featured like Tours. We'll see.

This company offers some keywords for finding interactive onboarding tools: http://blog.kera.io/post/42951938895/top-walkme-alternatives-compared-and-visualised . Their onboarding product appears to be gone, and I came across two other web tombstones in this field.

This Quora answer has many links: http://www.quora.com/What-are-the-alternatives-to-WalkMe

[everbeek]

of the ones below, Hopscotch then Joyride are the most polished of the freely available onboarding libraries. Features they probably lack include spotlighting and action following (click a button, triggers the next step of the tour). I will have to look deeper into each to see if they support these two vital features, or if I could easily tack those on.

• Free, easing and scrolling, back and forward: http://linkedin.github.io/hopscotch/
• Free jquery plugin under MIT license: http://zurb.com/playground/jquery-joyride-feature-tour-plugin (is indeed on github)
• Free with shadowing, step markers, keyboard navigation, but not action following: http://usablica.github.io/intro.js/

---

• Free, see wikipedia test usage, has action executing button option, but no shadowing with highlighting like intro.js has: http://www.jeffpickhardt.com/guiders (this article also mentions industry stats on user fall off as a tour progresses...20-30% falloff on first step, then 2-8% falloff at each subsequent step) (http://blog.wikimedia.org/2013/02/01/guided-tour-launch/)
• Free, amazingly raw documentation: http://sorich87.github.io/bootstrap-tour/api/
• Free, visually interesting, but a bit oblique to click the speech bubble to progress: http://blog.tommoor.com/crumble/
• Free, but more suited to page-by-page tours, and don't allow interactivity with page: http://amberjack.org/
• $, but has page changes and spotlighting. In BioMixer, page changes don't occur, but the concept of action and step being interactively connected is important: https://tutorialize.me/user/get_started

A variety to look at. Focus on the Github ones, check all for free-ness: http://www.quora.com/What-are-the-alternatives-to-WalkMe

[cpetrachenko]

Great ideas and I'm excited to do something like this. But do tools like these affect the performance of the application being described? (I may misunderstand how these tools connect to the application being described, if at all.)

[everbeek]

I don't think they would affect performance. They would only be activated on first visit or via some "Show Me!" button that I would add. Nothing in the existing functionality would trigger any of a tour library's code, only vice versa and only during a tour. It would increase the download size, but that's unlikely to be a problem for quite some time.

[everbeek]

Some thoughts:

• I really want to be able to execute arbitrary JS at each step. If whatever I pick does not support it, I will modify to include pre- and post- function calls
• I also need to be able to provide functions rather than strings for data ids that any tour uses to position dialogs [none of my top three support this, so I will have to modify them or hack things]
• I also want to be able to inspect the tour data for ids to be used, and verify that they exist whenever possible. The use of this is so that I can see during development if I have broken part of the tour, reducing the chance I will do so prior to committing it. If I use functions to get ids, that implies they may not be present at the time of page load, which complicates this requirement. Perhaps I have to skip verifying the presence of those ids. This will definitely not be supported by whatever library I choose, so I simply need to be able to easily inspect ids to be visited prior to running the tour, and do so with custom code.
• likely, I want to be able to hack onto any forward or back buttons arbitrary javascript (an extension of the above idea). This allows me to undo things if the user backs up.

Joyride includes a single method call that is called after each step, and a single method after the final step. Looking at github, it also has pre- and post- methods. I could probably also use this to update or inject ids into the driving data structure, if the ids are not in existence prior to taking certain tour steps. Not a big deal at all. Joyride also keeps its data separate from the document, in a way, so it can be inspected for ids that will be used.

Intro.js uses a roughly identical data structure. It has an onChange(nextElement) method, onStart(), and onExit(). It also has onbeforechange(nextStepElement) and onafterchange(nextStepElement), which I presume will receive the "previous" element when moving backwards. Form that I can ifner undo and redo. Like Joyride, it does not have functions allowed instead of constants for string values, but has the progress meter and back forward buttons.

Hopsotch has an even more diverse set of events I can bind to, but covers the same base ground (pre, post, etc). The nextOnTargetClick is really nice; it allows the user to progress the tour by clicking the item of interest, but this is a mixed blessing if all other elements are not prevented from being clicked...and Hopscotch does not appear to have spotlighting. It does support helpers...a way of dealing with an inability to include function definitions in JSON (as opposed to JS structures which otherwise are quite similar to JSON). If this is a problem with using the other ones, look to Hopscotch. Handles multi-page, but I don't need that I don't think.

Conclusion: Intro.js looks preferable because of progress meters, back and forward buttons, and spotlighting. It doesn't have scroll easing...but I don't need that! Joyride has the "expose" and "modal" parameters that create spotlight effects. Hopscotch has the target clicking option...

[everbeek]

For the tour, if I don't think I can do it using whatever graph the user has loaded, I can set it up to be a link to a stand alone window, which is passed an argument that starts the tour right away.

Found more...I will assess them quickly now that I have three baseline libraries to compare to: https://news.layervault.com/stories/15273-a-list-of-product-tour-plugins-for-onboarding

Ok, this one is nice but I'm not convinced it is superior to baseline: http://ryanfunduk.com/jquery-tourbus/

Chardin.js has wonderful contemporary design: http://heelhook.github.io/chardin.js/ and spotlighting. But it may not have steps.

Tourist.js is explicitly meant for complicated apps where actions need to be taken on the udnerlying page...interesting... http://easelinc.github.io/tourist/ It requires a CSS dependency, as well as Backbone. I don't feel like adding those unless I deem Tourist's features fully necessary.

Shepard.js allows interaction when things are dimmed. That would be ok for our case, or even desirable. http://github.hubspot.com/shepherd/docs/welcome/, but it also has an additional dependency called Tether, but is included.

It looks like I am still deciding among Hopscotch, Intro.js and Joyride, with my preference on the latter two except for the target clicking in Hopscotch. I can probably easily fake the Hopscotch "nextOnTargetClick" in the other two. Of more interest is modal and spotlighting capabilities.

[everbeek]

Ok, pulling the trigger on intro.js. If I have problems with it, Joyride and Hopscotch are both options too.

[everbeek]

I set up a tour with intro.js, but it allows popups to be positioned such that they go off screen. That's not ok, and there is a long outstanding issue for it. I will set things up with Joyride next, and probably Hopscotch. If it seems like the right decision, I will devise a fix for Intro.js and probably submit a pull request.

Oy, it's already a problem for me that Joyride expects an id for the element to be focused on...perhaps I will skip to Hopscotch right away.

[everbeek]

Intro.js doesn't allow use of highlighted elements, which means the users cannot perform the actions I want them to. I haven't completely abandoned it, since this might be easier to modify than Hopscotch...

Hopscotch does let me have users actually use page elements, but it doesn't offer shading, or modal dialogs, or non-anchored ones (where there is no target for it to point to). It also allows dialogs to fall off screen.

I just fixed a positioning problem in intro.js, and tried to fix the inability to interact with spotlighted elements. I cannot fix the latter, it seems, so I will prevent the shading and spotlighting from occurring. I would try a bit longer, but the spotlighting effect works poorly with SVG (such as the node menus), because of z-order problems. It seems to place the spotlight box below the element of interest, but the library is not coded to be SVG aware.

If I can disable shadowing and spotlighting easily, I am yet another step forward.

[everbeek]

I have disabled spotlighting and shading because of the SVG incompatibility. I now have null exception spawning from the same overall problem. When introjs tries to remove the previous element that was focused on (.introjs-showElement), it finds null when that was an SVG element.

If it were not a library I would move to using D3 selectors to get at the SVG.

http://stackoverflow.com/questions/8638621/jquery-svg-why-cant-i-addclass

One alternative is accessing classList rather than className, but IE doesn't support that. I will look at the Mozilla classList shim there, as well as Motto's library for accessing SVG classes from JQuery. I can then either use the shim and change className to classList where appropriate, or change all the className attribute accesses to JQuery. It's too bad that IntroJs does not use JQuery. The shim is preferable because then I don't need to taint our copy of IntroJs with JQuery, just change the JS approach it uses.

[everbeek]

Introjs steps behave well know, until I need the menu opened up. Then the tooltip causes the page to expand wider, and it gets placed off to the right of the menu item of interest, even pointing in the wrong direction. It is as though it is being added with incorrect display properties or to the wrong parent element, but it is likely something else.

[everbeek]

getBoundingClientRect() is giving me decent values for most elements, except those that are nested in my menu.

[everbeek]

Have it all working now. Committing, Then getting on to fixing a bug wherein I cannot drag nodes (#501). I think it preceded this work.

After fixing that, adding id checks at construction time and testing in an embed environment.

[everbeek]

Add:

• arc color and ontology color can be re-assigned by clicking on the sample arc in the arc filter menu, or on the color swatch in the ontology filter menu
• Is there a way to reduce the thickness of the frame around the Menu and Tour buttons?
• Change title of “Take an Intro.js tour” button… Get help… Learn more… Get started ??
• Can we include a link in the tour popups? If possible, we could link to further documentation, such as with the first popup, we could link to where we describe the path to root, term neighborhood, and mappings neighborhood options.
• The tour item that talks about sharing a layout: the click HERE link opens the viz in the same window, so the user's position within the tour is lost. While you can right click and open it in a new tab or whatever, people tend to be dumb so we should do this for them. Also, the window that opens doesn't really work (same issues we talked about earlier today) but perhaps that will be remedied when stage is fixed? Also, when the link is clicked, does the menu and sharing area display so that it's obvious to the user?
• I wonder if we should tour the menu all in one go instead of covering a couple things, then talking about working in the viz, then returning to telling them about the menu. I would cover viz basics (undo,redo,dragging,hovering,etc) before opening the menu. Thoughts?
• The tour item that talks about expansions: the menu item isn't automatically opened like with the other tour items. ("You just expanded a node, and a bunch of related nodes were added to the graph...") [I think the user should have to click this menu open themselves. It's one level deep, and differs from the main menu, so they will have the interactivity of locating it, clicking it, then clicking the options provided. For the other menu, I don't want them to constantly need to track down the submenu during the tutorial.]

[everbeek]

I am considering re-implementing the Intro.Js highlight mechanism (which I disabled with CSS). If I make it into four lines, rather than a box proper, then we can click through it freely in any browser.

This is kind of insane...and I kind of like it: http://www.walterzorn.de/en/jsgraphics/jsgraphics_e.htm . This is a library allowing geometric drawing in pure javascript (no SVG, no Canvas, no Flash). It uses good algorithms, and implements the shapes as collections of divs (insane!). I was just considering the use of four divs to produce the box outline, but I might use this instead, if the library looks easy to use and isn't too large. It would offer more flexibility (such as tightly outlining objects to be highlighted, even if they are not best outlined in a rectangle). It's 23K...so I will make my own rectangles and if we need flexibility, this note will be around to point towards this library later.

[everbeek]

I have an outline that works with html and SVG. It can be improved visually later via CSS, but works well as it is. It cannot be given a background, because that would lead us back to the same problem that I was trying to resolve.

Also got myself stuck when I changed a function to a lambda function and failed to change a single call instance...couldn't figure out why the menu system was broken. Sorted it out though.

[everbeek]

Looks great in embed. Closing case for now, but tweaks will surely follow later.