Install Superfish

Last updated on

6 June 2022

What is this module?

This module implements the jQuery plugin called Superfish [1] on Drupal menus. It provides Drupal users the ability to add some "splash" to Drupal menus with very little effort.

Dependencies

Drupal 8 & 9
- Superfish library 2.x
Drupal 6 & 7
- Superfish library 1.x
- Drupal 6 only: jQuery 1.3.x or higher, through the jQuery_update module v2.x

Installation

Drupal 8 & 9

Through Composer:

composer require drupal/superfish
More information.

Through your Web browser:
1. Download the Superfish library 2.x and extract it somewhere like /sites/all/libraries/superfish (so that the superfish.js will be located at http://example.com/sites/all/libraries/superfish/superfish.js)
2. Download and extract the Superfish module in /sites/all/modules or /modules.
3. Go to the Extend section of your Drupal administration back-end and enable the Superfish module.
Drupal 6 & 7
1. Download the Superfish library 1.x and extract it somewhere like /sites/all/libraries/superfish (so that the superfish.js will be located at http://example.com/sites/all/libraries/superfish/superfish.js)
2. Download and extract the Superfish module in /sites/all/modules.
3. Go to the Modules section of your Drupal administration back-end and enable the Superfish module.
Drupal 6 users need to install jQuery_update module v2.x too.
You can also use Drush to install this module.

Update

Updating the module is similar to updating any other Drupal module; you can either download the latest version and upload it to your modules directory or use the update manager to automatically update it.

Updating the Superfish library however is a bit different, since it consists of JavaScript and CSS some people ignore the warning and instructions in the README file and elsewhere and just edit the files there directly - especially the CSS.
If you are not sure whether changes were made please backup the directory (/libraries/superfish) before uploading the new library, otherwise just follow these simple steps:

Download the latest version from Github:
- Drupal 8 & 9
  https://github.com/mehrpadin/Superfish-for-Drupal/archive/2.x.zip
- Drupal 6 & 7
  https://github.com/mehrpadin/Superfish-for-Drupal/archive/1.x.zip
Unzip the file and rename the Superfish-for-Drupal directory to just superfish - all lowercase please.
Upload the superfish directory to your libraries directory, usually /sites/all/libraries
(so that the superfish.js for example will be at /sites/all/libraries/superfish/superfish.js and publicly accessible through http://example.com/sites/all/libraries/superfish/superfish.js)

Usage

What you need first is a menu. If you don't have a menu to play with, go and build one. As an example, here is a typical menu structure:
```
Parent Menu 1
  |_ Child Menu 1
Parent Menu 2
  |_ Child Menu 1
  |_ Child Menu 2
    |_ Sub Child Menu 1
    |_ Sub Child Menu 2
Parent Menu 3
```
The above structure has several links that go to different pages on your website and some of them are child menus to a parent menu. If you are a seasoned veteran of the Drupal menu system, you already know that every single menu [4] created by Drupal also produces a companion menu block [5]. If you create a menu and call it something like "Pink Fuzzy Bunny Navigation", a block will appear on your blocks list and it will also be called "Pink Fuzzy Bunny". Once you've created a menu to play with, lets configure your Superfish menu.
- Drupal 8 & 9
  - In Drupal 8 or 9, when you Place New Block, each of your existing menus will also have a Superfish version.
  - Go to the "Block layout" page (under Structure) and use any of the "Place block" buttons to create a Superfish block. Tip: Search for your menu using 'menu' as the search term and make sure to select the one with the "Superfish" category
- Drupal 6 & 7
  - Go to your blocks administration page; You will see several blocks called Superfish", move any of them to a region and save.
Use the "Configure" link of the block to configure it accordingly to your needs.
Navigate to front-end to meet your Superfish menu :)

Block Settings

Block title: This is just the typical block title that appears above the block content. Use of tokens here is supported if enabled.
Menu Name: The name you wish to give your menu. This name will be applied to any generated CSS classes in your block.
Menu Parent: The menu you want to be displayed using Superfish.
Menu Depth: You may control the number of child menus that you wish to use. Leaving this set as "-1" will use all child menus under their parent menu items.
Menu Type: The style of menu you want to see. Your choices are: Horizontal (drop downs), Vertical (sideways fly outs), and NavBar (dual level menus).
Style: There are several default "flavors" of menus you may choose from.
Animation Speed: The speed of the animation either in milliseconds or pre-defined values (slow, normal, fast). (Default: normal)
Mouse Delay: When someone takes their mouse cursor away from the menu, how long do you want it to linger?
Path class: The class you have applied to list items that lead to the current page. (Default: active-trail).
Path levels The number of levels of submenus that remain open or are restored using Path class. (Default: 1).
Slide-in Effect: Do you want your menu to appear to slide in when it appears?
Drop shadows: Do you want your menus to have drop shadows?
Auto Arrows: Do you want your menus that have children to show an arrow to indicate this?
Superfish plugins:
- jQuery BgiFrame plugin: This helps with z-index issues with Internet Explorer.
- jQuery Supposition plugin: Relocates sub-menus when they would otherwise appear outside the browser window area.
- jQuery hoverIntent plugin: Prevents accidental firing of animations by waiting until the user's mouse slows down enough, hence determinig user's intent.
- jQuery sf-Touchscreen plugin: Provides better functionality for touchscreen devices.
- Supersubs Supersubs allow you to set menu width limits for your child menu items.
Multi-column sub-menus: (Beta) Displays child menu items together with their own children. The level is determined by the Levels option (just below the multi-column checkbox) as columns rather than dropdowns.
This sometimes requires the menu structure to be altered slightly, the below menu for example cannot be rendered correctly:
```
Parent Menu 1
Parent Menu 2
  |_ Child Menu 1
  |_ Child Menu 2
    |_ Sub Child Menu 1
    |_ Sub Child Menu 2
    |_ Sub Child Menu 3
  |_ Child Menu 3
  |_ Child Menu 4
  |_ Child Menu 5
Parent Menu 3
```
But by changing it a little a bit the Parent 2 will get 3 columns.
```
Parent Menu 1
Parent Menu 2
  |_ Child Menu 1
    |_ Sub Child Menu 1
    |_ Sub Child Menu 2
  |_ Child Menu 2
    |_ Sub Child Menu 1
  |_ Child Menu 3
    |_ Sub Child Menu 1
    |_ Sub Child Menu 2
    |_ Sub Child Menu 3
```
Please do not misuse multi-column sub-menus:
Highly recommended: Mega Menus Work Well for Site Navigation [7]. See also: Mega Menus Gone Wrong.
Advanced HTML settings:
- Include hyperlinks description (title) in hyperlinks text: As the title says, this adds hyperlinks description to the hyperlink text.
  Sample output:
```
<a href="#">Register <span class="sf-description">Register today &amp; receive a 10% discount!</span></a>
```
- HTML wrappers: Add wrapper around various parts of a menu tree.
Advanced CSS settings: Various class options, just read the labels.
- Helper classes:
  1. Add First / Last classes Do you want the first and last menu items in a menu structure to have an additional "first" and "last" class applied to them. You can remove unwanted borders or colors on the first and last menu items.
  2. Add Zebra striping Do you want the menu items in a menu structure to have an additional "even" and "odd" class applied to them. You can then tell alternating menu items they should adopt different styling.
  3. Do not add First / Last Classes (Single Menu Item) Removes any "first" and "last" classes on single menu items since that would just look silly.
  4. Do not add Zebra Striping (Single Menu Item) Removes any zebra striping on single menu items since that would just look very silly.
  5. Add item counts to menu items This allows you to add menu item counts that are added to the classes. Great for custom menu item styling.
  6. Add children counter classes to menu items Adds custom classes to items based on the number of their children.
  7. Add item depth class to menu items and their hyperlinks Adds custom classes to items represting their depth in the menu tree.
- Custom classes: Add any custom classes you may want to use.
- Extra CSS Add any CSS commands you can think of.

How to style

In the block configuration page, set the Style to None
Copy one of the Superfish sample styles, for example default.css from sites/all/libraries/superfish/style to your theme; either as a separate CSS file or part of the main CSS file of your theme.
Rename the selectors .sf-style-default to .sf-style-none or remove them altogether.
You are now ready to unleash your CSS artistry :)

Some design tips:

Utilize a DOM inspector (such as Firebug) for temporarily modifying live code in real time.
Set the Mouse delay of the block settings to 99999999 so the sub-menus will stay open for a longer time giving you more time to work with them in Firebug etc.

Known Issues

Read this section only if IE6 matters to you!

The CSS part of the jQuery Superfish plugin - and not this module - has a problem (infamous z-index issue) with the Microsoft Internet Explorer.
- CSS solution: http://webdemar.com/webdesign/superfish-jquery-menu-ie-z-index-bug/
- Javascript solution: http://drupal.org/node/790576#comment-2947882
(If you would like to help defeat such bugs, support the drive to end Internet Explorer 6 and help web users upgrade to modern browsers [6]. More information can be found on Google's What Browser website [8].)
As reported here in #719638 - Submenu behind Flash Items in IE, the sub-menus sometime appear "behind" the flash movies.
The solution: [9]
1. Set the z-index of the DIV holding the flash to 1 and the z-index of the DIV holding the menu to 2.
2. In the flash element, look for the flash <object> tag and add the following code:
  <param name="wmode" value="transparent">
  You’ll want to insert this code right below the <param name=”quality” value=”high”> tag and include the code wmode=”transparent” in the flash <embed> tag.
As reported here in #838062 - Fuzzy text (ClearType bug) in IE, there are some potential problems with ClearType in Microsoft Internet Explorer, a fix for this problem is located here [9], also available in the above link.
Navbar style: first child menu always appears
Solution: Set the Path Levels to 0.