clueTip - Documentation

Introduction

What is clueTip?

clueTip is a lightweight and highly customizable JavaScript tooltip plugin. It’s designed to be easily integrated into any web project, providing elegant and informative tooltips with minimal code. clueTip focuses on simplicity and performance, offering a clean API for developers to create sophisticated tooltip interactions without unnecessary complexity. It avoids dependencies on large JavaScript frameworks, making it ideal for projects where minimizing file size is a priority.

Key Features

Getting Started

To begin using clueTip, you’ll need to include the necessary JavaScript and CSS files in your project. After inclusion, initialize clueTip on elements within your HTML. The core functionality revolves around attaching clueTip to a target element using a simple JavaScript call. This call configures the tooltip’s content and behavior. Detailed examples are provided in the examples section of this manual.

Installation

  1. Download: Download the latest release of clueTip from [insert download link here]. This will contain the cluetip.js and cluetip.css files.

  2. Include Files: Include both the JavaScript and CSS files in your HTML document’s <head> section. You can do this directly, or use a task runner like Webpack or Parcel.

    <link rel="stylesheet" href="path/to/cluetip.css">
<script src="path/to/cluetip.js"></script>

  3. Initialization: Use JavaScript to initialize clueTip on the elements you want to have tooltips. This usually involves selecting elements using a CSS selector and calling the clueTip function. A basic example is shown below. Refer to the API documentation for advanced usage and configuration options.

    $(document).ready(function() {
    $('.my-element').cluetip({
        content: 'This is my tooltip text!'
    });
});

    Remember to replace $('.my-element') with the appropriate selector targeting your elements and adjust the content option as needed. You may need to include jQuery if you’re using the selector shown in this example. Cluetip itself does not require jQuery.

Basic Usage

Creating a clueTip

The simplest way to create a clueTip is by using the cluetip() method on a target element. This method accepts an options object to customize the tooltip’s behavior and appearance. At a minimum, you’ll need to specify the tooltip’s content. This example uses jQuery, but clueTip can also be used without it (see the “Without jQuery” section below).

$(document).ready(function() {
  $('#myElement').cluetip({
    content: 'This is my tooltip text'
  });
});

Replace #myElement with the CSS selector for the element you want to attach the tooltip to. This code will display the text “This is my tooltip text” when the #myElement is hovered over.

Positioning the clueTip

clueTip automatically handles tooltip positioning, attempting to place it in a location that doesn’t overlap the target element or go off-screen. However, you can fine-tune the positioning using various options:

Example demonstrating custom positioning:

$('#myElement').cluetip({
  content: 'My Tooltip',
  position: 'bottom-right',
  offset: { x: 10, y: 5 }
});

Setting Content

The content of the clueTip can be specified in several ways:

Examples:

// Static content
$('#element1').cluetip({ content: 'Simple tooltip text' });

// Dynamic content
$('#element2').cluetip({ content: function() { return 'Dynamic content: ' + new Date(); } });

// AJAX content
$('#element3').cluetip({ ajax: { url: '/tooltip-content.html' } });

// Local content
$('#element4').cluetip({ local: '#hidden-content' });

Styling the clueTip

clueTip provides a default CSS style, but you can easily customize it. The core CSS class is cluetip. You can modify this class directly in your stylesheet or override individual styles using the style option within the cluetip() function:

// Using CSS
/* In your CSS file */
.cluetip {
  background-color: #f0f0f0;
  border: 1px solid #ccc;
  padding: 10px;
}

// Using the 'style' option (overrides CSS)
$('#myElement').cluetip({
  content: 'My Tooltip',
  style: {
    backgroundColor: '#ddd',
    border: '2px solid #000'
  }
});

Remember that CSS styles set directly with the style option will override styles declared elsewhere. You can use the cluetip-inner class to style the tooltip’s inner content if needed.

Advanced Configuration

Customizing Appearance

Beyond the basic styling options, clueTip offers several ways to fine-tune the tooltip’s appearance:

Example:

