SmartMenus jQuery Website Menu Plugin ? Docs

for Documentation

Quick setup

Include the script and CSS files on your page:

<!-- jQuery -->
<script src="jquery-1.4.4.min.js" type="text/javascript"></script>
<!-- SmartMenus jQuery plugin -->
<script src="jquery.smartmenus.js" type="text/javascript"></script>

<!-- SmartMenus core CSS (required) -->
<link href='sm-core-css.css' rel='stylesheet' type='text/css' />
<!-- "sm-blue" menu theme (optional, you can use your own CSS, too) -->
<link href='sm-blue/sm-blue.css' rel='stylesheet' type='text/css' />

The menu definition is a standard unordered list structure:

<ul id="main-menu" class="sm sm-blue">
  <li><a href="#">Item 1</a></li>
  <li><a href="#">Item 2</a>
    <ul>
      <li><a href="#">Item 2-1</a></li>
      <li><a href="#">Item 2-2</a></li>
      <li><a href="#">Item 2-3</a></li>
    </ul>
  </li>
  <li><a href="#">Item 3</a></li>
</ul>

You always need to set the sm class and, optionally, if you would like to use some of the default themes, set it's class too (e.g. like sm-blue in the example above).

If you would like to have a vertical main menu instead of horizontal, you also need to set the sm-vertical class (and sm-blue-vertical if you use the "sm-blue" theme):

<ul id="main-menu" class="sm sm-vertical sm-blue sm-blue-vertical"> ...

The script is initialized like any other jQuery plugin:

$(function() {
  $('#main-menu').smartmenus();
});

Options

bottomToTopSubMenus

Type: Boolean

Determines whether the sub menus should be displayed from bottom to top (drop-up) instead of top to bottom (drop-down).

collapsibleHideDuration

Type: Integer

The duration for hide animation for collapsible sub menus. This option matters only if collapsibleHideFunction: null

collapsibleHideFunction

Type: null, Function

Custom function to use when hiding a collapsible sub menu (the default is the jQuery 'hide').

Code sample:

collapsibleHideFunction: function($ul, complete) { $ul.SlideUp(250, complete); }

Note: Don't forget to call complete() at the end of whatever you do with the $ul (the sub menu).

collapsibleShowDuration

Type: Integer

The duration for show animation for collapsible sub menus. This option matters only if collapsibleShowFunction: null

collapsibleShowFunction

Type: null, Function

Custom function to use when showing a collapsible sub menu (the default is the jQuery 'show').

Code sample:

collapsibleShowFunction: function($ul, complete) { $ul.SlideDown(250, complete); }

Note: Don't forget to call complete() at the end of whatever you do with the $ul (the sub menu).

hideDuration

Type: Integer

The duration in milliseconds for hide animation. Set it to 0 for no animation. This option matters only if hideFunction: null

hideFunction

Type: null, Function

Custom function to use when hiding a sub menu (the default is the jQuery 'hide').

Code sample:

hideFunction: function($ul, complete) { $ul.fadeOut(250, complete); }

Note: Don't forget to call complete() at the end of whatever you do with the $ul (the sub menu).

hideOnClick

Type: Boolean

Determines whether to hide (reset) the sub menus on click/tap anywhere on the page.

hideTimeout

Type: Integer

The timeout in milliseconds before hiding (resetting) the sub menus on mouseout/focusout.

isPopup

Type: Boolean

Determines whether the menu is a popup menu or a permanent menu bar. Popup menus can be shown/hidden via the popupShow and popupHide API methods. Make sure you position offscreen or hide with display:none in your CSS any popup menus you have.

keepHighlighted

Type: Boolean

Determines whether all ancestor items of the current sub menu should be kept highlighted - the script adds the highlighted class to the links (the A elements).

keepInViewport

Type: Boolean

Determines whether the sub menus should be repositioned if needed to make sure they always appear inside the viewport.

mainMenuSubOffsetX

Type: Integer

Allows setting a horizontal offset in pixels from the default position for the first-level sub menus. You may want to check the subMenusSubOffsetX option, too.

mainMenuSubOffsetY

Type: Integer

