dotnetco.de

I fully agree with this quote from StartupVitamins: A user interface is like a joke. If you have to explain it, it’s not that good!

But it might happen that you need to have some kind of complexity which might be overwhelming for some users. So it’s of course a good idea to give as many helpful information as possible. But who reads manuals? …. Exactly. So nowadays it is (with good reason) expected by the users to have some kind of interactive guidelines. Of course there are several solutions, free and paid.

Hopscotch is a children’s game that can be played with several players or alone, but in currently article I’ll share some information about the Hopscotch framework created by the developers of business network LinkedIn. This Hopscotch helps you creating product tours on your website. So let’s see how to add a multipage tour to your asp.net website using asp.net Masterpages. Note: All helpful scripts are added at the end of this article.

Add files to your webproject

First of course download the latest master.zip from Hopscotchs Github page. Currently it’s release 0.2.3. Extract the zip and add the files from the dist-folder to your application:

• /dist/css/hopscotch.min.css
• /dist/img/sprite-green.png
• /dist/img/sprite-orange.png
• /dist/js/hopscotch.min.js

If you put the images to another folder you have to update the path in hopscotch.min.css of course. Hopscotch automatically detects whether YUI or jQuery is present and uses them, but it’s not required. So no further settings are necessary.

Reference them

As I use a Masterpage on my example I add the references there:

<link rel="stylesheet" href="css/hopscotch.min.css"></link>

 

into the head of the masterpage.

<script type="text/javascript" src="js/hopscotch.min.js"></script>

at the top of the body. It’s important to add it to the top because later on we will add the tours on the single webpages and therefore Hopscotch main has to be referenced before the tours are referenced.

Create Webpages

Now create 2 webpages using a Masterpage. I’ve named them Hopscotch1.aspx and Hopscotch2.aspx. Of course the Webpages should contain some text, so add some paragraphs and headlines etc. For the test you might use a Blind Text Generator. It’s important to add some IDs which could be found by Hopscotch later on, e.g.

<h3 id="Start">Start here</h3>
<span id="Second">Mittwoch</span>

Also add a button so the user could manually start the tour….

Create your first tour

For the first tour we will stay on a single page. You could simply copy the script from Hopscotch example and modify it according to your IDs. Copy the script into a new separate JavaScript file, e.g. HSTour1.js. Add a reference to this script into your Hopscotch1.aspx at the bottom of the body.

Start the first tour

Ok, everything embedded and reference but it does not work. Why? Because the button

<button id="startTourBtn">Try it out!</button>

used in the example tour does not work in asp.net. If you click on it a postback to the server will be done, but that’s not what we want. So the fix is simple: Remove the button and instead create e.g. a span element with this id:

<span id="startTourBtn">Start Tour</span>

 

Of course you could design the element as you want, maybe it should be displayed like a button if you want. Now everything works as expected!

Multipage tour

There is already an example available so we check whether we could use it. First get a new text to fill Hopscotch2.aspx. Again enter some IDs to be used by Hopscotch. I’ve then copied HSTour1.js into a new HSTour2.js. The following things need to be updated in HSTour2.js then (the renaming only needs to be done if you want to have both tours enabled):

• Change the variable ‘tour’ in 3 lines
• Change the name of the tour (‘hello-hopscotch’) in 2 lines
• Add the Multipage-option to the second step
• Add some steps to be shown on Page 2 then
• Add the new Javascript HSTour2.js to both pages, Hopscotch1.aspx and Hopscotch2.aspx

Take care: hopscotch.getState() returns the current tour name and the current step. So in my example I had 2 steps before so at hopscotch.getState() i have to change the expected step from ‘:1’ to ‘:2’.

That’s it!

So now we have single-page and a multi-page Hopscotch-Tour on our aspx pages using Masterpages. As long as you avoid the little pitfalls (don’t use a button, rename parameters in all lines if you use several tours on a page) it is very easy to configure and handle. See the Github Page for more options.

Source code

Here is the source code used in this project. The Hopscotch-Files could be retrieved from the Github page.

Site1.master

