10 ms·

Show HN: Weekend project, Intro.js

716 points by afshinmeh 14y ago

moe 14y ago
As others have already suggested: I think it would be even better if the explanation box was fixed (e.g. top left corner of the screen) and had a FAT red arrow pointing to the area of the screen that it explains. This would (imho) make it more obvious what's going on ("Ah, this is explaining that") and would improve usability. But either way, this is a great start (I love the limelight-effect) and we are definitely going to build on this. Thank you for open sourcing it!
acmecorps 14y ago
Superbly awesome work, afshinmeh! :D
przemoc 14y ago
Nice but lacks automatic scrolling to guarantee visibility of highlighted part and comment.
- afshinmeh 14y ago
  Yeah I just used a JavaScript method `scrollIntoViewIfNeeded` to scroll the page to the target element but it works in modern browsers AFAIK.
  - przemoc 14y ago
    I'm using Iceweasel straight from debian wheezy repository, i.e. Firefox 10. IMO not old enough to be not supported, but YMMV.
  - mediumdeviation 14y ago
    As far as I can tell it's a non-standard Webkit function. See https://bugzilla.mozilla.org/show_bug.cgi?id=403510 https://bugzilla.mozilla.org/show_bug.cgi?id=403510 and https://gist.github.com/hsablonniere/2581101 https://gist.github.com/hsablonniere/2581101
coffeeyesplease 14y ago
Very good, love the idea.
- afshinmeh 14y ago
  Thanks :]
padwan 14y ago
Nice and simple. Would be great if this worked over multiple pages.
- afshinmeh 14y ago
  Thanks. What you mean by "multiple pages"?
  - tzaman 14y ago
    He means that if intro instructs the user click here, and the browser goes to another page from within the same intro scope, then intro would pick up and continue.
    - padwan 14y ago
      Something like that yes :) Maybe step 1-3 is on "start.html" and step 4-6 is on "anotherpage.html". So when the user clicks next from step 3, he should be redirected to anotherpage.html and the intro continues.
      - afshinmeh 14y ago
        I got it, I got it. Good idea, I think you submitted an issue on Github also, right? Thanks for the awesome suggestion, in the next versions we will have that also.
        born2web 14y ago
        +1 - ability to guide a user through multiple pages would definitely be useful. Anyways, thanks a lot for a great contribution.
benharrison 14y ago
I really like this. I think it would be neat to see a discrete help button or toggle switch, that allows novice users to go into a help mode overlayed on top of a live web app.
- afshinmeh 14y ago
  For the next versions I'll add it so. Thanks for suggestion.
felix 14y ago
Nicely done. Bonus points for not making it a jQuery plugin!
- afshinmeh 14y ago
  VanillaJs!
spobin 14y ago
I've been looking for something like this for a while now. Brilliantly executed, thanks! I'll definitely be trying it out on my next project.
- afshinmeh 14y ago
  Whoho, Thanks :)
avel 14y ago
A nice alternative is Zurb Joyride: http://www.zurb.com/playground/jquery-joyride-feature-tour-plugin http://www.zurb.com/playground/jquery-joyride-feature-tour-p... http://foundation.zurb.com/docs/components/joyride.html http://foundation.zurb.com/docs/components/joyride.html
- afshinmeh 14y ago
  Yeah but it works with jQuery. What if I don't want to add jQuery to my page? IntroJs built with pure JavaScript.
  - ineedtosleep 14y ago
    Sure, if you don't want to have jQuery as a dependency intro.js is probably the winner. However, do note that Foundation's javascript plugins also work with Zepto[1][2] which weighs in at under 10k gzipped. [1] http://foundation.zurb.com/docs/javascript.html http://foundation.zurb.com/docs/javascript.html [2] http://zeptojs.com/ http://zeptojs.com/
- xpose2000 14y ago
  I was about to post this link myself. I'm not quite sure which one is better. I tend to like the Intro.js page fade animation. Although JoyRide 2 actually scrolls to the highlighted object, whereas intro.js does not.
- mos2 14y ago
  I think the work done here is fansastic and presents a great alternative to the zurb joyride / jquery or zepto combination. I agree with some of the other comments about the usability on an ipad and mobile device as well as scrolling the screen to the focused element. I think larger targets would really help with this. At this point in its development, if you are able to use jQuery or Zepto I think that Joyride 2 offers a much better UI / UX especially if you are planning to use Foundation 3/4.
  - afshinmeh 14y ago
    I'm also agree with you about the size of `next` and `skip` button. I'll fix it asap.
lukifer 14y ago
Great concept and execution! One item of feedback: the styling of the numbers look nearly identical to the feedback badge on iOS, which made me think for a second that it was some sort of alert, rather than a step in a sequence. Obviously the styling is customizable by the developer, but as a default, I could see it being confusing to iOS users. Edit: one more tidbit: resizing the browser doesn't force the box(es) to resize. Admittedly an edge case. :)
- afshinmeh 14y ago
  Yeah correct, there's a problem when you resize the browser. In the next versions I calculate all box(s) position again to keep focus element helper layer updated.
ceeK 14y ago
Very nice indeed, looks very well done!
racbart 14y ago
This is very nice but I have some suggestions to improve: Navigation: The “next” link is very small and it's in different place on every step. A fixed navigation and/or bigger link would be nice. Also, showing me that it's “Step 3” is useless to me - I can count myself and even if I couldn't, I don't really care how many steps I've already seen. I'm more interested in how many more there are. There should also be automatic scrolling so that I could actually see the next highlighted area. If you already do the scrolling, remember to scroll in a way that guarantees to show whole area, not only top line. Thanks for the great work, I think I might use it in my next projet!
- afshinmeh 14y ago
  Thanks buddy. I think I'll have those features for next version.
- matthuggins 14y ago
  I felt the same about the numbers appearing. It reminded me of the numbers that appear on my Facebook notifications/messages, and it made me feel like I needed to click/take some action with the number itself. It didn't really add anything to the experience though. Other than that, I liked it. I especially appreciated the animated transition to the next step, where the "spotlight" flowed & resized forcing my eyes to follow.
- dmragone 14y ago
  Agreed - came to comments to say the numbers aren't necessarily, and the navigation is unclear (though I just used keyboard arrow keys)
- ehsania 14y ago
  i think numbers in some cases are necessary. but can be optional.
  - afshinmeh 14y ago
    yeah we should have a config method.
