Magic Linkify works by looking for terms within a web page and wrapping links about them.

Link definition

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

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

Within each link, the first line is the term that will be keyed on and any subsequent lines are the associated URL that will linked to.

If a link only has a single line, that line will be split into a term and link on the last blank space ' ' within the line, but before any '?'.

URLs may contain parameters and anchors. These will be automatically escaped, so you don't need to worry about escaping parameters within a link definition

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 link definitions.

Page area selection

The part of the page that a Magic Linkify 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 Linkify 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 pats of a page.

Help - Magic Linkify 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 Linkify and edit/correct global tips.
  • Define the constant MAGIC_LINKIFY_ENABLE to be false in config/site.php.

Multiple templates

If you want, you can have multiple Magic Linkify blocks on a page, each with its own links and even a different template.

Alternate templates are provided to show the linkify list of links as an unordered list and as a tag cloud. Both these templates are simple lists and do not provide the linkify behaviour of the default template.

Existing Links

An option to 'Leave existing links' will prevent Magic Linkify from looking inside any existing links.

If you do not check this option, any terms found within existing links will be wrapped in the new links, possibly even subverting the entire existing link.

Block defaults

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

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

Interaction with Magic Tipple

Magic Linkify is designed to coexist on a page with Magic Tipple. 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.