<%@ Master Language="VB" AutoEventWireup="false" CodeBehind="Site1.master.vb" Inherits="WebApplication1.Site1" %>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title></title>
    <link rel="stylesheet" href="css/hopscotch.min.css"></link>
    <asp:ContentPlaceHolder ID="head" runat="server">
    </asp:ContentPlaceHolder>
    
</head>
<body>
    <form id="form1" runat="server">
    <script type="text/javascript" src="js/hopscotch.js"></script>
    <div>
        <asp:ContentPlaceHolder ID="ContentPlaceHolder1" runat="server">
        
        </asp:ContentPlaceHolder>
    </div>
    
    </form>
</body>
</html>

 

Hopscotch1.aspx

<%@ Page Title="" Language="vb" AutoEventWireup="false" MasterPageFile="~/Site1.Master"
    CodeBehind="Hopscotch1.aspx.vb" Inherits="WebApplication1.Hopscotch1" %>
<asp:Content ID="Content1" ContentPlaceHolderID="head" runat="server">
</asp:Content>
<asp:Content ID="Content2" ContentPlaceHolderID="ContentPlaceHolder1" runat="server">
    <h3 id="Start">
        Start here</h3>
    <p>
        Es gibt im Moment in diese Mannschaft, oh, einige Spieler vergessen ihnen Profi
        was sie sind. Ich lese nicht sehr viele Zeitungen, aber ich habe gehört viele Situationen.
        Erstens: wir haben nicht offensiv gespielt.</p>
    <p>
        Es gibt keine deutsche Mannschaft spielt offensiv und die Name offensiv wie Bayern.
        Letzte Spiel hatten wir in Platz drei Spitzen: Elber, Jancka und dann Zickler. Wir
        müssen nicht vergessen Zickler. Zickler ist eine Spitzen mehr, Mehmet eh mehr Basler.</p>
    <p>
        Ist klar diese Wörter, ist möglich verstehen, was ich hab gesagt? Danke. Offensiv,
        offensiv ist wie machen wir in Platz. Zweitens: ich habe erklärt mit diese zwei
        Spieler: nach Dortmund brauchen vielleicht Halbzeit Pause. Ich habe auch andere
        Mannschaften gesehen in Europa nach diese <span id="Second">Mittwoch</span>.</p>
    <p>
        Ich habe gesehen auch zwei Tage die Training. Ein Trainer ist nicht ein Idiot! Ein
        Trainer sei sehen was passieren in Platz. In diese Spiel es waren zwei, drei diese
        Spieler waren schwach wie eine Flasche leer! Haben Sie gesehen Mittwoch, welche
        Mannschaft hat gespielt Mittwoch? Hat gespielt Mehmet oder gespielt Basler oder
        hat gespielt Trapattoni? Diese Spieler beklagen mehr als sie spielen! Wissen Sie,
        warum die Italienmannschaften kaufen nicht diese Spieler? Weil wir haben gesehen
        viele Male solche Spiels!</p>
        <p><span id="startTourBtn">Hier Tour 1 starten</span>!</p>
        <p><span id="startTour2Btn">Hier Tour 2 starten</span>!</p>
        <button id="startTourBtnOld">Start Now</button>
    <script type="text/javascript" src="js/HSTour1.js"></script>
    <script type="text/javascript" src="js/HSTour2.js"></script>
</asp:Content>

 

Hopscotch2.aspx

<%@ Page Title="" Language="vb" AutoEventWireup="false" MasterPageFile="~/Site1.Master"
    CodeBehind="Hopscotch2.aspx.vb" Inherits="WebApplication1.Hopscotch2" %>