niggler 14y ago
Looks very cool but the fact that you have to hit the tiny "next" link makes it hard to use on iPad. It's compounded by the fact that the page isn't scrolling down all the way from step 1 to step2 so you have to scroll down manually. On the computer, though, this looks slick and works reasonably well. Good job!
- afshinmeh 14y ago
  We're working to prepare the next version for iPad and other touch devices also.
meerita 14y ago
My suggestion: take all the presentation. Make it less graphical and more scalable, lets say i dont want red circle with number i want just the overlay part. Looks good and I will use it no doubt!
- afshinmeh 14y ago
  Ok, good. I think I should add a config function to prevent some features, red circles for example.
  - meerita 14y ago
    That would make it. The problem is just that: designers doesn't want anything default. They like to customize to the extreme, take, put, etc. Keep going nice work!
nachteilig 14y ago
Thanks. I like what seems to be the differentiating feature here -- highlighting the actual elements on the page rather than pointing at it. I'm looking forward to the pull requests that fix some of the style issues (next button etc, as mentioned already).
- afshinmeh 14y ago
  Great. Pull-requests are welcome.
dubcanada 14y ago
Overall though its nice to see a non jQuery plugin! And it's very nicely done. Could use some finessing, on Opera there appears to be a white square/rectangle that appears on the next element for the second and third ones (not sure why). Then it disappears. Maybe it's an Opera thing. The styles that get applied to the element inside of the "white box" get applied before the white box moves. This is noticeable for the links in the top right. They turn light blue before the box even moves. It should be after the box has moved, since that kind of stuff is pretty much instant.
- nkozyra 14y ago
  Just curious ... why is it nice to see a non-jQuery plugin? Isn't the point of jQuery that it's tested and standardized for all browsers, thus theoretically reducing the odds that a plugin won't work on any given browser?
  - jgeerts 14y ago
    Probably the fact that you don't have to use jQuery if you don't want to.
    - Hovertruck 14y ago
      Yep. We're primarily built using the Closure library so it's nice to not have to bundle jQuery for third-party libs.
deleted 14y ago
[deleted]
drd 14y ago
Afshin, I think it would be good if you add an example (usecase, scenario, etc.) to the website for a quick introduction of the functionality.
- afshinmeh 14y ago
  Sure yeah. I'll add it so. Thanks.
kmfrk 14y ago
Place the Next and Prev buttons on a fixed position that doesn't change - for touch devices probably at 50% height, unless they block a tooltip. The current implementation feels more like a whack-a-mole game than a guided tour. :)
- afshinmeh 14y ago
  It's the first version! Let us complete it and help me with your suggestions. Thanks buddy.
- jliechti1 14y ago
  Agreed. That, or put a small reminder on the first step (or on each step) that lets users know they can use the arrow keys. Seeing the arrow in 'Next→' was not intuitive for me (if that was intended to convey that you can change steps with →).
- deleted 14y ago
  [deleted]
Inversechi 14y ago
Awesome - well done :) I'm loving this!
voodoomagicman 14y ago
How do you achieve the effect of the rounded corner box w/ box-shadow masking the overlay, but allowing content to show through?
- jgeerts 14y ago
  It's hosted on github, go and take a look ;).
  - voodoomagicman 14y ago
    Ahh, was looking for some new css property - it looks like it just sets position:relative on the content it wants to highlight, and then uses z-index.
    - afshinmeh 14y ago
      Yeah yeah. I didn't find better way for doing that.
voltagex_ 14y ago
Submitted a pull request with some basic copy-editing for you.
- afshinmeh 14y ago
  Thanks, merged.
davefp 14y ago
I'm curious, what connection to Canada does a Tehran-based web development company have? http://www.cira.ca/why-ca/ca-101/who-can-register-a-ca/ http://www.cira.ca/why-ca/ca-101/who-can-register-a-ca/
- gregmolnar 14y ago
  I am also curious. Why do you feel the need to ask this question? Are envy because the guy made a nice tool or what?
  - afshinmeh 14y ago
    Off topic I think.
    - gregmolnar 14y ago
      Sorry, you are right :). Thanks for the plugin by the way!
      - afshinmeh 14y ago
        Use it buddy :) I spent all of my weekend time to built it and I just published it open-sourced.
  - davefp 14y ago
    Not at all, I just find it odd. Having a fancy URL is great, but the restrictions in place on certain domains are there for a reason and should be respected.
- windsurfer 14y ago
  Maybe the domain is being rented from an individual who lives in Canada?
- gruseom 14y ago
  What connection does bit.ly have to Libya?
jQueryIsAwesome 14y ago
You are changing the z-index of the "focused" element but you need to check if one of the parents have z-index defined already because in that case the effect doesn't work. Instead of looking for a workaround I would suggest that since you are already aiming for modern browsers maybe you should use SVG (clip-path) with CSS {pointer-events: none} so you have a real "hole" and you could use 4 dummy divs if you want to disable interaction with non-focused elements.
- acoleman616 14y ago
  It depends on the complexity of the highlighted element, but you could also just clone & absolute-position said element.
  - jQueryIsAwesome 14y ago
    That can become a PITA if you want to preserve events and CSS in the focused element.
