search

not-only-code / Simpletooltip

Simpletooltip is a JQuery plugin, thought to insert short tooltips to any element of your website more easily
21 stars 4 forks source link

readme

Simpletoolip

...is a Jquery plugin, thought to insert short tooltips to any element of your website more easily

Simpletooltip logo

Table of contents

  1. Features
  2. Build
  3. Installation
  4. Usage
    1. Using data attribute
    2. Using JavaScript
  5. Options
    1. Default options
    2. Global options
  6. Positions
  7. Themes
    1. Creating Themes
  8. Download
  9. Changelog

Features

Build

$ npm install
$ grunt

Installation

Download the plugin and decompress files, put the folder simpletooltip in your tree project files, would be nice create a folder that contains it, for example js (/js/simpletooltip).

In the header of your document attach the scripts simpletooltip.min.cssandsimpletooltip.min.js`. Of course, you will need to load jQuery first:

<link rel="stylesheet" href="https://github.com/not-only-code/Simpletooltip/blob/master/.../simpletooltip/dist/css/simpletooltip.min.css" media="screen" />

<script src="http://code.jquery.com/jquery.min.js"></script>
<script src="https://github.com/not-only-code/Simpletooltip/raw/master/.../simpletooltip/dist/js/simpletooltip.min.js"></script>

Usage

To initialize the plugin you have 2 options:

Using data attribute

First declare data-simpletooltip="init" in the html element, and complete the attribute title, that will be the content of the tooltip. The plugin will initialize automatically.

<h1 data-simpletooltip="init" title="This is a tooltip">This is a header</h1>

Using JavaScript

You can use the jquery function simpletooltip() to initialize the plugin for one or more objects together. Remember the attribute `title must exist in each element.

<h1 title="This is a tooltip">This is a header</h1>

<script>
    jQuery(document).ready(function($) {
        $('h1').simpletooltip();
    });
</script>

Simpletooltip was thought for use small and descriptive texts in order to substitute the ugly yellow tooltip that browsers offers by default. Anyway, you can insert more complex content like linebreaks, lists, images, etc...

<h1 title="This is a tooltip">This is a header</h1>

<script>
    jQuery(document).ready(function($) {
        $('h1').simpletooltip();
    });
</script>

Options

You can add some options to customize your tooltips. This options works in cascade, that means you can override them. Here, the priorities:

  1. The default options will be applied at first instance.
  2. Your global options will override the default ones.
  3. Your theme options will override the global ones
  4. All data attributes will override the rest.

Default options

attribute description values default
position position of tooltip in relation with the element top top-left left-top left left-bottom bottom-left bottom bottom-right right-bottom right right-top top-right top
color color of text inside the box #FFFFFF / 'rgba(255, 255, 255, 0.5)' / 'white' #CCCCCC
background_color color of background of the box #000000 / 'rgba(0, 0, 0, 0.5)' / 'black' #222222
border_color color of the box border #000000 / 'rgba(0, 0, 0, 0.5)' / 'black' #111111
border_width width of box border (in pixels) 4 / 4px / 0 'none' 0
arrow_width size of the arrow (in pixels) 6 / 6px 4px
fade animation when appears true / false true
max_width limit of the box width 200 / '200px' 200px

Global options

You can add it globally, witch affects all tooltips of your queried objects:

<script>
    jQuery(document).ready(function($) {
        $('.tooltip').simpletooltip({
            position: 'right',
            border_color: 'purple',
            color: '#FFFFFF',
            background_color: 'rgba(125,100,230, 0.5)',
            border_width: 4
        });
    });
</script>

Custom options

Or be more specific and override 1 option in 1 tooltip using data attribute:

<h1 class="tooltip" data-simpletooltip-color="#FF0055">my title</h1>

Positions

Simpletooltip has 12 funcional positions, by default goes on top position, but you can choose: top top-left left-top left left-bottom bottom-left bottom bottom-right right-bottom right right-top `top-right.

To add the desired position, in that example we'will use attribute `data-simpletooltip-position.

<div class="simpletooltip" data-simpletooltip-position="right-top">right top</div>

Themes

Themes are packages of options you can set up in one place, Simpletooltip comes with 4 default themes, you can choose: blue white dark gray.

To assign a theme, configure theme parameter with the theme name:

<img src="https://github.com/not-only-code/Simpletooltip/raw/master/images/themesample-seablue.png" class="simpletooltip" data-simpletooltip-theme="blue" title="blue theme" />

Also you can extend it, imagine a blue theme without border:

<p data-simpletooltip="init" data-simpletooltip-theme="blue" data-simpletooltip-border-width="0" title="blue custom theme">blue theme customized<p>

Creating Themes

Also you can create your own themes. Imagine you need to repeat continuously 2 schemes in your site and don't want to fill your html code with noisy variables inside data attributes. For that you can use themes attribute.

<script>
    jQuery(document).ready(function($) {
        $('.tooltip').simpletooltip({
            themes: {
                pink: {
                    color: 'red',
                    border_color: 'red',
                    background_color: 'pink',
                    border_width: 4
                },
                brazil: {
                    color: 'yellow',
                    background_color: 'green',
                    border_color: 'yellow',
                    border_width: 4
                }
            }
        });
    });
</script>

Download

Download the plugin here, also you can access to GitHub repo.
Contribute with ideas, new features, or bugs on Github Issues.
If this plugin helped you, any donation will be wellcome.

Changelog

v1.3.0 (11.06.2014)

v1.2.0 (01.02.2011)

v1.1.0 (03.06.2010)

v1.0 (19.05.2010)