Magic Tipple works by looking for terms within a web page, marking them, and associating a popup tip or modal.

Tip definition

Whether defined in the Magic Tipple block, globally in the Magic Tipple dashboard page, or loaded from a text file, all tips share a common format.

Tips are defined in plain text as a list separated by two new lines.

Within each tip, the first line is the term that will be keyed on and any subsequent lines are the associated description that will be popped up.

If a tip only has a single line, that line will be split into a term and description on either the first colon ':' or the first blank space ' ' within the line.

Terms are by deafult treated as plain text, but may also be interpreted as a jQuery selector (see below).

Descriptions may optionally include html, or have URLs automatically translated into links.

By default, the way terms are matched will automatically adjust with the content of the term.

• If a term contains any lowercase letters, then matching will ignore case and test for complete words or groups of words.
• If a term is all uppercase, then matching will be fixed case.
• If a term ends in a non alpha-numeric character, then partial matches will be acceplted.
• If a term begins with $: , then the rest of the term will be processed as a jQuery selector.

This automatic mode can be changed for fixed or ignore case and for full or partial matching through the dashboard. 

Have a look at the screenshots for examples of real tip definitions.

Page area selection

The part of the page that a Magic Tipple block is applied to is governed by jQuery or CSS style selectors. The default selection of '#main-content-container' is a good starting point for the Greek Yogurt theme. For other themes, you will need to look in the theme page type template or inspect the page to determine a suitable selector. Your theme developer may also be able to advise you on selectors.

If you do not specify a selector, Magic Tipple could accidentally mess with all sorts of things you don t want it to!

Selectors can be more complex using elements, ids and classes in combination and in lists. You can also specify a selector to exclude parts of a page.

Adding your own icons

To add your own icons, use FTP to upload your icons as '.png' files to the folder 'site-root/files/magic_tipple/icons/'. Magic Tipple will then show the icons in the edit dialogue.

If the spacing between an icon and the terms it is associated with is not quite to your liking, the slider 'Adjust icon x position' can be used to shift it a few pixels left or right.

Internet Explorer

In old Internet Explorer versions (IE7 or before), Magic Tipple templates fall back to showing tips in using the browser default tooltip.

Help – I defined some bad html in a tip and it broke my site !!

You have a variety of options to get out of this:

• Go directly to the dashboard sitemap and revert the page version.
• Go to the dashboard file manager and delete or replace a faulty file of tips.
• Go to the dashboard page for Magic Tipple and edit/correct global tips.
• Define the constant MAGIC_TIPPLE_ENABLE to be false in config/site.php.

Multiple templates

If you want, you can have multiple Magic Tipple blocks on a page, each with its own terms, highlighting and tip templates.

Block defaults

In addition to allowing entry of global tips, the Magic Tipple dashboard page also enables you to change the default settings for Magic Tipple blocks.

Any settings you save in the dashboard will be used to provide defaults when you next add a Magic Tipple block.

Developing further templates

For a custom template, the easiest solution is to base it on the qTip template. Just copy the template's view.php and add your own php to set:

$qtip_classes = 'your_qtip_class';

This will fix the qTip class to be based on your_qtip_class rather than the class selected through the Magic Tipple edit dialogue.

To include qTips corner rounding and drop shadow options, you can also append:

$qtip_classes = 'your_qtip_class' . ' ' . $other_qtip_classes;

In the associated copy of view.css, then define 'your_qtip_class' to style the qTip popup. Have a look in the file '/packages/jl_magic_tipple/css/qtip/jquery.qtip.css' for the associated class names that you may want to override.

To prevent your new template from interfering with existing templates, you will also need to change the $marker_class to a name unique to your template.

If you want to write JavaScript or jQuery to integrate other tip or popup plugins, the default template (view.php) has been left with script uncompressed to show the overall structure you can work within.

Interaction with Magic Linkify

Magic Tipple is designed to coexist on a page with Magic Linkify. If any terms are shared, both tips and links will be applied to the same terms.

How these interact depends on the behaviours selected and the sequence of the blocks on the page. In general, it is best to place a Magic Tipple block before a Magic Linkify block. This will leave any icons inserted by Magic Tipple outside the links applied by Magic Linkify, thus facilitating both behaviours.

Wrappers for Universal Content Puller

As a bonus, Magic Tipple provides tip styled wrapper plugins for Universal Content Puller. By selecting these wrappers from UCP you can make pulled content look like a Bootstrap tip, Bootstrap popover, or any qTip themed tip.