quizotic 14y ago
Wow. Wow. Wow. What a great way to do an on-site tutorial. Thank you!!
posabsolute 14y ago
Hey, we have been looking to integrate a solution like this in our product, I got a couple of suggestions. First, using data attribute is too intrusive, a json object would have been much better, we just cannot add these attributes everywhere in our app. Using a json object would also make it possible for anyone to create a UI tool for creating guides. Also a "scenario" concept would be nice, having the ability to have multiple scenarios in a page is essential for a support team. Last thing, the UX is fantastic, it's clean and simple :)
- afshinmeh 14y ago
  Aha, good idea for JSON (but I think attribute is a good one for some frameworks like ExtJs that you don't know your element id or something like that). What you need by "senario"? Could you please explain it more? Thanks anyway.
  - posabsolute 14y ago
    Yea, the support team want multiple scenarios (intros) in a page, we use a param, so they can link to it and push them to users asking how to do stuff, it becomes for us like an advanced, usable, faq system
diego_moita 14y ago
Brilliant and almost perfect. I will incorporate it into my project, next week. Thank you so much. Most people here are asking for more features. Please be careful with that; it would be a pity to see such a pearl to swell into bloatware. You have very good taste, let it be your guide.
- crimsonzagar 14y ago
  With under 4kb js and 2kb css I guess it is pretty far from being a bloat.
- thom 14y ago
  You could potentially build a commercial version of this on the same technology, if you wanted to keep the core of it lean. I know several people that would pay money to have this plus analytics about user progress and drop outs, user feedback etc.
  - ChrisCinelli 14y ago
    Somebody already thought about it: walkme.com
    - bmelton 14y ago
      Or HN's own, https://taurus.io/ https://taurus.io/
      - thom 14y ago
        Thanks for both the pointers!
        bmelton 14y ago
        I can't speak to the other one, but I will go on to say that Taurus is moving very fast. I was an early adopter, and while I don't use them anymore, I saw them go from a barebones product, to a barebones product with an on-site tutorial builder, to a fairly rich product with customizable themes, etc., in just a few weeks. I can't speak for what they've done since I stopped using them, but looking at their homepage, the velocity still seems pretty high.
cturhan 14y ago
Good job. In past I wrote something like this but it was just to save the day, therefore I didn't have a chance to publish.
haddr 14y ago
This is piece of brilliant work! When I saw it I suddenly got the idea I have to use it the project I'm working on. Thanks!
pchekuri 14y ago
this is simply brilliant.
ehmuidifici 14y ago
Awesome project, this plugin is great to do "howtos" and online interactive manuals. Cheers!
prakashk 14y ago
Very nice! Just one thing. I pressed the Enter key thinking that it would take me to the next step (like the right-arrow), but the page background went darker. And, each successive press of Enter made it even darker. I actually liked the effect (even if it was unintended) as it increased the contrast between the step being focused and the rest of the page. However, I found no way to get back to original page after all the steps are completed (by right-arrow navigation). Pressing ESC had no effect. Edit: Using Firefox 20.0 on Ubuntu Lucid.
- taoufix 14y ago
  Same here, using Firefox 19 on Windows XP. You can go back to normal by clicking with the mouse, the more you click the brighter it gets.
  - afshinmeh 14y ago
    And I ask again, it's very very helpful if you report a bug to our Github.
- davidradcliffe 14y ago
  The script probably just needs to check if it is already running before starting.
- afshinmeh 14y ago
  Thanks, could you please report this problem to the Github issues?
acjohnson55 14y ago
This is AWESOME! I'm totally going to use it in my project
bamazizi 14y ago
Congrats Afshin
- afshinmeh 14y ago
  Hey thanks :) I glad to see your comment here.
  - bamazizi 14y ago
    your project is such a great idea, we're going to use it at theRedPin.com keep me updated on your other projects. i may have more works for you very proud of you.
    - afshinmeh 14y ago
      Thanks Bamdad Jan :) I glad to hear that you want to use it.
floydpink 14y ago
Nifty little thing! Thank you. :)
cemregr 14y ago
AWESOME! The next button could be way bigger though, I felt like I was trying to catch it every time :) And maybe you can pre-focus on it with JS, so you'd give users the affordance that they can press enter to move on. (You enabled the right arrow key, but I didn't immediately know I could do it).
abailin 14y ago
Look great for super lightweight tutorials. If you need to customize more, http://tutorialize.me http://tutorialize.me is my favorite.
- lshemesh 14y ago
  Thanks abailin for plugging my startup! Guys this solution is really cool, and I love the "spotlighting" animation. When it comes to flexibility you definitely cannot compete with implementing a simple library like this. Nevertheless, for ease of installation and for a bunch more amazing features I highly recommend you check out http://tutorialize.me http://tutorialize.me. Fully hosted, asynchronous, installed in minutes, full markup (mustache.js) and CSS editing, Cross browser support, and a sweet dashboard with tutorial analytics. PEACE!
danzajork 14y ago
Great work!
danzajork 14y ago
Great work!
hugofirth 14y ago
This is - quite simply - one of the coolest things I have seen in a while. "In game" tutorials are such a fantastic way of demonstrating functionality in that sector - why shouldn't websites be the same ?
bamdadd 14y ago
Cool project, love it when I see devs from Tehran publish their work on HN and become the top on the news with the current situation in Iran and the worst internet connection ever! Good job
- afshinmeh 14y ago
  Thanks for your nice comment, I think you know our situation exactly!
frozenport 14y ago
Good work. It would be cool if you could also scroll the browser window. For example, in my the I need to scroll down to see the 2nd bubble and up to see the following.
Bjoern 14y ago
Good stuff! Thanks for this. Just to put it out there, here is an alternative built on jquery. http://trentrichardson.com/Impromptu/ http://trentrichardson.com/Impromptu/
andyl 14y ago
Nice weekend project - cool! Worked fine on my laptop - a few problems on my iPad. Suggestion: enlarge the next/prev buttons. Thank you Afshinmeh and happy new year! :-)
- afshinmeh 14y ago
  Hey, thanks! Sure, I'll make that buttons better for next version.
Bjoern 14y ago
We built something similar like this based on jQuery Impromptu and merged it together with HowlerJS. This way we have a nice website walkthrough with voice if desired.
- monkeyspaw 14y ago
  Any chance you guys released that as open source? This is exactly what I want. Would be even better if it animated the boxes, so that the users eye is drawn to what you're showing them. All these projects are really impressive.
  - Bjoern 14y ago
    Sorry we haven't yet. Let me clean it up and get back with it.
js-coder 14y ago
The HN effect: Visited the project 3-4 hours ago, and it had 40 stargazers, now 650. :) I really like it by the way, and I think I'll use it for my next project. How about some events though? Like `introJs.on('5', fn)` would execute `fn` when the fifth hint is shown. It could be used to introduce several views to the user (one page app).
- afshinmeh 14y ago
  Nice, I think we can manage it better if you make an issue on our Github, so I mark it as enhancement and I'll work it for next versions.
adamgravitis 14y ago
Regarding usabili.ca, the domain you're using... If you're "three geeks in Tehran", you really shouldn't be using a Canadian domain. Unless you're Canadians, or are incorporated within Canada. Just saying.
- alphakappa 14y ago
  Unnecessary. There are plenty of .in or .it domains that have nothing to do with India or Italy. It's just a domain name and it's inevitable that people will use it in new ways.
  - davefp 14y ago
    Not all country-level TLDs are administered in the same way. According to Wikipedia, there are no restrictions on .in domains, and .it domains are only available to EU residents. http://en.wikipedia.org/wiki/.in http://en.wikipedia.org/wiki/.in http://en.wikipedia.org/wiki/.it http://en.wikipedia.org/wiki/.it CIRA, who manage .ca domains, have stricter rules. They can be found here: http://www.cira.ca/why-ca/ca-101/who-can-register-a-ca/ http://www.cira.ca/why-ca/ca-101/who-can-register-a-ca/