<asp:Content ID="Content1" ContentPlaceHolderID="head" runat="server">
</asp:Content>
<asp:Content ID="Content2" ContentPlaceHolderID="ContentPlaceHolder1" runat="server">
<h3 id="Page2">Welcome to page 2</h3>
    <p>
        Zwei flinke Boxer jagen die quirlige Eva und ihren Mops durch Sylt. Franz jagt im
        komplett verwahrlosten Taxi quer durch Bayern. Zwölf Boxkämpfer jagen Viktor quer
        über den großen Sylter Deich. Vogel Quax zwickt Johnys Pferd Bim. Sylvia wagt quick
        den Jux bei Pforzheim.</p>
    <p>
        Polyfon zwitschernd aßen Mäxchens Vögel Rüben, Joghurt und Quark. "Fix, Schwyz!
        " quäkt Jürgen blöd vom Paß. Victor jagt zwölf Boxkämpfer quer über den großen Sylter
        Deich. Falsches Üben von Xylophonmusik quält jeden größeren Zwerg. Heizölrückstoßabdämpfung.</p>
    <p>
        Zwei flinke Boxer jagen die quirlige Eva und ihren Mops durch Sylt. Franz jagt im
        komplett verwahrlosten Taxi quer durch Bayern. Zwölf Boxkämpfer jagen Viktor quer
        über den großen Sylter Deich. Vogel <span id="AnotherInfo">Quax</span> zwickt Johnys Pferd Bim. Sylvia wagt quick
        den Jux bei Pforzheim.</p>
    <p>
        Polyfon zwitschernd aßen Mäxchens Vögel Rüben, Joghurt und Quark. "Fix, Schwyz!
        " quäkt Jürgen blöd vom Paß. Victor jagt zwölf Boxkämpfer quer über den großen Sylter
        Deich. Falsches Üben von Xylophonmusik quält jeden größeren Zwerg. Heizölrückstoßabdämpfung.
        Zwei flinke Boxer jagen die quirlige Eva und ihren Mops durch Sylt. Franz jagt im
        komplett verwahrlosten Taxi quer durch Bayern. Zwölf Boxkämpfer jagen Viktor quer
        über den großen Sylter Deich. Vogel Quax zwickt Johnys Pferd Bim. Sylvia wagt quick
        den Jux</p>
        <script type="text/javascript" src="js/HSTour2.js"></script>
</asp:Content>

 

HSTour1.js

// Define the tour!
var tour = {
    id: "hello-hopscotch",
    steps: [
        {
            title: "My Header",
            content: "This is the header of my page.",
            target: "Start",
            placement: "bottom"
        },
        {
            title: "My 2nd step",
            content: "This is the second step.",
            target: "Second",
            placement: "left"
        }
      ]
},
/* ========== */
/* TOUR SETUP */
/* ========== */
addClickListener = function (el, fn) {
    if (el.addEventListener) {
        el.addEventListener('click', fn, false);
    }
    else {
        el.attachEvent('onclick', fn);
    }
},
startBtnEl = document.getElementById("startTourBtn");
    if (startBtnEl) {
        addClickListener(startBtnEl, function () {
            if (!hopscotch.isActive) {
                hopscotch.startTour(tour);
            }
        });
    }
    else {
        // Assuming we're on page 2.
        if (hopscotch.getState() === "hello-hopscotch:1") {
            // tour id is hello-hopscotch and we're on the second step. sounds right, so start the tour!
            hopscotch.startTour(tour);
        }
    }

 

HSTour2.js

// Define the tour!
var tour2 = {
    id: "tour2-hopscotch",
    steps: [
        {
            title: "My Header",
            content: "This is the header of my page.",
            target: "Start",
            placement: "bottom"
        },
        {
            title: "My 2nd step",
            content: "This is the second step.",
            target: "Second",
            placement: "left",
            multipage: true,
            onNext: function () {
                window.location = "Hopscotch2.aspx"
            }
        },
        {
            title: "My Header on page 2",
            content: "This is the header of page 2.",
            target: "Page2",
            placement: "bottom"
        },
        {
            title: "My 2nd step on page 2",
            content: "This is the second step on page 2.",
            target: "AnotherInfo",
            placement: "top"
        }
      ]
},
/* ========== */
/* TOUR SETUP */
/* ========== */
addClickListener = function (el, fn) {
    if (el.addEventListener) {
        el.addEventListener('click', fn, false);
    }
    else {
        el.attachEvent('onclick', fn);
    }
},
startBtnEl = document.getElementById("startTour2Btn");
if (startBtnEl) {
    addClickListener(startBtnEl, function () {
        if (!hopscotch.isActive) {
            hopscotch.startTour(tour2);
        }
    });
}
else {
    // Assuming we're on page 2.
    if (hopscotch.getState() === "tour2-hopscotch:2") {
        // tour id is tour2-hopscotch and we're on the third step. sounds right, so start the tour!
        hopscotch.startTour(tour2);
    }
}