Allows setting a vertical offset in pixels from the default position for the first-level sub menus. You may want to check the subMenusSubOffsetY option, too.

markCurrentItem

Type: Boolean

Determines whether the script should automatically add the current class to the A element of the item linking to the current page URL.

markCurrentTree

Type: Boolean

Determines whether the script should automatically add the current class to the A elements of all ancestor items of the current item. This option matters only if markCurrentItem: true

overlapControlsInIE

Type: Boolean

Determines whether the script should make sure the sub menus appear on top of special OS controls in Internet Explorer (i.e. SELECT, OBJECT, EMBED, etc.) You may opt to disable this feature if you don't need this fix and would like to achieve best possible runtime performance in IE (other browsers are not affected anyway).

rightToLeftSubMenus

Type: Boolean

Determines whether the sub menus should be displayed from right to left instead of left to right. You may need to check and update the CSS for the sub indicators' position, too (i.e. look for span.sub-arrow).

scrollAccelerate

Type: Boolean

Determines whether to accelerate scrolling or use a fixed step for long sub menus that do not fully fit in the viewport height (i.e. start slower and then gradually increase the step).

scrollInterval

Type: Integer

Interval in milliseconds between each scrolling step for long sub menus that do not fully fit in the viewport height.

scrollStep

Type: Integer

Step in pixels when scrolling long sub menus that do not fit in the viewport height.

showDuration

Type: Integer

The duration in milliseconds for show animation. Set it to 0 for no animation. This option matters only if showFunction: null

showFunction

Type: null, Function

Custom function to use when showing a sub menu (the default is the jQuery 'show').

Code sample:

showFunction: function($ul, complete) { $ul.fadeIn(250, complete); }

Note: Don't forget to call complete() at the end of whatever you do with the $ul (the sub menu).

showOnClick

Type: Boolean

Determines whether to show the first-level sub menus onclick instead of onmouseover - i.e. like drop-down menus on desktop applications. This option matters only for mouse input.

showTimeout

Type: Integer

The timeout in milliseconds before showing the sub menus on mouseover/focusin.

subIndicators

Type: Boolean

Determines whether to create sub menu indicators. The script creates a SPAN and inserts it in the item's A element.

subIndicatorsPos

Type: String

Position of the sub menu indicator SPAN relative to the menu item content. A keyword specifying the jQuery method to use when inserting the SPAN in the menu item's A element - either 'prepend', or 'append'.

subIndicatorsText

Type: String

A text string to be added in the sub menu indicator SPAN (e.g. '+'). You may need to check and update the CSS for the sub indicators, too (i.e. look for span.sub-arrow).

subMenusMaxWidth

Type: String

Max-width for the sub menus in any valid CSS unit. If a value is set, any fixed width set in CSS will be ignored by the script.

subMenusMinWidth

Type: String

Min-width for the sub menus in any valid CSS unit. If a value is set, any fixed width set in CSS will be ignored by the script.

subMenusSubOffsetX

Type: Integer

Allows setting a horizontal offset in pixels from the default position for the second+ level sub menus. You may want to check the mainMenuSubOffsetX option, too.

subMenusSubOffsetY

Type: Integer

Allows setting a vertical offset in pixels from the default position for the second+ level sub menus. You may want to check the mainMenuSubOffsetY option, too.

Events

activate

Fired when an item is activated, right before its sub menu (if the item has a sub menu) is shown. You can cancel the event with return false and the item's sub menu will not be shown.

Cancelable: Yes

Arguments:

e

The jQuery.Event object.

item

The menu item A element.

Code sample:

$('#main-menu').bind('activate.smapi', function(e, item) {});

beforefirstshow

Fired only once for each sub menu, right before it's shown for the first time. You could use it, for example, for some initialization tasks that need to be called just once. You can cancel the event with return false and the sub menu will not be shown.

Cancelable: Yes

Arguments:

e

The jQuery.Event object.

menu

The sub menu UL element.

Code sample:

$('#main-menu').bind('beforefirstshow.smapi', function(e, menu) {});

beforehide

Fired right before a sub menu is hidden. You can cancel the event with return false and the sub menu will not be hidden.

