Simple overlay instructions for your apps.

Overview

Chardin.js

Simple overlay instructions for your apps.

Check out a demo.

Or demo sequential stepping.

Chardin.js is a jQuery plugin that creates a simple overlay to display instructions on existent elements. It is inspired by the recent Gmail new composer tour which I loved.

chardin
Jean-Baptiste-Siméon Chardin

Installing

Simple! Fork this repo or download chardinjs.css and chardinjs.min.js and add the following assets to your HTML:

<link href="chardinjs.css" rel="stylesheet">
<script src="chardinjs.min.js"></script>

There's a chardinjs-rails gem.

Adding data for the instructions

Add the instructions to your elements:

data-intro: Text to show with the instructions/tooltip. data-position: (left, top, right, bottom), where to place the text with respect to the element. In addition you can alter the relative position of the tooltip text by placing a colon and a percentage value (-100 to 100) after the position text, eg "top:-50". This will slide the tooltip along the length or height of the element away from the centre. If you want to increae the distance of the tooltip from the element, you can do it by placing a comma and a percentage value (100, 200, 300, 400 or 500) after the tooltip offset, eg "top:0,200". This will shift the tooltip to be twice farther away from the element than by default.

<img src="img/chardin.png" data-intro="An awesome 18th-century painter, who found beauty in everyday, common things." data-position="right" />

You can also run Chardin in sequenced mode, where one element will be displayed at a time, moving on to the next with a mouse click (or automatically after a set delay). Add data-chardin-sequenced="true" entry to the body tag. Also add data-chardin-auto="true" and data-chardin-delay="100" for automatic movement through the elements. Delay is in milliseconds. The default sequence is as loaded by the DOM, but this can be overridden using the tag data-sequence with a number. If no auto-traversal is set, clicking will move sequentially through the elements, clicking with the shift key down will move backwards through them.

<body data-chardin-sequenced="true" data-chardin-auto="false" data-chardin-delay="800" >

Running

Once you have your elements ready, initialise the library and assign it to a button that the user will click to show the overlay. The library will store an initialised object to the containing element's data set so you can start and stop it with whatever options you set.

$('body').chardinJs();
$('body').on('click', 'button[data-toggle="chardinjs"]', function (e) {
    e.preventDefault();
    return ($('body').data('chardinJs')).toggle();
});

You can run it explicitly like so:

$('body').chardinJs('start')

If you would rather run ChardinJs confined to a particular container (instead of using the whole document) you can change body to some other selector.

$('.container').chardinJs('start')

You may also refresh instructions overlay any time to reflect whatever changes happened to the underlying page elements since the instructions overlay has been displayed.

var chardinOverlay = $('body').chardinJs('start');
...
chardinOverlay.refresh();

Options

The chardinJS constructor can take several options, eg:

$('body').chardinJs({ url: "/help/HelpOverlay.json" });

Options are:

  • url: specifies a url that returns a json object containing text to show. This is useful to dynamically change the overlay, or to hold all your overlay text in one external file. The json file should contain a set of name-value pairs, the name will match the data-intro attribute if it begins with a '#'. The value contains the required text and an optional position. For conflicts between the data attributes and the json entries, the attribute takes precedence.

Example:

{
    "#summary-btns": {
        "text": "buttons to interact with the displayed summary",
        "position": "left"
    },
    "#search-btn": { 
        "text": "expand this to filter the list of profiles" 
    }
}

This text will be shown against an element that has data-intro='#summary-btns'. If the data-intro does not start with a #, then the value will be used as the text to display. If no entry is present for a given element's data reference, then nothing will be displayed.

  • attribute: changes the data attribute from data-intro to data-. Example:
$('body').chardinJs({ attribute: 'data-intro' });

Methods

.chardinJs('start')

Start ChardinJs in the selector.

.chardinJs('toggle')

Toggle ChardinJs.

.chardinJs('stop')

Make your best guess. That's right! Stops ChardinJs in the selector.

Events

'chardinJs:start'

Triggered when chardinJs is correctly started.

'chardinJs:stop'

Triggered when chardinJs is stopped.

'chardinJs:next'

Triggered when the sequential option moves to the next element

'chardinJs:previous'

Triggered when the sequential option moves to the previous element

Author

Pablo Fernandez

Contributors

Contributions