dave_sid 14y ago
Really nice idea. will use this and have a 'tutorial' button at the top of my page to trigger it.
eranation 14y ago
I was trying to build something like this and what stopped me from finishing it was handling z-index of different stacking contexts, I couldn't make it work on all cases, from the code it seems you put a very high z-index to the displayed section, which was my approach as well, but on different stacking contexts, I found out that sometimes no matter how high is your z-index, it will still be dependent on the parent stacking context, I guess I could have just released it (it was a jQuery plugin) as it was probably going to work for 99% of the use cases. Great work in any case!
donniefitz2 14y ago
This is just the sort of thing I've wanted to add to my web app. Great work!
dested 14y ago
Great project!!
joshmattvander 14y ago
well done!
arrowgunz 14y ago
This is so cool.
jv22222 14y ago
Really nice job, well done.
Mahn 14y ago
Very nicely done. I find interesting how an intro of this kind makes clearer information that is already to be found within the site itself; it doesn't create new information, it just forces the user to focus on the different areas of the site. I can't help but think we are trained to ignore when we can't see what's on the screen unless the site forces focus over the different areas.
Smudge 14y ago
I was recently part of a brainstorming session where it was decided that we needed something that could do exactly this. (The way we described it: something like the "Joyride" feature in Zurb Foundation, except it could also highlight the relevant section.) Keep this simple and fix a few of the bugs, and I think you have a winner.
- afshinmeh 14y ago
  Hhm, nice. It's the first version of IntroJs, I'll fix the bugs asap.
photorized 14y ago
Brilliant. I needed something that could easily explain application workflow to the customer - and this is it! Thank you.
mrgreenfur 14y ago
There are a bunch of tutorials as a service companies out there. Awesome to see one as F/OSS though! Nicely done!
mikeleeorg 14y ago
Neat! Fantastic first version! It has lots of potential. I love how it's not tied to jQuery. And I agree with what some of the others have said - it's possible you could build a freemium service with this. I don't know how ample that opportunity is though. Here's another feature request to your list too: Have the word bubbles remain in the viewport, or scroll so they are always in view.
javajosh 14y ago
I would suggest using the non-minified version of your library on the demo page, because programmers like me will want to look at the source in the fastest way possible, which is in the browser. (Your library is so small I don't think it will make much of a difference to bandwidth, and anyway you are cleverly using github as your static host.) Nice work.
- afshinmeh 14y ago
  Yeah cool. So I will change the resources to non-minified version.
Jeremy1026 14y ago
Falls apart on IE7. Love what you've done though. (Note to employer, UPGRADE MY COMPUTER)
- afshinmeh 14y ago
  Working on old browsers is a big change in the next version of IntroJs.
  - Jeremy1026 14y ago
    Very cool. I'll be following this project. It has some very good points so far. Cleaning it up a little will make it that much better.
ckarmann 14y ago
"Currently for Modern Browsers only". Can you be more specific? No IE? IE from version 9? 10?
- alecdibble 14y ago
  There is only one way to find out.
  - afshinmeh 14y ago
    Sorry for bad README, I'll complete it asap.
mcintyre1994 14y ago
Very almost perfect. The only issue I have is with its scrolling - when it scrolls down it only scrolls enough to show the highlighted area, not the textbox underneath it with information. 1366x768 resolution if that matters.
cyrilga 14y ago
Amazing work, mate! I will definitely use it really soon on Javascript 2d Games to show how to play the games. If you are looking at monetizing it, you could sell it as a plugin for Crafty.js for instance
- afshinmeh 14y ago
  Good news! Let me know when you use it.
muyuu 14y ago
Great to see some proper Irani geeks doing good stuff. Does this work in mobile browsers? maybe a compatibility table in the front page?
stinky613 14y ago
I like it. I'd recommend that you make a block link out of the text bubble that contains your 'next' link. Honing in on the actual word 'next' slowed me down. For especially... uninitiated (?) web/computer users I could see there being an issue wherein the text bubble containing 'next' is cut off by the bottom boundary of the browser window. Just recently I had to make a series of screenshots to walk someone through something. Great weekend project.
- afshinmeh 14y ago
  Yeah that's a mistake, you're correct. I'll fix it.
donnfelker 14y ago
I love it. I wish the next and skip links were larger so it would look good on a mobile device. :)
vicks711 14y ago
Just one suggestion. The page should scroll automatically so that the focus area is completely visible.
droncancio 14y ago
great work, i feel like the rest the next link is to small, and even if you try to navegate with arrows <-, -> and works some other mechanic like (enter/click/tap) to keep going and then (esc/del/back) to avoid the intro, but its a great aid as it is right now a friend of me built something like this (not that good), from zero to his app but now everyone can have this, going to recommend it.
coldtea 14y ago
And it's from a guy in Tehran according to the meta info. I'm pointing to this, because, even in tech forums I follow, some people believe Iranians are evil and they should be nuked or something. Don't confuse what your local media say for each country (and how they choose to present it) with what the country actually is. Don't even judge by the government of the other country (would Americans like to be judged by Bush or Nixon? Maybe Kissinger and Rove?). And don't judge by your pre-determined cultural notions either. As a European, I abhor the death penalty, the practice of executing 15 year old children and protestant bible thumpers. Still I find the people of Texas mighty fine, including those that agree with those things, and not just the SXSW crowd. So I can also understand people in Iran (or whatever) having their own culture, religious etc and being backwards (to my view) in some regards. Unless a country has done specific, unprovoked and tangible harm to another country, there is no reason to hate it at all. As for what happens INSIDE the country, it's mostly their thing to deal with.
- nfg 14y ago
  If you're from a country with a decent visa situation (I.e. not the US or UK) I'd really recommend visiting Iran, its incredible and full of the friendliest people I've had the privilege to meet.
  - afshinmeh 14y ago
    thanks thanks!