Cancelable: Yes

Arguments:

e

The jQuery.Event object.

menu

The sub menu UL element.

Code sample:

$('#main-menu').bind('beforehide.smapi', function(e, menu) {});

beforeshow

Fired right before a sub menu is shown. You can cancel the event with return false and the sub menu will not be shown.

Cancelable: Yes

Arguments:

e

The jQuery.Event object.

menu

The sub menu UL element.

Code sample:

$('#main-menu').bind('beforeshow.smapi', function(e, menu) {});

blur

Fired when an item loses focus.

Cancelable: No

Arguments:

e

The jQuery.Event object.

item

The menu item A element.

Code sample:

$('#main-menu').bind('blur.smapi', function(e, item) {});

click

Fired when an item is clicked. You can cancel the event with return false and the item will not be selected (i.e. it's link won't be loaded) and if there is a sub menu which should appear on click, it won't be shown, too. This event is fired even for disabled items so you may want to check the select event, too.

Cancelable: Yes

Arguments:

e

The jQuery.Event object.

item

The menu item A element.

Code sample:

$('#main-menu').bind('click.smapi', function(e, item) {});

focus

Fired when an item is focused.

Cancelable: No

Arguments:

e

The jQuery.Event object.

item

The menu item A element.

Code sample:

$('#main-menu').bind('focus.smapi', function(e, item) {});

hide

Fired right after a sub menu is hidden.

Cancelable: No

Arguments:

e

The jQuery.Event object.

menu

The sub menu UL element.

Code sample:

$('#main-menu').bind('hide.smapi', function(e, menu) {});

mouseenter

Fired when an item is hovered.

Cancelable: No

Arguments:

e

The jQuery.Event object.

item

The menu item A element.

Code sample:

$('#main-menu').bind('mouseenter.smapi', function(e, item) {});

mouseleave

Fired when an item is hovered out.

Cancelable: No

Arguments:

e

The jQuery.Event object.

item

The menu item A element.

Code sample:

$('#main-menu').bind('mouseleave.smapi', function(e, item) {});

select

Fired when an item is selected, right before it's link is loaded. You can cancel the event with return false and the item will not be selected (i.e. it's link won't be loaded). This event is not fired for disabled items so you may want to check the click event, too.

Cancelable: Yes

Arguments:

e

The jQuery.Event object.

item

The menu item A element.

Code sample:

$('#main-menu').bind('select.smapi', function(e, item) {});

show

Fired right after a sub menu is shown.

Cancelable: No

Arguments:

e

The jQuery.Event object.

menu

The sub menu UL element.

Code sample:

$('#main-menu').bind('show.smapi', function(e, menu) {});

Methods

Global methods

The following methods are global for all menu instances.

destroy

Destroys all menu instances initialized on the page and cleans up everything.

Code sample:

$.SmartMenus.destroy();

hideAll

Hides (resets) all sub menus of all menu instances on the page.

Code sample:

$.SmartMenus.hideAll();

Instance methods

The following methods are available for each menu instance.

blur

Use the native JavaScript method for any menu item's A element if you need. This will deactivate the item and hide any sub menus.

Code sample:

$('a#myItem')[0].blur();

destroy

Destroys the menu instance and cleans up.

Code sample:

$('#main-menu').smartmenus('destroy');

disable

Disables the menu and optionally displays a transparent overlay DIV over the main menu.

Arguments:

noOverlay

Type: Boolean
Default value: false
If true is passed, no overlay will be displayed over the main menu.

Code sample:

// disable the menu
$('#main-menu').smartmenus('disable');

// disable the menu but don't display an overlay over the main menu
$('#main-menu').smartmenus('disable', true);

enable

Enable the menu after it has been disabled.

Code sample:

$('#main-menu').smartmenus('enable');

focus

Use the native JavaScript method for any menu item's A element to send keyboard focus to it. Note that you may need to call itemActivate first to make sure the menu containing the item is visible when you try to focus it, otherwise the item might not be focused by the browser.

Code sample:

$('a#myItem')[0].focus();

itemActivate

