Item2107: Update JQueryPlugin::Superfish

At the moment we ship with 1.4.1.

I've been running with 1.4.8, and there are some important improvements - mostly to do with resizing the view port when menus are too big to fit the canvas (hoping I'm using the right terminology there

Superfish is fantastic. I have been working with it to make a nifty AJAX-ified breadcrumb navigation system, which I think should ship as either a SlickBreadcrumbsContrib or perhaps as an example of DBQUERY and JQuery/Superfish.

Problem: change of CSS menuClass

In 1.4.1, superfish would apply itself to ULs with the class .sf-menu. Now in 1.4.8, this has been removed and replaced with .sf-js-enabled.

I've had to make the following tweaks to the official 1.4.8 code:

--- superfish-1.4.8/js/superfish.js   2008-09-11 10:52:10.000000000 +1000
+++ jquery.superfish.uncompressed.js   2009-09-16 22:17:53.000000000 +1000
@@ -62,7 +62,7 @@
       }).each(function() {
          var menuClasses = [c.menuClass];
          if (sf.op.dropShadows  && !($.browser.msie && $.browser.version < 7)) menuClasses.push(c.shadowClass);
-         $(this).addClass(menuClasses.join(' '));
+         /*$(this).addClass(menuClasses.join(' '));*/
       });
    };
 
@@ -76,7 +76,7 @@
       };
    sf.c = {
       bcClass     : 'sf-breadcrumb',
-      menuClass   : 'sf-js-enabled',
+      menuClass   : 'sf-menu',
       anchorClass : 'sf-with-ul',
       arrowClass  : 'sf-sub-indicator',
       shadowClass : 'sf-shadow'
@@ -111,6 +111,7 @@
             sh = sf.c.shadowClass+'-off',
             $ul = this.addClass(o.hoverClass)
                .find('>ul:hidden').css('visibility','visible');
+                        this.find('>ul:hidden').css('display','view');
          sf.IE7fix.call($ul);
          o.onBeforeShow.call($ul);
          $ul.animate(o.animation,o.speed,function(){ sf.IE7fix.call($ul); o.onShow.call($ul); });

• The top change was required to avoid superfish menus from resetting/collapsing when my AJAX code decided to load new submenus. I don't think this change should be necessary (I have to find out why my options.dropShadow preference isn't being honoured).
• The middle change is obviously where we need to keep compatibility with the old usage of superfish.
• The bottom change was an IE6 hack which may not be necessary any more (will test later).

Question

Assuming I can make menuClass an array variable so that both .sf-menu and .sf-js-enabled are recognised (the code looks like it should be able to cope with this), what's the best way to maintain a foswiki patched version of an upstream component?

1. Keep a .diff and the original .js in the plugin somehwere? Is there a way BuildContrib can apply patches and generate our custom foswiki'd JS for us?
2. Or just hack the .js in-place, manually?

Allow users to select a default css with JQREQUIRE or similar

At the moment JQREQUIRE for superfish doesn't include any CSS at all (even though we ship with some superfish .css). The author of superfish ships a few alternatives (default, navbar, vertical). It would be good if users can use JQREQUIRE to get the JS and default CSS added to HEAD automatically, and we should provide a way to include specific default-superfish CSS files.

Question

Do we add a new tag handler? Or can JQREQUIRE do it for us?

Add Supersubs plugin

This is a remarkably useful add-on to Superfish, and I think we should ship it by default with Superfish. It dynamically resizes menus (within specified limits) to accommodate the contents.

Question

How do we add a plugin for a JQueryPlugin::Plugin?

Update documentation

I find myself reading the JQueryPlugin code a lot. I hope to update the docs with a clear list of tags and examples.

-- PaulHarvey - 20 Sep 2009

distro:22eb9075e9fd was no good idea as it breaks theming of menus in NatSkin. Will revert it.

-- MichaelDaum - 22 Sep 2009

I should have realised. Sorry, reverted. Will think about how to selectively include things with JQREQUIRE.

-- PaulHarvey - 22 Sep 2009

Updated. Added SUPERSUBS. Todo: add examples.

-- PaulHarvey - 08 Nov 2009

Added examples. Todo: clean up examples (remove HTML and replace with Foswiki TML equiv.)

-- PaulHarvey - 08 Nov 2009

NatSkin menus broken again, most probably due to class name changes...fixed in local copy ... releasing

-- MichaelDaum - 09 Nov 2009

Part of distro:b59960963486 removed a patch I had to upstream menuClass JS. I decided to remove our custom patch because I thought it would be nice to not patch upstream things unless really necessary.

See http://trac.foswiki.org/browser/trunk/JQueryPlugin/pub/System/JQueryPlugin/plugins/superfish/jquery.superfish.uncompressed.js.diff?rev=5455 and http://trac.foswiki.org/browser/trunk/JQueryPlugin/pub/System/JQueryPlugin/plugins/superfish/Makefile?rev=5455.

But perhaps it could be incorporated after all. Or I should at least add a note to the release history that .sf-menu should be replaced with .sf-js-enabled

-- PaulHarvey - 09 Nov 2009

Best would be if superfish allowed to define the menu class provided in the options array to the superfish call. Then we would be able to write a wrapper to make markup like this

%JQREQUIRE{"superfish"}%
<div class="superfish {menuClass: 'my-super-fish'}"
   * item1
   * item2
   * item3
</div>

a superfish menu and define specific css for my-super-fish that won't interfere with other menus.

I was looking at the javascript code to see why this doesn't work out like this. Hm, this needs an upstream patch.

-- MichaelDaum - 10 Nov 2009