
Show HN: Weekend project, Intro.js - afshinmeh
http://usablica.github.com/intro.js/
======
diego_moita
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.

~~~
thom
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
Somebody already thought about it: walkme.com

~~~
bmelton
Or HN's own, <https://taurus.io/>

~~~
thom
Thanks for both the pointers!

~~~
bmelton
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.

------
racbart
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!

~~~
ehsania
i think numbers in some cases are necessary. but can be optional.

~~~
afshinmeh
yeah we should have a config method.

~~~
Zecc
Just give them a less "active" default color and you're halfway there. As they
are now, they seem to be asking for action. I'd also write "Step n of N" or
simply "n/N" to help clear the meaning.

Congratulations on your good work, by the way. I don't usually vote TFAs up,
but you totally deserve it.

~~~
afshinmeh
Yeah that's a good idea also. Thanks for your vote.

------
kmfrk
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. :)

~~~
jliechti1
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 →).

------
coldtea
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
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
thanks thanks!

------
avel
A nice alternative is Zurb Joyride: [http://www.zurb.com/playground/jquery-
joyride-feature-tour-p...](http://www.zurb.com/playground/jquery-joyride-
feature-tour-plugin) <http://foundation.zurb.com/docs/components/joyride.html>

~~~
afshinmeh
Yeah but it works with jQuery. What if I don't want to add jQuery to my page?
IntroJs built with pure JavaScript.

~~~
ineedtosleep
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>

[2] <http://zeptojs.com/>

------
niggler
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
We're working to prepare the next version for iPad and other touch devices
also.

------
bamdadd
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
Thanks for your nice comment, I think you know our situation exactly!

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

~~~
afshinmeh
VanillaJs!

------
javajosh
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
Yeah cool. So I will change the resources to non-minified version.

------
Bjoern
Good stuff! Thanks for this.

Just to put it out there, here is an alternative built on jquery.

<http://trentrichardson.com/Impromptu/>

------
davefp
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/>

~~~
gruseom
What connection does bit.ly have to Libya?

~~~
tptacek
Only that at one point, to purchase the rights to that domain name, they
effectively paid the Ghaddafi regime a small amount of money, and that they
run a popular service that at any time could be hijacked by the current regime
in Libya.

------
eranation
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!

------
hugofirth
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 ?

------
lukifer
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
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.

------
js-coder
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
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.

------
cemregr
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).

------
dubcanada
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
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
Probably the fact that you don't have to use jQuery if you don't want to.

~~~
Hovertruck
Yep. We're primarily built using the Closure library so it's nice to not have
to bundle jQuery for third-party libs.

------
prakashk
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
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
And I ask again, it's very very helpful if you report a bug to our Github.

------
benharrison
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
For the next versions I'll add it so. Thanks for suggestion.

------
posabsolute
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
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
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

------
frozenport
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.

------
moe
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!

------
Mahn
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.

------
stinky613
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
Yeah that's a mistake, you're correct. I'll fix it.

------
drd
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
Sure yeah. I'll add it so. Thanks.

------
spobin
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
Whoho, Thanks :)

------
mikeleeorg
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.

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

~~~
jgeerts
It's hosted on github, go and take a look ;).

~~~
voodoomagicman
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
Yeah yeah. I didn't find better way for doing that.

------
Smudge
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
Hhm, nice. It's the first version of IntroJs, I'll fix the bugs asap.

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

------
mcintyre1994
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.

------
nachteilig
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
Great. Pull-requests are welcome.

------
cyrilga
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
Good news! Let me know when you use it.

------
meerita
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
Ok, good. I think I should add a config function to prevent some features, red
circles for example.

~~~
meerita
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!

------
Bjoern
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
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
Sorry we haven't yet. Let me clean it up and get back with it.

------
droncancio
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.

------
abailin
Look great for super lightweight tutorials.

If you need to customize more, <http://tutorialize.me> is my favorite.

~~~
lshemesh
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>. Fully hosted,
asynchronous, installed in minutes, full markup (mustache.js) and CSS editing,
Cross browser support, and a sweet dashboard with tutorial analytics. PEACE!

------
haddr
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!

------
cturhan
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.

------
muyuu
Great to see some proper Irani geeks doing good stuff.

Does this work in mobile browsers? maybe a compatibility table in the front
page?

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

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

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

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

~~~
alecdibble
There is only one way to find out.

~~~
afshinmeh
Sorry for bad README, I'll complete it asap.

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

~~~
afshinmeh
Yeah I just used a JavaScript method `scrollIntoViewIfNeeded` to scroll the
page to the target element but it works in modern browsers AFAIK.

~~~
mediumdeviation
As far as I can tell it's a non-standard Webkit function. See
<https://bugzilla.mozilla.org/show_bug.cgi?id=403510> and
<https://gist.github.com/hsablonniere/2581101>

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

~~~
afshinmeh
Working on old browsers is a big change in the next version of IntroJs.

~~~
Jeremy1026
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.

------
photorized
Brilliant.

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

Thank you.

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

------
coffeeyesplease
Very good, love the idea.

~~~
afshinmeh
Thanks :]

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

~~~
afshinmeh
Thanks. What you mean by "multiple pages"?

~~~
tzaman
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
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
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
+1 - ability to guide a user through multiple pages would definitely be
useful. Anyways, thanks a lot for a great contribution.

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

~~~
afshinmeh
Thanks, merged.

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

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

------
ceeK
Very nice indeed, looks very well done!

------
acmecorps
Superbly awesome work, afshinmeh! :D

------
floydpink
Nifty little thing! Thank you. :)

------
jv22222
Really nice job, well done.

------
arrowgunz
This is so cool.

------
quizotic
Wow.

Wow. Wow.

What a great way to do an on-site tutorial.

Thank you!!

------
dested
Great project!!

------
bamazizi
Congrats Afshin

~~~
afshinmeh
Hey thanks :) I glad to see your comment here.

~~~
bamazizi
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
Thanks Bamdad Jan :) I glad to hear that you want to use it.

------
danzajork
Great work!

------
pchekuri
this is simply brilliant.

------
joshmattvander
well done!

------
jQueryIsAwesome
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
It depends on the complexity of the highlighted element, but you could also
just clone & absolute-position said element.

~~~
jQueryIsAwesome
That can become a PITA if you want to preserve events and CSS in the focused
element.

------
andyl
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
Hey, thanks! Sure, I'll make that buttons better for next version.

------
adamgravitis
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
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
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/.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/>