- devcpp 14y ago
  I've never once in my life met a person that sincerely thinks that each and every inhabitant of a country is evil when their leaders are. By the way, "Iranians are evil" does not count, as it generally implies "most Iranians are evil", which, if you count it as a democracy (it is to some extent) and consider the elected leaders to be evil (a reasonable claim from a particular perspective), would be true.

716 points by afshinmeh 14y ago

moe 14y ago

As others have already suggested: I think it would be even better if the explanation box was fixed (e.g. top left corner of the screen) and had a FAT red arrow pointing to the area of the screen that it explains. This would (imho) make it more obvious what's going on ("Ah, this is explaining that") and would improve usability. But either way, this is a great start (I love the limelight-effect) and we are definitely going to build on this. Thank you for open sourcing it!

acmecorps 14y ago

Superbly awesome work, afshinmeh! :D

przemoc 14y ago

Nice but lacks automatic scrolling to guarantee visibility of highlighted part and comment.

afshinmeh 14y ago
Yeah I just used a JavaScript method `scrollIntoViewIfNeeded` to scroll the page to the target element but it works in modern browsers AFAIK.
- przemoc 14y ago
  I'm using Iceweasel straight from debian wheezy repository, i.e. Firefox 10. IMO not old enough to be not supported, but YMMV.
- mediumdeviation 14y ago
  As far as I can tell it's a non-standard Webkit function. See https://bugzilla.mozilla.org/show_bug.cgi?id=403510 https://bugzilla.mozilla.org/show_bug.cgi?id=403510 and https://gist.github.com/hsablonniere/2581101 https://gist.github.com/hsablonniere/2581101

coffeeyesplease 14y ago

Very good, love the idea.

afshinmeh 14y ago
Thanks :]

padwan 14y ago

Nice and simple. Would be great if this worked over multiple pages.

afshinmeh 14y ago
Thanks. What you mean by "multiple pages"?
- tzaman 14y ago
  He means that if intro instructs the user click here, and the browser goes to another page from within the same intro scope, then intro would pick up and continue.
  - padwan 14y ago
    Something like that yes :) Maybe step 1-3 is on "start.html" and step 4-6 is on "anotherpage.html". So when the user clicks next from step 3, he should be redirected to anotherpage.html and the intro continues.
    - afshinmeh 14y ago
      I got it, I got it. Good idea, I think you submitted an issue on Github also, right? Thanks for the awesome suggestion, in the next versions we will have that also.
      - born2web 14y ago
        +1 - ability to guide a user through multiple pages would definitely be useful. Anyways, thanks a lot for a great contribution.

benharrison 14y ago

I really like this. I think it would be neat to see a discrete help button or toggle switch, that allows novice users to go into a help mode overlayed on top of a live web app.

afshinmeh 14y ago
For the next versions I'll add it so. Thanks for suggestion.

felix 14y ago

Nicely done. Bonus points for not making it a jQuery plugin!

afshinmeh 14y ago
VanillaJs!

spobin 14y ago

I've been looking for something like this for a while now. Brilliantly executed, thanks! I'll definitely be trying it out on my next project.

afshinmeh 14y ago
Whoho, Thanks :)

avel 14y ago

A nice alternative is Zurb Joyride: http://www.zurb.com/playground/jquery-joyride-feature-tour-plugin http://www.zurb.com/playground/jquery-joyride-feature-tour-p... http://foundation.zurb.com/docs/components/joyride.html http://foundation.zurb.com/docs/components/joyride.html

afshinmeh 14y ago
Yeah but it works with jQuery. What if I don't want to add jQuery to my page? IntroJs built with pure JavaScript.
- ineedtosleep 14y ago
  Sure, if you don't want to have jQuery as a dependency intro.js is probably the winner. However, do note that Foundation's javascript plugins also work with Zepto[1][2] which weighs in at under 10k gzipped. [1] http://foundation.zurb.com/docs/javascript.html http://foundation.zurb.com/docs/javascript.html [2] http://zeptojs.com/ http://zeptojs.com/
xpose2000 14y ago
I was about to post this link myself. I'm not quite sure which one is better. I tend to like the Intro.js page fade animation. Although JoyRide 2 actually scrolls to the highlighted object, whereas intro.js does not.
mos2 14y ago
I think the work done here is fansastic and presents a great alternative to the zurb joyride / jquery or zepto combination. I agree with some of the other comments about the usability on an ipad and mobile device as well as scrolling the screen to the focused element. I think larger targets would really help with this. At this point in its development, if you are able to use jQuery or Zepto I think that Joyride 2 offers a much better UI / UX especially if you are planning to use Foundation 3/4.
- afshinmeh 14y ago
  I'm also agree with you about the size of `next` and `skip` button. I'll fix it asap.

lukifer 14y ago

Great concept and execution! One item of feedback: the styling of the numbers look nearly identical to the feedback badge on iOS, which made me think for a second that it was some sort of alert, rather than a step in a sequence. Obviously the styling is customizable by the developer, but as a default, I could see it being confusing to iOS users. Edit: one more tidbit: resizing the browser doesn't force the box(es) to resize. Admittedly an edge case. :)

afshinmeh 14y ago
Yeah correct, there's a problem when you resize the browser. In the next versions I calculate all box(s) position again to keep focus element helper layer updated.

ceeK 14y ago

Very nice indeed, looks very well done!

racbart 14y ago

This is very nice but I have some suggestions to improve: Navigation: The “next” link is very small and it's in different place on every step. A fixed navigation and/or bigger link would be nice. Also, showing me that it's “Step 3” is useless to me - I can count myself and even if I couldn't, I don't really care how many steps I've already seen. I'm more interested in how many more there are. There should also be automatic scrolling so that I could actually see the next highlighted area. If you already do the scrolling, remember to scroll in a way that guarantees to show whole area, not only top line. Thanks for the great work, I think I might use it in my next projet!

afshinmeh 14y ago
Thanks buddy. I think I'll have those features for next version.
matthuggins 14y ago
I felt the same about the numbers appearing. It reminded me of the numbers that appear on my Facebook notifications/messages, and it made me feel like I needed to click/take some action with the number itself. It didn't really add anything to the experience though. Other than that, I liked it. I especially appreciated the animated transition to the next step, where the "spotlight" flowed & resized forcing my eyes to follow.
dmragone 14y ago
Agreed - came to comments to say the numbers aren't necessarily, and the navigation is unclear (though I just used keyboard arrow keys)
ehsania 14y ago
i think numbers in some cases are necessary. but can be optional.
- afshinmeh 14y ago
  yeah we should have a config method.