Activates any menu item. This will show its sub menu (if the item has a sub menu). If you want to also send keyboard focus to the item, you can additionally call the focus method.

Arguments:

$a

Type: jQuery
The jQuery wrapped A element of the item you would like to activate.

Code sample:

// activate the item
$('#main-menu').smartmenus('itemActivate', $('a#myItem'));

// activate the item and focus it
$('#main-menu').smartmenus('itemActivate', $('a#myItem'));
$('a#myItem')[0].focus();

menuHideAll

Hides (resets) all sub menus.

Code sample:

$('#main-menu').smartmenus('menuHideAll');

popupHide

Hides any popup menu. A menu is a popup menu when the isPopup: true option is set. When isPopup: false the main menu is permanent (always visible) and cannot be hidden with this method.

Arguments:

noHideTimeout

Type: Boolean
Default value: false
If true is passed, the menu will be hidden immediately, otherwise the hideTimeout option specifies the delay before hiding the popup menu.

Code sample:

// hide a popup menu
$('#popup-menu').smartmenus('popupHide');

// hide a popup menu immediately without a delay
$('#popup-menu').smartmenus('popupHide', true);

popupShow

Shows any popup menu. A menu is a popup menu when the isPopup: true option is set. When isPopup: false the main menu is permanent (always visible) and cannot be shown with this method.

Arguments:

left

Type: String
Pass a value for the CSS left declaration to be set for the popup menu before it is shown.

top

Type: String
Pass a value for the CSS top declaration to be set for the popup menu before it is shown.

Code sample:

// show the popup at left:100px;top:100px;
$('#popup-menu').smartmenus('popupShow', '100px', '100px');

// show the popup right below some target element
var $targetElm = $('#targetElm'),
    targetOffset = $targetElm.offset();
$('#popup-menu').smartmenus('popupShow', targetOffset.left, targetOffset.top + $targetElm.outerHeight());

refresh

Refreshes (re-initializes) the menu after any DOM operations have been applied - e.g. adding/removing items and sub menus or completely replacing the innerHTML of the root UL element.

Code sample:

var $menu = $('#main-menu');

// append a new main menu item
$menu.append('<li><a href="#">New item</a></li>');

// add a sub menu with 3 items to the new main menu item
$menu.children('li:last').append('<ul>  <li><a href="#">New item</a></li>  <li><a href="#">New item</a></li>  <li><a href="#">New item</a></li></ul>');

// refresh the menu after the DOM operations
$menu.smartmenus('refresh');

Tutorials

Styling the menus

You can style the menus and items the same way you can style any other unordered list on your page. The UL elements represent the menu boxes and the A elements - the menu items.

You always need to include on your pages the SmartMenus core CSS sm-core-css.css which includes just some basic rules that take care of things like resetting default list styles, main menu items arrangement, etc. And then you can either use (and modify to suit your needs) some of the default themes, or you can even use your own CSS to style the menus and items as you like.

Main menu classes - sm, sm-vertical, sm-rtl

There are some classes that you can and may need to set to your main menu (the root UL element):

sm

This is a required class you always need to set to any menu you are going to use.

Code sample:

<ul id="main-menu" class="sm"> ...

sm-vertical

Setting this class will make your main menu vertical and the items will appear one below the other. By default when this class is not set, the main menu is horizontal.

Code sample:

<ul id="main-menu" class="sm sm-vertical"> ...

sm-rtl

You need to set this class if the text in the menus is right-to-left - e.g. Hebrew, Arabic, etc. Read Using the script with RTL text (e.g. Hebrew, Arabic) for more info.

If you use some of the default menu themes, you will also need to set its class too - e.g. sm-blue and possibly sm-blue-vertical for the default blue theme.

Menu item classes - disabled, current, highlighted, has-submenu

There are some classes that you can set or are set automatically by the script to the menu items (the A elements):

disabled

You can set this class to any menu item to make it disabled. User clicks on disabled items are neglected by the script.

Code sample:

<li><a href="#" class="disabled"> ...

current

You can configure the script to set this class automatically to the item linking to the current page URL that is loaded by the browser (and optionally to its parent items). This would allow you to style the current item differently from all other items. You can control this feature via the markCurrentItem and markCurrentTree options.