$('#myElement').cluetip({
  content: 'My Tooltip',
  width: 200,
  class: 'custom-tooltip',
  arrows: true,
  arrowStyle: { color: '#FF0000', width: 10, height: 10 },
  showTitle: true,
  title: 'Important Information'
});

Remember to define the custom-tooltip class in your CSS file to apply specific styling.

Events and Callbacks

clueTip provides several events and callbacks allowing you to hook into various stages of the tooltip’s lifecycle:

These events can be specified within the options object:

$('#myElement').cluetip({
  content: 'My Tooltip',
  cluetipBeforeShow: function(ct, element) {
    console.log('Tooltip about to show');
    // Return false to prevent showing
    return true; 
  },
  cluetipShow: function(ct, element) {
    console.log('Tooltip shown');
  },
  cluetipBeforeHide: function(ct, element) {
    console.log('Tooltip about to hide');
    // Return false to prevent hiding
    return true;
  },
  cluetipHide: function(ct, element) {
    console.log('Tooltip hidden');
  }
});

ct refers to the clueTip instance, and element is the target element.

Animations

clueTip uses simple animations by default, but these can be customized:

$('#myElement').cluetip({
  content: 'My Tooltip',
  showEffect: 'slide',
  hideEffect: 'blind',
  showSpeed: 500,
  hideSpeed: 300
});

Accessibility

For improved accessibility, ensure that your tooltip content is semantically correct and uses appropriate ARIA attributes. clueTip itself doesn’t automatically add ARIA attributes; you might need to add them manually to the tooltip content or using a separate accessibility library. For instance, ensure that you use appropriate heading tags (<h1>, <h2>, etc.) within the tooltip content for better screen reader support.

Working with Multiple clueTips

clueTip handles multiple tooltips without conflicts. Simply initialize clueTip on multiple elements independently. Each element will have its own tooltip instance. There is no need for special handling or configuration when using multiple tooltips on a single page. However, ensure that the selectors used for each call to cluetip() are specific enough to target the correct elements to avoid unintended behavior.

API Reference

clueTip()

The primary function for initializing clueTip on an element.

Syntax:

$(selector).cluetip(options);

Example:

$('#myElement').cluetip({ content: 'My Tooltip' });

show()

Programmatically shows a clueTip instance.

Syntax:

$(selector).cluetip('show');

Example:

$('#myElement').cluetip('show');

hide()

Programmatically hides a clueTip instance.

Syntax:

$(selector).cluetip('hide');

Example:

$('#myElement').cluetip('hide');

destroy()

Completely removes a clueTip instance from an element. This removes all event handlers and the tooltip element itself.

Syntax:

$(selector).cluetip('destroy');

Example:

$('#myElement').cluetip('destroy');

updateContent()

Updates the content of an existing clueTip.

Syntax:

$(selector).cluetip('updateContent', newContent);

Example:

$('#myElement').cluetip('updateContent', 'New tooltip text!');

updatePosition()

Repositions the clueTip. Useful if the target element’s position changes dynamically.

Syntax:

$(selector).cluetip('updatePosition');

Example:

$('#myElement').cluetip('updatePosition');

getOptions()

Retrieves the current configuration options of a clueTip instance.

Syntax:

var options = $(selector).cluetip('getOptions');

Example:

var currentOptions = $('#myElement').cluetip('getOptions');
console.log(currentOptions);

setOptions()

Updates the configuration options of a clueTip instance.

Syntax:

$(selector).cluetip('setOptions', newOptions);

Example:

$('#myElement').cluetip('setOptions', { width: 300, position: 'bottom' });

Examples

These examples assume you have included the necessary clueTip CSS and JavaScript files in your project (see the “Installation” section). Remember to replace placeholder selectors like #myElement with your actual element selectors.

Simple Tooltip

This example demonstrates the most basic usage of clueTip, displaying a simple tooltip with static text.

HTML:

<p id="myElement">Hover over me!</p>

JavaScript:

$(document).ready(function() {
  $('#myElement').cluetip({
    content: 'This is a simple tooltip!'
  });
});