If you want to contribute, please:

  • Fork the project.
  • Make your feature addition or bug fix.
  • Add yourself to the list of contributors in the README.md.
  • Send me a pull request on Github.

License

Copyright 2020 Pablo Fernandez

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Comments
  • Element with z-index and position doesn't appear above overlay

    Element with z-index and position doesn't appear above overlay

    When the element to highlight has both a z-index and either position relative or absolute, it doesn't rise above the overlay.

    Reproduced here: http://jsfiddle.net/wAUKV/

    opened by dozyatom 14
  • Sequential tour

    Sequential tour

    HN comment "I think it would be worth displaying each message one at a time with a delay in between (that way they could function as a sequential tour in addition to coach marks)."

    source

    opened by GMali 9
  • [enhancement] Add missing bower.json.

    [enhancement] Add missing bower.json.

    Hey, maintainer(s) of heelhook/chardin.js!

    We at VersionEye are working hard to keep up the quality of the bower's registry.

    We just finished our initial analysis of the quality of the Bower.io registry:

    7530 - registered packages, 224 of them doesnt exists anymore;

    We analysed 7306 existing packages and 1070 of them don't have bower.json on the master branch ( that's where a Bower client pulls a data ).

    Sadly, your library heelhook/chardin.js is one of them.

    Can you spare 15 minutes to help us to make Bower better?

    Just add a new file bower.json and change attributes.

    {
      "name": "heelhook/chardin.js",
      "version": "1.0.0",
      "main": "path/to/main.css",
      "description": "please add it",
      "license": "Eclipse",
      "ignore": [
        ".jshintrc",
        "**/*.txt"
      ],
      "dependencies": {
        "<dependency_name>": "<semantic_version>",
        "<dependency_name>": "<Local_folder>",
        "<dependency_name>": "<package>"
      },
      "devDependencies": {
        "<test-framework-name>": "<version>"
      }
    }
    
    

    Read more about bower.json on the official spefication and nodejs semver library has great examples of proper versioning.

    NB! Please validate your bower.json with jsonlint before commiting your updates.

    Thank you!

    Timo, twitter: @versioneye email: [email protected] VersionEye - no more legacy software!

    opened by timgluz 8
  • Make the opacity of the overlay configurable

    Make the opacity of the overlay configurable

    Right now .8 is wired into the code:

            return setTimeout(function() {
              styleText += "opacity: .8;";
              return overlay_layer.setAttribute("style", styleText);
            }, 10);
    

    opened by MrCsabaToth 7
  • Is there a way to make it mobile responsive?

    Is there a way to make it mobile responsive?

    Hello everyone. I have been looking for quite some time an overlay instructions script to use for an upcoming project.

    I am wondering if it can be made responsive down to mobile screen size; what I mean is turn the left or right side tooltips to top and bottom when it reaches mobile screen size.

    Moreover, is there any way to replace the borders with an image (like arrows?)

    Thanks in advance for any help I get on this :)

    opened by scooterlord 6
  • *[data-intro] is a 'heavy' css query. Can I give you a list?

    *[data-intro] is a 'heavy' css query. Can I give you a list?

    First of all, I like the tool. It looks great!

    But I'm concerned with one thing. *[data-intro] is a 'heavy' css query. It's not optimised for speed. When you have a big page with a lot of elements. Things will be slowed down.

    Instead of that, can I give you list? Like:

    var list = [
        {
            target: '.jumbotron img',
            intro: 'An awesome 18th-century painter, who found beauty in everyday, common things.',
            position: 'right'
        },
        {
            target: '.jumbotron .btn',
            intro: 'This button toggles the overlay, you can click it, even when the overlay is visible',
            position: 'left'
        },
        {
            target: '.jumbotron .credits p',
            intro: 'Author of this plugin, aka Pablo Fernandez',
            position: 'right'
        },
    ]
    
    $('body').chardinJs(list);
    $('body').chardinJs('start');
    

    That would be awesome. Now I even can pre-i18n it.

    Big thanks

    opened by pahlers 6
  • Fix for issues #4 and #5

    Fix for issues #4 and #5

    I use the code from @fiveminuteargument and compiled the min.js and the .js from the .coffee code.

    • added the DOM element in the getOffset when not body
    • removed element with $(this) not this on stop
    opened by felipeclopes 6
  • Start with button

    Start with button

    Hello

    I want to run it with the button and I tried to get the data via JSON but it doesn't work. Can you say my mistake?

    <button type="button" class="btn btn-dual" id="tourStart" data-toggle="chardinjs"></button>
    
    $('#tourStart').on('click', 'button[data-toggle="chardinjs"]', function (e) {
    	e.preventDefault();
    	$('body').chardinJs({url: "test/test.json"});
             return $('body').chardinJs('start');
    });
    
    opened by emresaracoglu 5
  • Chardin.js and Intro.js conflict in data-intro attribute use

    Chardin.js and Intro.js conflict in data-intro attribute use

    Both Chardin.js and Intro.js use the data-intro attribute.

    I would like to have a walk-thru for first use with Intro.js and a separate help overlay using chardin.js. It is hokey to have the help file be a walk-thru and it is hokey to have the help overlay popup on first use without a walk thru. It seems to me that both have their place.

    Unfortunately they both use the same attribute: data-intro

    So I can't use them both wiithout changing one or the other. I would change chardin.js to use data-help instead of data-intro. Chardin.js is more of a help file overlay while intro.js is more of an intro and walk-thru on first use tool. So data-intro makes more sense for Intro.js.

    I see how I can change this easy enough myself if I branch chardin.js. I just thought someone might have some feedback on this.

    Changing this would break everyone who currently uses chardin.js. If I were to provide a pull request, it wouldn't be pulled.

    So perhaps the solution would be to default to data-intro but allow for the attribute to be changed at load time.

    Thoughts?

    opened by rhyous 5
  • Chardin.js demo (gh-pages) doesn't work due to some http refernces

    Chardin.js demo (gh-pages) doesn't work due to some http refernces

    Right now I'm booted into Win 8.1, trying latest FF and Chrome. Looks like google fonts are not loaded and maybe other issues.

    FF FireBug console: Blocked loading mixed active content "http://fonts.googleapis.com/css?family=Montserrat:400,700" Blocked loading mixed active content "http://code.jquery.com/jquery-1.9.1.min.js" Blocked loading mixed active content "http://fonts.googleapis.com/css?family=Montserrat:400,700" Blocked loading mixed active content "http://code.jquery.com/jquery-1.9.1.min.js" TypeError: t is undefined ...tParent;return t.top=r,t.left=n,t},e}(),t.fn.extend({chardinJs:function(){var n,... chardinjs.min.js (line 2, col 3983) ReferenceError: $ is not defined $(function() { demo.js (line 4, col 2) GET https://apis.google.com//scs/apps-static//js/k=...RSTNoBcAYOn7vC-V1AIz10SRkEhEcPg/cb=gapi.loaded_0

    200 OK 248ms
    fastbut...9063390 (line 28) GET https://apis.google.com//scs/apps-static//js/k=...RSTMjG9wWLrT-KZYIA_lqG6d1J68HKw/cb=gapi.loaded_1

    200 OK 251ms
    fastbut...9063390 (line 28) 20:1:41.407 CSI/tbsd_ 20:1:41.408 CSI/_tbnd

    Chrome: [blocked] The page at 'https://heelhook.github.io/chardin.js/#' was loaded over HTTPS, but ran insecure content from 'http://fonts.googleapis.com/css?family=Montserrat:400,700': this content should also be loaded over HTTPS. (index):11 [blocked] The page at 'https://heelhook.github.io/chardin.js/#' was loaded over HTTPS, but ran insecure content from 'http://code.jquery.com/jquery-1.9.1.min.js': this content should also be loaded over HTTPS. (index):1 Uncaught TypeError: Cannot read property 'fn' of undefined chardinjs.min.js:2 Uncaught ReferenceError: $ is not defined demo.js:4 Consider using 'dppx' units, as in CSS 'dpi' means dots-per-CSS-inch, not dots-per-physical-inch, so does not correspond to the actual 'dpi' of a screen. In media query expression: (-webkit-min-device-pixel-ratio: 1.5), (min-resolution: 144dpi) tweet_button.1406859257.html:1 Consider using 'dppx' units, as in CSS 'dpi' means dots-per-CSS-inch, not dots-per-physical-inch, so does not correspond to the actual 'dpi' of a screen. In media query expression: (-webkit-min-device-pixel-ratio: 1.5), (min-resolution: 144dpi) follow_button.1406859257.html:1

    opened by MrCsabaToth 5
  • Chardin in a loop

    Chardin in a loop

    With a loop every input field will have a data-intro and data-position. Resulting in an overkill of the same values. Is there a way to counter this by picking only the data-intro and data-position of the first element?

    $value){?>
    opened by zwaardje 5
  • Highlight current help element

    Highlight current help element

    Hi, love this tool, but there are some things missing. E.g. the possibility of highlighting a currently shown element.

    I've written this code:

    chardinJs.prototype.getClipPathPolygon = function (element) {
            var offset_top = parseInt($(element).offset()["top"]);
            var offset_left = parseInt($(element).offset()["left"]);
    
            var width = parseInt($(element)[0].scrollWidth);
            var height = parseInt($(element)[0].scrollHeight);
    
            var left = offset_left;
            var right = left + width;
    
            var top_y = offset_top;
            var bottom_y = top_y + height;
    
            var string = `polygon(0px 0px, 0px 100%, ${left}px 100%, ${left}px ${top_y}px, ${right}px ${top_y}px, ${right}px ${bottom_y}px, ${left}px ${bottom_y}px, ${left}px 100%, 100% 100%, 100% 0px)`;
            return string;
    };
    

    This has to be attached to the chardin-mask-layer somehow for each click, but I cannot currently find a simple way of doing that.

    opened by NormanTUD 1
  • Targeting local div, if grid within grid, produces weird results

    Targeting local div, if grid within grid, produces weird results

    When I try and target a specific container, and said container is a grid item within another grid item, I get a very strange result.

    Have a look at my example. if you click on the green section, you will see that the overlay works properly, this is targeting the entire body. When targeting the #green div, which can be done by clicking the blue button on the right. You will see the result.

    https://chardin-js-local-div-target-example.webflow.io/


    Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

    opened by gorillabiscuit 0
  • Can we add any links in the Data-intro part?

    Can we add any links in the Data-intro part?

    I am just looking for the option of including the link in the "data-intro" message so that when i click on the link I want to navigate to that link on another tab in the browser

    Step1 : Initialized "$('body').chardinJs('start')" Step2: Once the overlay is shown on the page. I would like to have a link in one of the "data-intro" attribute Step3: once we click the link present on the "data-intro: it should navigate to the link opened in the next page.

    Do we have any easy way to achieve this?

    Please look into the attached screenshot. Screenshot.docx


    Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

    opened by bhanu24268 0
  • Added data attribute to modify class of element when overlay is shown

    Added data attribute to modify class of element when overlay is shown

    Often when the overlay is shown, users may want to customize the css of the element only for the duration during which the overlay is shown. For example, in the demo, a white border might be added to the image when the overlay is shown ( https://apophiz-gd.github.io/chardin.js/ ). This commit adds an attribute 'appendclass' which add's css classes when the overlay is shown.

    opened by apophiz-gd 0
  • Implementation of an external documentation-link feature

    Implementation of an external documentation-link feature

    Adding an optional link at the end of tooltip if the attribute is specified.

    For example; chardin

    An awesome 18th-century painter, who found beauty in everyday, common things. Read more?

    opened by pegasuspect 0
Releases(0.2.0)
  • 0.2.0(Feb 15, 2020)

    Under new management.

    This release contains a fair few updates and fixes pulled in from various pull requests made over the years - thanks all who contributed.

    Changes:

    • Can now use custom data attribute name to tag elements
    • Now uses 4 overlays above/below/left/right of the target element to ensure it shows through.
    • Can offset the tooltip along the element edge
    • Optionally allow sequential stepping through elements
    • Optionally fetch help tooltips from json file dynamically sourced from a get request
    • Various minor fixes.
    Source code(tar.gz)
    Source code(zip)
Simple, flexible tours for your app

Tourist.js Tourist.js is a simple library for creating guided tours through your app. It's better suited to complex, single-page apps than websites. O

null 1.2k Dec 6, 2022
Guide your users through a tour of your app

Shepherd is maintained by Ship Shape. Contact us for web app consulting, development, and training for your project. Browsers support Edge Firefox Chr

Ship Shape 10.8k Dec 28, 2022
A better way for new feature introduction and step-by-step users guide for your website and project.

Intro.js v3 Lightweight, user-friendly onboarding tour library Where to get You can obtain your local copy of Intro.js from: 1) This github repository

usablica 21.7k Jan 2, 2023
Grupprojekt för kurserna 'Javascript med Ramverk' och 'Agil Utveckling'

JavaScript-med-Ramverk-Laboration-3 Grupprojektet för kurserna Javascript med Ramverk och Agil Utveckling. Utvecklingsguide För information om hur utv

Svante Jonsson IT-Högskolan 3 May 18, 2022
Hemsida för personer i Sverige som kan och vill erbjuda boende till människor på flykt

Getting Started with Create React App This project was bootstrapped with Create React App. Available Scripts In the project directory, you can run: np

null 4 May 3, 2022
Kurs-repo för kursen Webbserver och Databaser

Webbserver och databaser This repository is meant for CME students to access exercises and codealongs that happen throughout the course. I hope you wi

null 14 Jan 3, 2023
This repo contains instructions on how to create your NFT in Solana(using Metaplex and Candy Machine) and mint it using your custom front-end Dapp

Solana-NFT minting Dapp Create your own NFT's on Solana, and mint them from your custom front-end Dapp. Tools used Metaplex -> Metaplex is the NFT sta

Udit Sankhadasariya 12 Nov 2, 2022
VSCode extension that creates overlay for your Broadcasting Software of choice.

BSOverlay VSCode extension that creates an overlay for your Broadcasting Software of choice. Documentation Please refer to the Wiki Section. Installin

chocoearly44 4 Sep 30, 2022
An ingame overlay with a lot of enhancements for your daily gameplay

LostArkOverlay This project was generated using Nx. ?? Smart, Extensible Build Framework Quick Start & Documentation Nx Documentation 10-minute video

Pascal M 7 Sep 24, 2022
A POC of a Discord.js bot that sends 3D rendering instructions to a Go server through gRPC which responds with the image bytes which are then sent back on Discord.

A POC of a Discord.js bot that sends 3D rendering instructions to a Go server through gRPC which responds with the image bytes which are then sent back on Discord.

Henrique Corrêa 5 Jan 8, 2022
Information about the application internals and instructions on how to run it can be found in our Technical Documentation.

Swisstopo Showcases Welcome to our approach on bringing geodata closer to the user. This is our semester project during our Bachelor studies at the Be

Jonas Hofer 3 Sep 30, 2022
Short sample and instructions for configuring a Flutter Web application to deploy-on-push to Firebase Hosting

Short sample and instructions for configuring a Flutter Web application to deploy-on-push to Firebase Hosting

Kevin Moore 18 Nov 17, 2022
A User Interface for calling a program's instructions

Anchor Test UI Testing Anchor programs can be lenghty and overwelming So we thought of a Cool Way of Testing Anchor program without writing an Testing

Pratik Saria 25 Sep 3, 2022
Node js package makes creating node jd dependincies files like Controllers,Entities and Repositories easier by executing a few instructions

Nodejs Studio Node js package makes creating node js project dependincies files like Controllers,Entities and Repositories easier by executing a few i

Syrian Open Source 9 Oct 12, 2022
This repository contains the Solidity smart contract of Enso, a detailed list of features and deployment instructions.

Enso NFT Smart Contract This repository contains the Solidity smart contract of Enso, a detailed list of features and deployment instructions. We stro

enso NFT 3 Apr 24, 2022
Hacking Instructions for the Nokia 800 Tough (aka Bananaphone with KaiOS)

Nokia 800 Tough Hacking Instructions for Arch Linux host system. I don't care about your messed up Windows, sorry. 1. Android Platform Tools Install t

Cookie Engineer 3 Jul 12, 2022
:flashlight: Set a spotlight focus on DOM element adding a overlay layer to the rest of the page

Focusable An awesome and lightweight library for performing spotlight in your DOM elements, setting an animated overlay to the rest of the page. You c

Hector Zarco 1.1k Dec 7, 2022
Sandbox for experimenting with Overwolf's TFT overlay

Overwolf sample app This repository contains sample apps that demonstrate some basic points and flows that are relevant when developing Overwolf apps:

Collin Lidstrom 1 Dec 26, 2021
Interactive map overlay for finding secrets hidden around the world of Lost Ark.

Lostark Map Overlay This is an interactive map overlay which is resizable, movable and can be kept up during gameplay for finding secrets hidden aroun

Omar Minaya 6 Dec 29, 2022
Green Lattice Overlay for r/place

Green Lattice Overlay for r/place Step 1 Install one of the following extensions for your browser. Chrome (TamperMonkey) Firefox (ViolentMonkey) (note

siah 4 Apr 25, 2022