highlighted

When the keepHighlighted: true option is set, the script will automatically add this class at runtime to any item that has its sub menu displayed. The class is removed as soon as the sub menu is hidden.

has-submenu

The script sets this class on init to all items that have sub menus.

Supporting touch devices

Both touch and mouse input are supported by default. You don't need to do anything about it - your menus will just work and respond to whatever input is available on the device. The script even supports simultaneous touch and mouse input (for example, an Android device with a USB mouse plugged in, a Windows 8 touch-enabled device, etc.) which means that the menus will respond properly to the mouse cursor movement and any touches at the same time.

Supporting small-screen devices (responsive menus)

By default the script supports small-screen devices by transforming any horizontal or vertical main menu with drop-down sub menus into a vertical menu bar with collapsible sub menus when the browser viewport is not wide enough.

You can control in which cases (e.g. at what width) this should happen (and should it happen at all) by using CSS media queries like you do normally for your responsive page layouts. The default themes are all optimized for small screen devices and any menus that use these themes will be automatically transformed to collapsible menus at given viewport widths. For example, the default blue theme includes the following CSS:

@media screen and (max-width: 640px) {

  /* The following will make the sub menus collapsible for small screen devices (it's not recommended editing these) */
  ul.sm-blue{width:auto !important;}
  ul.sm-blue ul{display:none;position:static !important;top:auto !important;left:auto !important;margin-left:0 !important;margin-top:0 !important;width:auto !important;min-width:0 !important;max-width:none !important;}
  ul.sm-blue>li{float:none;}
  ul.sm-blue>li>a,ul.sm-blue ul.sm-nowrap>li>a{white-space:normal;}
  ul.sm-blue iframe{display:none;}

  /* more rules to style the collapsible menu bar ... */

}

These rules are basically what is required. When you use these, the script will automatically detect when the main menu should become collapsible and take care of everything. What you may want to edit in the above media query is the max-width: 640px part where you specify the exact width break point.

If you are not using any of the default themes (i.e. you are styling your menus from scratch) and would like to make your menus collapsible on narrow viewports, you will just need to use the above CSS - just replace ul.sm-blue with the class you use or even with an id selector for your root UL element:

Using the script with RTL text (e.g. Hebrew, Arabic)

To use the script with right-to-left text you just need to set the sm-rtl class to the root UL element:

<ul id="main-menu" class="sm sm-rtl"> ...
<!-- or -->
<ul id="main-menu" class="sm sm-vertical sm-rtl"> ...

and the script will take care of everything.

Adding a menu toggle button on small screens

Here is some sample code that adds a menu toggle show/hide button on small screens.

HTML:

Add the collapsed class to the root UL element:

<ul id="main-menu" class="sm collapsed"> ...
<!-- or -->
<ul id="main-menu" class="sm sm-vertical collapsed"> ...

Add the menu button code on your page:

<a id="menu-button"></a>

CSS:

#menu-button {
  display:none;
  /* style it as you like... */
}
#menu-button:before {
  content:'Menu -';
}
#menu-button.collapsed:before {
  content:'Menu +';
}
@media screen and (max-width: 640px) {
  /* show the button on small screens */
  #menu-button {
    display:inline-block;
  }
  /* hide the menu when it has the "collapsed" class set by the script */
  #main-menu.collapsed {
    display:none;
  }
}

JavaScript:

$(function() {
  $('#menu-button').click(function() {
    var $this = $(this),
        $menu = $('#main-menu');
    if (!$this.hasClass('collapsed')) {
      $menu.addClass('collapsed');
      $this.addClass('collapsed');
    } else {
      $menu.removeClass('collapsed');
      $this.removeClass('collapsed');
    }
    return false;
  }).click();
});

This will show a menu toggle button (link) when the viewport width is less than 640px. This is, of course, just a basic example - you can tweak the styling of the button as you like, change the exact width breakpoint, etc.

Requirements

The script requires and fully supports jQuery 1.4.4+.

? Vadikom Web Ltd. 2014
Thanks to jQuery & Wordpress!