Tooltip with Custom Content

This example shows how to use a function to dynamically generate the tooltip content.

HTML:

<p id="dynamicElement">Hover over me!</p>

JavaScript:

$(document).ready(function() {
  $('#dynamicElement').cluetip({
    content: function() {
      return 'The current time is: ' + new Date();
    }
  });
});

Tooltip with Custom Styling

This example demonstrates how to customize the tooltip’s appearance using CSS.

HTML:

<p id="styledElement" class="styled-element">Hover over me!</p>

CSS:

.styled-element .cluetip {
  background-color: #f08080; /* Light coral */
  border: 2px solid #800000; /* Dark red */
  padding: 10px;
  color: white;
}

JavaScript: (No JavaScript changes needed for this example beyond basic initialization)

$(document).ready(function() {
    $('#styledElement').cluetip();
});

Tooltip with Animations

This example shows how to customize the tooltip’s show and hide animations.

HTML:

<p id="animatedElement">Hover over me!</p>

JavaScript:

$(document).ready(function() {
  $('#animatedElement').cluetip({
    content: 'This tooltip uses slide animation!',
    showEffect: 'slide',
    hideEffect: 'slide',
    showSpeed: 500,
    hideSpeed: 300
  });
});

Complex Example

This example combines several features, including AJAX content loading, custom positioning, and a title bar.

HTML:

<a id="ajaxElement" href="#">Click me!</a>

JavaScript:

$(document).ready(function() {
  $('#ajaxElement').cluetip({
    ajax: { url: '/my-ajax-content.html' }, // Replace with your URL
    position: 'bottom-right',
    offset: { x: 10, y: 5 },
    showTitle: true,
    title: 'AJAX Content',
    width: 300
  });
});

Remember to create a file named my-ajax-content.html at the appropriate location to return the content. This complex example requires the ajax option which fetches content from a specified URL. You will need a server-side setup to handle this request.

Remember to adjust paths and URLs to match your project structure. These examples provide a starting point for exploring clueTip’s capabilities; consult the API reference for more advanced options and customizations.

Troubleshooting

Common Issues

Debugging Tips

If you continue to experience issues after trying these troubleshooting steps, consider providing a minimal reproducible example to report a potential bug on the clueTip project’s issue tracker (if available). Include relevant code snippets and screenshots to help developers diagnose the problem efficiently.

Contributing

We welcome contributions to clueTip! Whether you’re reporting bugs, suggesting features, or submitting code improvements, your help is appreciated.

Reporting Bugs

When reporting bugs, please provide as much detail as possible to help us reproduce and fix the issue. A good bug report should include:

Ideally, create a minimal HTML file that isolates the problem. This makes it easy for us to test and debug the issue.

Submitting Pull Requests

If you’d like to contribute code improvements or new features, please follow these guidelines:

  1. Fork the repository: Create a fork of the clueTip repository on GitHub.

  2. Create a new branch: Create a new branch for your changes. Use a descriptive branch name that clearly indicates the purpose of your changes (e.g., “fix-tooltip-positioning”, “add-feature-x”).

  3. Make your changes: Write clean, well-documented code. Follow the existing coding style and conventions of the project.

  4. Test your changes thoroughly: Ensure your changes work correctly and don’t introduce new bugs. Run the provided test suite (if available) and add new tests for your changes if necessary.

  5. Commit your changes: Commit your changes with clear and concise commit messages. Use the imperative mood (e.g., “Fix tooltip positioning issue”, “Add support for custom arrow styles”).

  6. Push your branch: Push your branch to your forked repository.

  7. Create a pull request: Create a pull request on the main clueTip repository, linking to your branch. Provide a clear description of your changes and why they are needed. Address any comments or feedback received on your pull request promptly.

We appreciate contributions that improve the quality, performance, and usability of clueTip. By following these guidelines, you can help make the project even better. Before making significant changes, it is highly recommended that you open an issue to discuss the proposed changes to ensure they align with the project’s goals.