niggler 14y ago

Looks very cool but the fact that you have to hit the tiny "next" link makes it hard to use on iPad. It's compounded by the fact that the page isn't scrolling down all the way from step 1 to step2 so you have to scroll down manually. On the computer, though, this looks slick and works reasonably well. Good job!

afshinmeh 14y ago
We're working to prepare the next version for iPad and other touch devices also.

meerita 14y ago

My suggestion: take all the presentation. Make it less graphical and more scalable, lets say i dont want red circle with number i want just the overlay part. Looks good and I will use it no doubt!

afshinmeh 14y ago
Ok, good. I think I should add a config function to prevent some features, red circles for example.
- meerita 14y ago
  That would make it. The problem is just that: designers doesn't want anything default. They like to customize to the extreme, take, put, etc. Keep going nice work!

nachteilig 14y ago

Thanks. I like what seems to be the differentiating feature here -- highlighting the actual elements on the page rather than pointing at it. I'm looking forward to the pull requests that fix some of the style issues (next button etc, as mentioned already).

afshinmeh 14y ago
Great. Pull-requests are welcome.

dubcanada 14y ago

Overall though its nice to see a non jQuery plugin! And it's very nicely done. Could use some finessing, on Opera there appears to be a white square/rectangle that appears on the next element for the second and third ones (not sure why). Then it disappears. Maybe it's an Opera thing. The styles that get applied to the element inside of the "white box" get applied before the white box moves. This is noticeable for the links in the top right. They turn light blue before the box even moves. It should be after the box has moved, since that kind of stuff is pretty much instant.

nkozyra 14y ago
Just curious ... why is it nice to see a non-jQuery plugin? Isn't the point of jQuery that it's tested and standardized for all browsers, thus theoretically reducing the odds that a plugin won't work on any given browser?
- jgeerts 14y ago
  Probably the fact that you don't have to use jQuery if you don't want to.
  - Hovertruck 14y ago
    Yep. We're primarily built using the Closure library so it's nice to not have to bundle jQuery for third-party libs.

deleted 14y ago

[deleted]

drd 14y ago

Afshin, I think it would be good if you add an example (usecase, scenario, etc.) to the website for a quick introduction of the functionality.

afshinmeh 14y ago
Sure yeah. I'll add it so. Thanks.

kmfrk 14y ago

Place the Next and Prev buttons on a fixed position that doesn't change - for touch devices probably at 50% height, unless they block a tooltip. The current implementation feels more like a whack-a-mole game than a guided tour. :)

afshinmeh 14y ago
It's the first version! Let us complete it and help me with your suggestions. Thanks buddy.
jliechti1 14y ago
Agreed. That, or put a small reminder on the first step (or on each step) that lets users know they can use the arrow keys. Seeing the arrow in 'Next→' was not intuitive for me (if that was intended to convey that you can change steps with →).
deleted 14y ago
[deleted]

Inversechi 14y ago

Awesome - well done :) I'm loving this!

voodoomagicman 14y ago

How do you achieve the effect of the rounded corner box w/ box-shadow masking the overlay, but allowing content to show through?

jgeerts 14y ago
It's hosted on github, go and take a look ;).
- voodoomagicman 14y ago
  Ahh, was looking for some new css property - it looks like it just sets position:relative on the content it wants to highlight, and then uses z-index.
  - afshinmeh 14y ago
    Yeah yeah. I didn't find better way for doing that.

voltagex_ 14y ago

Submitted a pull request with some basic copy-editing for you.

afshinmeh 14y ago
Thanks, merged.

davefp 14y ago

I'm curious, what connection to Canada does a Tehran-based web development company have? http://www.cira.ca/why-ca/ca-101/who-can-register-a-ca/ http://www.cira.ca/why-ca/ca-101/who-can-register-a-ca/

gregmolnar 14y ago
I am also curious. Why do you feel the need to ask this question? Are envy because the guy made a nice tool or what?
- afshinmeh 14y ago
  Off topic I think.
  - gregmolnar 14y ago
    Sorry, you are right :). Thanks for the plugin by the way!
    - afshinmeh 14y ago
      Use it buddy :) I spent all of my weekend time to built it and I just published it open-sourced.
- davefp 14y ago
  Not at all, I just find it odd. Having a fancy URL is great, but the restrictions in place on certain domains are there for a reason and should be respected.
windsurfer 14y ago
Maybe the domain is being rented from an individual who lives in Canada?
gruseom 14y ago
What connection does bit.ly have to Libya?

jQueryIsAwesome 14y ago

You are changing the z-index of the "focused" element but you need to check if one of the parents have z-index defined already because in that case the effect doesn't work. Instead of looking for a workaround I would suggest that since you are already aiming for modern browsers maybe you should use SVG (clip-path) with CSS {pointer-events: none} so you have a real "hole" and you could use 4 dummy divs if you want to disable interaction with non-focused elements.

acoleman616 14y ago
It depends on the complexity of the highlighted element, but you could also just clone & absolute-position said element.
- jQueryIsAwesome 14y ago
  That can become a PITA if you want to preserve events and CSS in the focused element.

quizotic 14y ago

Wow. Wow. Wow. What a great way to do an on-site tutorial. Thank you!!

posabsolute 14y ago

Hey, we have been looking to integrate a solution like this in our product, I got a couple of suggestions. First, using data attribute is too intrusive, a json object would have been much better, we just cannot add these attributes everywhere in our app. Using a json object would also make it possible for anyone to create a UI tool for creating guides. Also a "scenario" concept would be nice, having the ability to have multiple scenarios in a page is essential for a support team. Last thing, the UX is fantastic, it's clean and simple :)

