Getting Started

To get started, set up a simple sequence of blocks within an area. You can have other blocks before and after, but this sequence of wrapping what you want to toggle on/off with Magic Toggle blocks is the essential part:

1. Magic Toggle Block
2. One or more blocks to show normally (A)
3. Magic Toggle Block
4. One or more blocks to show when toggled (B)
5. Magic Toggle End

The above sequence of blocks will then show group (A), then when the cursor hovers over group (A), will show group (B).

Once you have this basic hover behaviour working, all kinds of other behaviours are possible using the various block templates provided with Magic Toggle and using the Magic Toggle remote control block.

While a Page Loads

Magic Toggle transforms a page as it completes loading. For a large or complex page, this means you may briefly see content without the toggles while the page loads.

If you want to hide this, use block Design (Set Block Styles) > CSS >Additional CSS to add “display:none;” to any blocks (including Magic Toggle blocks) you want to remain hidden until everything is ready. Magic Toggle will then show the hidden blocks and toggle sets when everything has loaded.

Ending Sets of Toggles

By default, the last Magic Toggle block in any area will contain any other blocks up to the end of an area.

To end a toggle set before the end of an area, simply insert a Magic Toggle End block. Subsequent blocks will then continue below the toggle set. Or you can start another toggle set simply by inserting a new Magic Toggle block where you want the next toggle set to begin.

Magic Toggle End is entirely optional. If you don’t add it, a toggle set will run on to the end of a page area.

Magic Toggle in Stacks

You can put Magic Toggle blocks in stacks and include the stack in the Main area of a page and the Magic Toggle blocks will behave as if they were part of the sequence of blocks in that page area.

You can put a complete toggle set in a stack and include the stack in any area of the page and the Magic Toggle will behave as a toggle set.

However, an incomplete toggle set within a stack included in page areas other than the main area will try and behave as a separate toggle set, so will not run on from a toggle set outside of the stack.

Toggles in the Dashboard

Toggles are disabled on dashboard pages, in the same way as they are disabled in Edit mode.

Using Custom Templates

Magic Toggle comes with several custom templates. Any toggle set will follow the template set for the first Magic Toggle block in the set (templates set for subsequent Magic Toggle blocks in the set will be ignored).

These templates concentrate on variations of behaviour, leaving the styling of toggles up to the styling of the blocks within the toggle.

• Toggle on cursor movement (hover).
• Toggle on clicking links.
• Toggle by remote control from anywhere on the page.
• Page through toggle sets of more than two groups of blocks.

You can also design custom templates using the examples shown in the supplied templates as a starting point (see below).

For styling with css, Magic Toggle applies the class 'jl-magic-toggle-active' to the currently active toggle group within each toggle set. Various templates apply additional classes, defined by the individual template, to active or inactive groups within a toggle set. However, only the active group is shown, so styling of inactive groups is only really useful for those integrating additional JavaScript/jQuery.

Remote Control

Remote control comprises a toggle set, defined using Magic Toggle blocks styled with a remote control template, and a controller using a Remote Control block (or similarly styled links). These blocks are linked using the class 'magic_toggle_remote_controller' and the Label of the first Magic Toggle block in the toggle set.

A remote control is fundamentally one or more html link elements, with everything else in the block being concerned with how those links are presented. In general, a remote control block does not use any JavaScript because the associated Magic Toggle already contains the necessary JavaScript that listens for dom events such as clicking or mouse movement (hovering) of the link(s) in the Remote Control block.

This makes it easy to add remote controls to any block. You don't need to use a Remote Control block! Just include a link with the class 'magic_toggle_remote_controller' and the href="#magic_toggle_rc_...." that a Remote Control block would have provided. For example, you could create a remote control for a Magic Toggle from within a custom AutoNav template!

on_named_block_hover

If you don't want to use a link to trigger the toggle, the template on_named_block_hover will activate the toggle when a block with a matching id is hovered.

To work with this template you will need to use block design to set the elements that trigger the toggle and name them according to the correct convention.

If the toggle remote label is my_remote_1, that magic toggle set will toggle when the cursor is hovered on a dom element with the id:

magic_toggle_rc_nextmy_remote_1

For example, to toggle when a content block is hovered, in block design, last tab, the content block should be given the css id:

magic_toggle_rc_nextmy_remote_1

Now, when the cursor hovers over that content block, it will toggle the Magic Toggle set with the label my_remote_1.

Custom Templates for Controls

With Magic Toggle, you rarely need a custom template because you use the styling of the blocks within the toggle and their block templates to achieve your page design.

If all you want is a freshly styled button to control the toggle, consider a template for the Remote Control block. Its a smaller block and almost trivial to override  or style.

siteroot/blocks/jl_magic_toggle_remote/templates/your_remote_template_name

Custom Templates for Toggling Behaviour

Custom templates for Magic Toggle blocks are more concerned with providing new controls and behaviour for Magic Toggle. Custom templates contain two parts, a view.php and an optional view.css. These files should be created in the folder:

siteroot/blocks/jl_magic_toggle/templates/your_template_name

You can start from scratch, or copy and modify the default view for magic toggle or any existing template supplied with the package.

The view.php part of a Magic Toggle template will be primarily concerned with providing JavaScript/jQuery behaviours attached to control elements. The control elements could be:

• The toggle set itself (toggle on hover).
• Links or buttons provided by the template (and hence shown above the toggle set).
• Remote control from any element on the page, simply by providing an appropriate click or mouse movement event listener.

Always use the 'magic_toggle_ready' Event

Magic Toggle triggers the custom JavaScript event 'magic_toggle_ready' when the Magic Toggle has finished preparing a page and is ready to start toggling. Template script developers must enclose any JavaScript that is used within a toggle template in a handler for this event. There are plenty of examples in the templates provided with Magic Toggle.

Always wait for the magic_toggle_ready event, or it just won't work !!!

Controlling toggles by triggering events

Most Magic Toggle templates are primarily concerned with some simple behaviours in JavaScript/jQuery. Within a magic_toggle_ready handler, a custom template should set up listeners for whatever events you want to toggle on and then trigger the toggling behaviour of Magic Toggle using the events magic_toggle_next and magic_toggle_prev to control the actual toggle action.

For a normal toggle situation of toggling between the first (index 0) and second (index 1) groups of a toggle set, there is no difference between magic_toggle_next and magic_toggle_prev. However, sticking to magic_toggle_next is a good convention.

When there are more than 2 groups to toggle between, magic_toggle_next and magic_toggle_prev can be used to page through a longer list of groups.

Both events have the same parameters in and anonymous array [...]

1. The toggle group number or dom id within to show (or null, and it will be the next or previous).
2. Classes to add to the shown group (or null to hold the place).
3. Classes to remove from the not shown groups.

Also available is a jQuery enquiry about the content of a toggle set.

 var set_info = $('.<?php echo $setname;?>').getMagicToggleSetInfo(); 

This returns an array of objects, one for each group in the set:

{ id : toggle_id, //dom id selector
  label : labels, 
  tip : tip }; 

This is useful for creating indexed paging lists or attaching tips to controls.

Magic Toggle will also fire the custom JavaScript event 'jl_magic_toggle_show' for a toggle set when it is shown. Template developers can use this to add custom behaviours when a toggled group is shown.