afshinmeh 14y ago
Aha, good idea for JSON (but I think attribute is a good one for some frameworks like ExtJs that you don't know your element id or something like that). What you need by "senario"? Could you please explain it more? Thanks anyway.
- posabsolute 14y ago
  Yea, the support team want multiple scenarios (intros) in a page, we use a param, so they can link to it and push them to users asking how to do stuff, it becomes for us like an advanced, usable, faq system

diego_moita 14y ago

Brilliant and almost perfect. I will incorporate it into my project, next week. Thank you so much. Most people here are asking for more features. Please be careful with that; it would be a pity to see such a pearl to swell into bloatware. You have very good taste, let it be your guide.

crimsonzagar 14y ago
With under 4kb js and 2kb css I guess it is pretty far from being a bloat.
thom 14y ago
You could potentially build a commercial version of this on the same technology, if you wanted to keep the core of it lean. I know several people that would pay money to have this plus analytics about user progress and drop outs, user feedback etc.
- ChrisCinelli 14y ago
  Somebody already thought about it: walkme.com
  - bmelton 14y ago
    Or HN's own, https://taurus.io/ https://taurus.io/
    - thom 14y ago
      Thanks for both the pointers!
      - bmelton 14y ago
        I can't speak to the other one, but I will go on to say that Taurus is moving very fast. I was an early adopter, and while I don't use them anymore, I saw them go from a barebones product, to a barebones product with an on-site tutorial builder, to a fairly rich product with customizable themes, etc., in just a few weeks. I can't speak for what they've done since I stopped using them, but looking at their homepage, the velocity still seems pretty high.

cturhan 14y ago

Good job. In past I wrote something like this but it was just to save the day, therefore I didn't have a chance to publish.

haddr 14y ago

This is piece of brilliant work! When I saw it I suddenly got the idea I have to use it the project I'm working on. Thanks!

pchekuri 14y ago

this is simply brilliant.

ehmuidifici 14y ago

Awesome project, this plugin is great to do "howtos" and online interactive manuals. Cheers!

prakashk 14y ago

Very nice! Just one thing. I pressed the Enter key thinking that it would take me to the next step (like the right-arrow), but the page background went darker. And, each successive press of Enter made it even darker. I actually liked the effect (even if it was unintended) as it increased the contrast between the step being focused and the rest of the page. However, I found no way to get back to original page after all the steps are completed (by right-arrow navigation). Pressing ESC had no effect. Edit: Using Firefox 20.0 on Ubuntu Lucid.

taoufix 14y ago
Same here, using Firefox 19 on Windows XP. You can go back to normal by clicking with the mouse, the more you click the brighter it gets.
- afshinmeh 14y ago
  And I ask again, it's very very helpful if you report a bug to our Github.
davidradcliffe 14y ago
The script probably just needs to check if it is already running before starting.
afshinmeh 14y ago
Thanks, could you please report this problem to the Github issues?

acjohnson55 14y ago

This is AWESOME! I'm totally going to use it in my project

bamazizi 14y ago

Congrats Afshin

afshinmeh 14y ago
Hey thanks :) I glad to see your comment here.
- bamazizi 14y ago
  your project is such a great idea, we're going to use it at theRedPin.com keep me updated on your other projects. i may have more works for you very proud of you.
  - afshinmeh 14y ago
    Thanks Bamdad Jan :) I glad to hear that you want to use it.

floydpink 14y ago

Nifty little thing! Thank you. :)

cemregr 14y ago

AWESOME! The next button could be way bigger though, I felt like I was trying to catch it every time :) And maybe you can pre-focus on it with JS, so you'd give users the affordance that they can press enter to move on. (You enabled the right arrow key, but I didn't immediately know I could do it).

abailin 14y ago

Look great for super lightweight tutorials. If you need to customize more, http://tutorialize.me http://tutorialize.me is my favorite.

lshemesh 14y ago
Thanks abailin for plugging my startup! Guys this solution is really cool, and I love the "spotlighting" animation. When it comes to flexibility you definitely cannot compete with implementing a simple library like this. Nevertheless, for ease of installation and for a bunch more amazing features I highly recommend you check out http://tutorialize.me http://tutorialize.me. Fully hosted, asynchronous, installed in minutes, full markup (mustache.js) and CSS editing, Cross browser support, and a sweet dashboard with tutorial analytics. PEACE!

danzajork 14y ago

Great work!

danzajork 14y ago

Great work!

hugofirth 14y ago

This is - quite simply - one of the coolest things I have seen in a while. "In game" tutorials are such a fantastic way of demonstrating functionality in that sector - why shouldn't websites be the same ?

bamdadd 14y ago

Cool project, love it when I see devs from Tehran publish their work on HN and become the top on the news with the current situation in Iran and the worst internet connection ever! Good job

afshinmeh 14y ago
Thanks for your nice comment, I think you know our situation exactly!

frozenport 14y ago

Good work. It would be cool if you could also scroll the browser window. For example, in my the I need to scroll down to see the 2nd bubble and up to see the following.

Bjoern 14y ago

Good stuff! Thanks for this. Just to put it out there, here is an alternative built on jquery. http://trentrichardson.com/Impromptu/ http://trentrichardson.com/Impromptu/

andyl 14y ago

Nice weekend project - cool! Worked fine on my laptop - a few problems on my iPad. Suggestion: enlarge the next/prev buttons. Thank you Afshinmeh and happy new year! :-)

afshinmeh 14y ago
Hey, thanks! Sure, I'll make that buttons better for next version.

Bjoern 14y ago

We built something similar like this based on jQuery Impromptu and merged it together with HowlerJS. This way we have a nice website walkthrough with voice if desired.

monkeyspaw 14y ago
Any chance you guys released that as open source? This is exactly what I want. Would be even better if it animated the boxes, so that the users eye is drawn to what you're showing them. All these projects are really impressive.
- Bjoern 14y ago
  Sorry we haven't yet. Let me clean it up and get back with it.

js-coder 14y ago

The HN effect: Visited the project 3-4 hours ago, and it had 40 stargazers, now 650. :) I really like it by the way, and I think I'll use it for my next project. How about some events though? Like `introJs.on('5', fn)` would execute `fn` when the fifth hint is shown. It could be used to introduce several views to the user (one page app).

afshinmeh 14y ago
Nice, I think we can manage it better if you make an issue on our Github, so I mark it as enhancement and I'll work it for next versions.

adamgravitis 14y ago

Regarding usabili.ca, the domain you're using... If you're "three geeks in Tehran", you really shouldn't be using a Canadian domain. Unless you're Canadians, or are incorporated within Canada. Just saying.

alphakappa 14y ago
Unnecessary. There are plenty of .in or .it domains that have nothing to do with India or Italy. It's just a domain name and it's inevitable that people will use it in new ways.
- davefp 14y ago
  Not all country-level TLDs are administered in the same way. According to Wikipedia, there are no restrictions on .in domains, and .it domains are only available to EU residents. http://en.wikipedia.org/wiki/.in http://en.wikipedia.org/wiki/.in http://en.wikipedia.org/wiki/.it http://en.wikipedia.org/wiki/.it CIRA, who manage .ca domains, have stricter rules. They can be found here: http://www.cira.ca/why-ca/ca-101/who-can-register-a-ca/ http://www.cira.ca/why-ca/ca-101/who-can-register-a-ca/

dave_sid 14y ago

Really nice idea. will use this and have a 'tutorial' button at the top of my page to trigger it.

eranation 14y ago

I was trying to build something like this and what stopped me from finishing it was handling z-index of different stacking contexts, I couldn't make it work on all cases, from the code it seems you put a very high z-index to the displayed section, which was my approach as well, but on different stacking contexts, I found out that sometimes no matter how high is your z-index, it will still be dependent on the parent stacking context, I guess I could have just released it (it was a jQuery plugin) as it was probably going to work for 99% of the use cases. Great work in any case!

donniefitz2 14y ago

This is just the sort of thing I've wanted to add to my web app. Great work!

dested 14y ago

Great project!!

joshmattvander 14y ago

well done!

arrowgunz 14y ago

This is so cool.

jv22222 14y ago

Really nice job, well done.

Mahn 14y ago

Very nicely done. I find interesting how an intro of this kind makes clearer information that is already to be found within the site itself; it doesn't create new information, it just forces the user to focus on the different areas of the site. I can't help but think we are trained to ignore when we can't see what's on the screen unless the site forces focus over the different areas.

Smudge 14y ago

I was recently part of a brainstorming session where it was decided that we needed something that could do exactly this. (The way we described it: something like the "Joyride" feature in Zurb Foundation, except it could also highlight the relevant section.) Keep this simple and fix a few of the bugs, and I think you have a winner.

afshinmeh 14y ago
Hhm, nice. It's the first version of IntroJs, I'll fix the bugs asap.

photorized 14y ago

Brilliant. I needed something that could easily explain application workflow to the customer - and this is it! Thank you.

mrgreenfur 14y ago

There are a bunch of tutorials as a service companies out there. Awesome to see one as F/OSS though! Nicely done!

mikeleeorg 14y ago

Neat! Fantastic first version! It has lots of potential. I love how it's not tied to jQuery. And I agree with what some of the others have said - it's possible you could build a freemium service with this. I don't know how ample that opportunity is though. Here's another feature request to your list too: Have the word bubbles remain in the viewport, or scroll so they are always in view.

javajosh 14y ago

I would suggest using the non-minified version of your library on the demo page, because programmers like me will want to look at the source in the fastest way possible, which is in the browser. (Your library is so small I don't think it will make much of a difference to bandwidth, and anyway you are cleverly using github as your static host.) Nice work.

afshinmeh 14y ago
Yeah cool. So I will change the resources to non-minified version.

Jeremy1026 14y ago

Falls apart on IE7. Love what you've done though. (Note to employer, UPGRADE MY COMPUTER)

afshinmeh 14y ago
Working on old browsers is a big change in the next version of IntroJs.
- Jeremy1026 14y ago
  Very cool. I'll be following this project. It has some very good points so far. Cleaning it up a little will make it that much better.

ckarmann 14y ago

"Currently for Modern Browsers only". Can you be more specific? No IE? IE from version 9? 10?

alecdibble 14y ago
There is only one way to find out.
- afshinmeh 14y ago
  Sorry for bad README, I'll complete it asap.

mcintyre1994 14y ago

Very almost perfect. The only issue I have is with its scrolling - when it scrolls down it only scrolls enough to show the highlighted area, not the textbox underneath it with information. 1366x768 resolution if that matters.

cyrilga 14y ago

Amazing work, mate! I will definitely use it really soon on Javascript 2d Games to show how to play the games. If you are looking at monetizing it, you could sell it as a plugin for Crafty.js for instance

afshinmeh 14y ago
Good news! Let me know when you use it.

muyuu 14y ago

Great to see some proper Irani geeks doing good stuff. Does this work in mobile browsers? maybe a compatibility table in the front page?

stinky613 14y ago

I like it. I'd recommend that you make a block link out of the text bubble that contains your 'next' link. Honing in on the actual word 'next' slowed me down. For especially... uninitiated (?) web/computer users I could see there being an issue wherein the text bubble containing 'next' is cut off by the bottom boundary of the browser window. Just recently I had to make a series of screenshots to walk someone through something. Great weekend project.

afshinmeh 14y ago
Yeah that's a mistake, you're correct. I'll fix it.

donnfelker 14y ago

I love it. I wish the next and skip links were larger so it would look good on a mobile device. :)

vicks711 14y ago

Just one suggestion. The page should scroll automatically so that the focus area is completely visible.

droncancio 14y ago

great work, i feel like the rest the next link is to small, and even if you try to navegate with arrows <-, -> and works some other mechanic like (enter/click/tap) to keep going and then (esc/del/back) to avoid the intro, but its a great aid as it is right now a friend of me built something like this (not that good), from zero to his app but now everyone can have this, going to recommend it.

coldtea 14y ago

And it's from a guy in Tehran according to the meta info. I'm pointing to this, because, even in tech forums I follow, some people believe Iranians are evil and they should be nuked or something. Don't confuse what your local media say for each country (and how they choose to present it) with what the country actually is. Don't even judge by the government of the other country (would Americans like to be judged by Bush or Nixon? Maybe Kissinger and Rove?). And don't judge by your pre-determined cultural notions either. As a European, I abhor the death penalty, the practice of executing 15 year old children and protestant bible thumpers. Still I find the people of Texas mighty fine, including those that agree with those things, and not just the SXSW crowd. So I can also understand people in Iran (or whatever) having their own culture, religious etc and being backwards (to my view) in some regards. Unless a country has done specific, unprovoked and tangible harm to another country, there is no reason to hate it at all. As for what happens INSIDE the country, it's mostly their thing to deal with.

nfg 14y ago
If you're from a country with a decent visa situation (I.e. not the US or UK) I'd really recommend visiting Iran, its incredible and full of the friendliest people I've had the privilege to meet.
- afshinmeh 14y ago
  thanks thanks!
devcpp 14y ago
I've never once in my life met a person that sincerely thinks that each and every inhabitant of a country is evil when their leaders are. By the way, "Iranians are evil" does not count, as it generally implies "most Iranians are evil", which, if you count it as a democracy (it is to some extent) and consider the elected leaders to be evil (a reasonable claim from a particular perspective), would be true.