WHAT’S NEW

• New option! – fullscreen : false
  (resize box & refresh to test. use menu on bottom.)
• Many gallery
• Randomize your galleries
• Try new API to push/pop, shift/unshift images from outside (mandatory one image in markup)
• See a basic push example
• See how push hundreds images from outside (my picasa feed)
• See an example of adapter that use new API
• Test zoom, centered and original style option
• Caption simplified and improved (see html markup)

jbgallery is a UI widget webpage written in javascript on top of the jQuery library.
Its function is to show a single big image, multiple images, multiple galleries, slideshows, as a site’s background, in a “dialog” mode or as a common pop-up.

jbgallery has two basic menus: the first one has music player buttons while the other one links directly to single images.
I added a “complex” menu on the 2.0 version, which is inspired by the flickr slider-equipped slideshow that allows to scroll the thumbnail previews.
jbgallery provides a pubblic API to remote control the component, so it would be easier to bind also with a more complex menu.

Examples:

• Option “fullscreen” – default true (jQuery UI resizable only for test):
  • box gallery (NEW option! fullscreen : false)
  • multi box gallery (NEW option! fullscreen : false)
• Option “style” – default “centered”:
  • centered (default)
  • zoom
  • original
• Option “menu” – default “simple”:
  • simple (default)
  • slider
  • numbers
  • nothing (slideshow true, use arrows)
• Option “caption” – default true:
  • caption (see html markup)
  • no caption (caption disabled)
• Option “timers”:
  • interval
  • No fade effect (menu simple)
  • No fade effect (menu slider)
• Option “autohide” – default false:
  • autohide (menu slider)
  • autohide (menu numbers)
• Option “randomize” – default 0:
  • randomize first image – randomize : 1
  • randomize slideshow – randomize : 2
• custom labels
• clickable – option clickable (default : false)
• Debug style (debug style)
• Option “popup” – default 0:
  • multiple gallery same page
  • “overlay” vs window.open (see “permalink”)
• “Old Hack” – deprecated (use caption):
  • links over image
• API & Advanced options for developers/designers:
  • callback (basic callback)
  • api (menu slider)
  • api (menu numbers)
  • api (menu simple)
  • callback on push/pop/unshift/shift
• API demo (hundreds images push via yql & picasa):
  • slider
  • simple
  • numbers – note the limitations of this menu
  • basic example of push
• ADAPTERS (picasa):
  • all album – new version with api
  • filter by album – new version with api
  • all album – old version
  • filter by album – old version

Installation

Download and extract

jbgallery-3.0.beta.zip

Download single files :

• jbgallery-3.0.js : source | min
• jbgallery-3.0.css
• ajax-loader.gif
• sprite.png
• opacity.png
• jquery-1.4.4.min.js

Extra files :

• jbpicasa.js : source – new version.
• jbpicasa.js : source – test adapter that you can use building an html structure, getting data from an external rss feed.

Usage

js and css (include in head tag)

<link href="jbgallery-3.0.css" rel="stylesheet" media="screen" />
<script type="text/javascript" src="jquery.1.4.2.min.js"></script>
<script type="text/javascript" src="jbgallery-3.0.js"></script>

HTML structure (minimal menu)

<div class="jbgallery">
 <ul>
  <li><a href="1.jpg" >1</a></li>
  <li><a href="2.jpg" >2</a></li>
  <!-- etc -->
 </ul>
</div>

HTML structure (thumbnails – menu with slider)

<div class="jbgallery">
 <ul>
  <li><a href="big1.jpg"><img src="small1.jpg" alt="" /></a></li>
  <li><a href="big2.jpg"><img src="small2.jpg" alt="" /></a></li>
  <!-- etc -->
 </ul>
</div>

HTML structure (caption)

[/html]
<div class="jbgallery">
 <ul>
  <li>
   <a href="big.jpg" title="Caption title" rel="Caption title link"><img src="small.jpg" alt="" /></a>
   <div class="caption">Long long long text</div>
  </li>
  <!-- etc -->
 </ul>
</div>

1

JS

<script type="text/javascript">
jQuery(document).ready(function(){
  jQuery(".jbgallery").jbgallery();
});
</script>

OPTIONS & DEFAULTS

Write options HERE :

    jQuery('.jbgallery').jbgallery({HERE});

{
  //option   : default value     //see docs/demo for usage - PLEASE FIX MY ENGLISH IF YOU CAN & SEND ME  (thanks!)
    style    : "centered",       //"centered"|"zoom"|"original" - image style
    menu     : "slider",         //false|"numbers"|"simple"|"slider" - menu type
    shortcuts: [37, 39],         //[prev,next] - keyboard code shortcuts
    slideshow: false,            //true|false - autostart slideshow
    fade     : true,             //true|false - disable all fade effects
    popup    : false,            //true|false - modal box & traditional popup hack to display multiple gallery (3.0 : fullscreen:false)
    randomize: 0,                //0|1|2 - randomize first image (1) or randomize "slideshow" (2) - blackout: http://www.grayhats.org
    caption  : true,             //true|false - show/disable internal caption system
    autohide : false,            //true|false - auto hide menu & caption
    clickable: false,            //true|false - "image click & go"
    current  : 1,                //number     - set initial photo (modal "hack" - see demo. don't use "hash". jbgallery use "location.hash" only in popup mode)
    webkit   : (navigator.userAgent.toLowerCase().search(/webkit/) != -1),  //boolean - used for specific browser hack. if you want, you can force disable this flag & try to find crossbrowser solution
    ie6      : (/MSIE 6/i.test(navigator.userAgent)), //boolean - IDEM
    ie7      : (/MSIE 7/i.test(navigator.userAgent)), //boolean - IDEM
    labels   : {                 //labels of internal menu
        play : "play",
        next : "next",
        prev : "prev",
        stop : "stop",
        close: "close",
        info : "info"
    },
    timers   : {                 //timers
        fade    : 400,           //fade duration
        interval: 7000,          //slideshow interval
        autohide: 7000           //autohide timeout
    },
    delays: {                    //delays (timers) to improve usability and reduce events
        mousemove: 200,          //used by autohide. cancel autohide timeout every XXXms.
        resize   : 500,          //used by ie6 to reduce events handled by window.resize
        mouseover: 800           //used by tooltip. show tooltip only if the mouse STAY over thumb for XXXms
    },
    close    : function(){},     //callback handled by menu's button close. see demo. example : close : function(){window.close()}
    before   : function(){},     //callback handled BEFORE image gallery loaded
    after    : function(ev){},   //callback(ev) handled AFTER image gallery loaded. receive the native load event.
    load     : function(ev){},   //callback(ev) handled AFTER native image load event. receive the native load event.
    ready    : function(el){},   //callback(el) handled AFTER jbgallery render. receive the HTML element.
    //WHAT'S NEW - 3.0
    fullscreen: true,            //true|false : the most important feature of jbgallery 3.0. now jbgallery can "stay in a box" and have multiple istance in one page.
    push      : function(o){},   //callback handled by push public method (JBGALLERY API). receive the object/string/array of objects/array of strings passed from external. useful for external menu system
    unshift   : function(o){},   //callback handled by unshift public method (JBGALLERY API). receive the object/string/array of objects/array of strings passed from external.
    shift     : function(){},    //callback handled by shift public method
    pop       : function(){},    //callback handled by pop public method
    empty     : function(){}     //callback handled by empty public method
}

API (developers/designers)

var obj = jQuery("#jbg").jbgallery({menu : "slider"}, true);//GET API
obj.left();
obj.right();
obj.go(3);
obj.current();
obj.play(4000);
obj.stop();
obj.push(single);//single = 'http://url'
obj.push(aobj);//aobj is array of object
obj.unshift(obj);//obj is a single object
obj.unshift(arr);//arr is an array of string (url)
obj.shift();
obj.pop();
obj.empty();
obj.destroy();

EXAMPLE

var images = {
    single : 'http://lh5.ggpht.com/_JJJpzXdPAI4/SpzvbyPhCHI/AAAAAAAAA-w/rf8dATWiOK8/100_2274.jpg',
    arr : ['http://lh3.ggpht.com/_JJJpzXdPAI4/SpzvrjvU83I/AAAAAAAABAU/8tbAipa9wgk/P1020533.jpg','http://lh5.ggpht.com/_JJJpzXdPAI4/SpzuSpC-0zI/AAAAAAAAA48/M2GPV81K4Ak/100_2090.jpg'],
    obj : {
        href : 'http://lh5.ggpht.com/_JJJpzXdPAI4/SpzvjOmg5-I/AAAAAAAAA_g/S8wow3zLays/P1020744.jpg',
        title: 'Hiroshima',
        rel  : 'http://en.wikipedia.org/wiki/Hiroshima',
        caption : 'Hiroshima (広島市, Hiroshima-shi?) (About this sound listen (help·info)) is the capital of Hiroshima Prefecture, and the largest city in the Chūgoku region of western Honshū',
        caption_css : 'custom'
    },
    aobj : [{
        href : 'http://lh5.ggpht.com/_JJJpzXdPAI4/SpzvjOmg5-I/AAAAAAAAA_g/S8wow3zLays/P1020744.jpg',
        thumb: 'http://lh5.ggpht.com/_JJJpzXdPAI4/SpzvjOmg5-I/AAAAAAAAA_g/S8wow3zLays/s288/P1020744.jpg',
        title: 'Hiroshima',
        rel  : 'http://en.wikipedia.org/wiki/Hiroshima',
        caption : 'Hiroshima (広島市, Hiroshima-shi?) (About this sound listen (help·info)) is the capital of Hiroshima Prefecture, and the largest city in the Chūgoku region of western Honshū',
        caption_css : 'custom'
    },{
        href : 'http://lh5.ggpht.com/_JJJpzXdPAI4/SpzvbyPhCHI/AAAAAAAAA-w/rf8dATWiOK8/100_2274.jpg',
        title: 'Magome-juku'
    }]
};
obj = jQuery("#jbgallery-api").jbgallery({menu : "slider"}, true);//GET API
jQuery("#mm-empty").click(function(){
    obj.empty();
});
jQuery("#mm-push").click(function(){
    obj.push(images.single);
});
jQuery("#mm-pushmany").click(function(){
    obj.push(images.aobj);
});
jQuery("#mm-shift").click(function(){
    obj.shift();
});
jQuery("#mm-pop").click(function(){
    obj.pop();
});
jQuery("#mm-unshift").click(function(){
    obj.unshift(images.obj);
});
jQuery("#mm-unshiftmany").click(function(){
    obj.unshift(images.arr);
});

NOTES

BROWSERS TESTED

• Firefox 3.6
• Chrome 8,9
• IE6,7,8,9
• Opera
• Safari

DESIGN

This component is published with two graphic layout.

You are free to customize css and to ask me any change to add classes to the menus edited by me.
If you use API or design more complex menus, or if you write plugins populating html lists pushing images
(see picasa 3.0 adapter) via ajax by flickr
or similar services, please share with me for the next version of this plugin.

CREDITS

This work is inspired by http://www.ringvemedia.com/ and Chicca
The slider is inspired by http://www.flickr.com/search/show/

Depends on jQuery (1.4.4) by John Resig.

Thanks to Carlo Denaro, Simone Parato, Aaron Hutten, Alain Bourgeoa, Steffen Wenzel

CONTACTS

Post a comment on this post.

LICENSE

Copyright (c) 2010 Massimiliano Balestrieri

Licensed GPL licenses:
http://www.gnu.org/licenses/gpl.html

DEMO SITE – (UPDATED 2010-12-20)

jbgallery is a UI widget webpage written in javascript on top of the jQuery library.
Its function is to show a single big image, multiple images, multiple galleries, slideshows, as a site’s background, in a “dialog” mode or as a common pop-up.
jbgallery has two basic menus: the first one has music player buttons while the other one links directly to single images.
I added a “complex” menu on the 2.0 version, which in inspired by the flickr slider-equipped slideshow that allows to scroll the thumbnail previews.
jbgallery provides a pubblic API to remote control the component, so it would be easier to bind also with a more complex menu.

Examples:

• Option “style”:
  • centered (default)
  • zoom
  • original (NEW : 2010-09-01)
• Option “menu”:
  • slider (default) *NEW
  • numbers
  • simple
  • nothing (slideshow true, use arrows)
• Single image background
• Single image centered
• Multi “fullscreen lightbox” gallery (2010-12-15 – update)
• Randomize first image (2010-12-15 – update)
• Randomize slideshow (2010-12-15 – update)
• “Fullscreen lightbox” vs Traditional popup (2010-12-15 – update)
• Custom labels
• No fade effect
• No fade effect (slider)
• Timers: interval
• Timers: autohide
• Callback for developers
• Api for designer/developers
• Clickable
• Picasa adapter (NEW)
• Picasa adapter (NEW) (album)
• Style test

Installation

Download and extract

jbgallery-2.0.zip (update: 2010-12-20)

Download single files :

• jbgallery-2.0.js : source | min
• jbgallery-2.0.css
• ajax-loader.gif
• sprite.png
• jquery-1.4.2.min.js

Extra files :

• jbpicasa.js : source – test adapter that you can use building an html structure, getting data from an external rss feed.

js and css (include in head tag)

<link href="jbgallery-2.0.css" rel="stylesheet" media="screen" />
<script type="text/javascript" src="jquery.1.4.2.min.js"></script>
<script type="text/javascript" src="jbgallery-2.0.js"></script>

HTML structure (minimal menu)

<div class="jbgallery">
 <ul>
  <li><a href="1.jpg" >1</a></li>
  <li><a href="2.jpg" >2</a></li>
  <!-- etc -->
 </ul>
</div>

HTML structure (thumbnails – menu with slider)

<div class="jbgallery">
 <ul>
  <li><a href="big1.jpg"><img src="small1.jpg" alt="" /></a></li>
  <li><a href="big2.jpg"><img src="small2.jpg" alt="" /></a></li>
  <!-- etc -->
 </ul>
</div>

HTML structure (caption)

<div class="jbgallery">
 <ul>
  <li>
   <a href="big.jpg" title="Caption title"><img src="small.jpg" alt="" /></a>
   <div class="caption">Long long long text</div>
  </li>
  <!-- etc -->
 </ul>
</div>

JS

<script type="text/javascript">
jQuery(document).ready(function(){
  jQuery(".jbgallery").jbgallery();
});
</script>

OPTIONS & DEFAULTS

Write options HERE :

 jQuery(".jbgallery").jbgallery({HERE});

DEFAULTS

{
  style     : "centered",//centered, zoom, original
  menu      : 'slider', //false, numbers, simple, slider
  shortcuts : [37,39],
  slideshow : false,
  fade      : true,
  popup     : false,
  caption   : true,  //NEW 2.0
  autohide  : false, //NEW 2.0
  clickable : false, //NEW 2.0
  current   : 1,   //NEW 2.0
  randomize : 0,   //NEW 2.0
  webkit    : (navigator.userAgent.toLowerCase().search(/webkit/) != -1),
  ie6       : (/MSIE 6/i.test(navigator.userAgent)),
  ie7       : (/MSIE 7/i.test(navigator.userAgent)),
  labels    : {
    play : "play",
    next : "next",
    prev : "prev",
    stop : "stop",
    close: "close",
    info : "info"
  },
  timers    : {
    fade      : 400,
    interval  : 7000,
    autohide  : 7000
  },
  delays    : {
    mousemove : 200,
    resize    : 500,
    mouseover : 800
  },
  close     : function(){},
  before    : function(){},
  after     : function(ev){},
  load      : function(ev){},
  ready      : function(){}
}

OPTIONS

• style : string (‘zoom’/'centered’/'original’)
• slideshow : boolean (true/false)
• menu : string/boolean (‘slider’/'simple’/'numbers’/false)
• caption : boolean (show info button in menu – NEW)
• autohide: boolean (autohide interface – NEW)
• clickable: boolean (NEW)
• current: number (set the initial photo NEW)
• randomize : numeric (0/1/2 – NEW – 0 default | 1 randomize first image | 2 randomize slidshow/prev/next – thanks to Carlo Denaro – blackout: http://www.grayhats.org)
• fade : boolean (false/true)
• shortcuts : array (keycodes for trigger events left/right via keyboard)
• before: function (callback)
• load : function(ev) (callback – native image load event)
• after : function (callback)
• ready : function (callback – interface ready)
• popup : boolean (show close button)
• close : function(ev) (callback after click close button. i.e. window.close())
• labels: object – default:

  {
     play : "play",
     next : "next",
     prev : "prev",
     stop : "stop",
     close: "close",
     info : "info"
  }
  

• timers: object – default:

  {
    fade      : 400,  //fadeIn-Out timer
    interval  : 7000, //slideshow timer
    autohide  : 7000  //autohide timer
  }
  

• delays: object – default:

  {
    mousemove : 200,
    resize    : 500,
    mouseover : 800
  }
  

API (developers/designers)

• jQuery(“#jbgallery”).jbgallery(); // build object FIRST
• jQuery(“#jbgallery”).jbgallery(“go” , 2); // go to photo 2 if exist
• jQuery(“#jbgallery”).jbgallery(“left”); // prev photo
• jQuery(“#jbgallery”).jbgallery(“right”); // next photo
• jQuery(“#jbgallery”).jbgallery(“play”); // autoplay start
• jQuery(“#jbgallery”).jbgallery(“stop”); // autoplay stop
• jQuery(“#jbgallery”).jbgallery(“destroy”); // destroy object, events, expando
• jQuery(“#jbgallery”).jbgallery(“current”); // return number of current photo

CONTENTS/FURTHER ELEMENTS

To add to the image further contents or other kind of elements you can use the following div. Otherwise you can add other divs copying the styles below.

<div id="jbg-content">
    <!-- PUT HERE CONTENT -->
    <div id="docs">
        <div class="wrapper">
        </div>
    </div>
    <!-- /PUT HERE CONTENT -->
</div>

#docs{width:500px;right:200px;top:15%;position:absolute;z-index:1000;}
#docs .wrapper{padding:10px;margin:10px;background:#fff;}

BROWSERS TESTED

• Firefox 3.5 (winxp/linux)
• Safari 3.2, 4 (winxp)
• Chrome/Chromium (winxp/linux)
• Opera 9/10/11 (winxp/linux)
• Internet Explorer 6/7/8 (winxp)

DESIGN/GRAPHIC

This component is published with a minimalist graphic layout.
You are free to customize css and to ask me any change to add classes to the simple menus edited by me.
If you use API or design more complex menus, or if you write plugins populating html lists via ajax by flickr
or similar services, please share with me for the next version of this plugin.

CREDITS

This work is inspired by http://www.ringvemedia.com/ and Chicca
The slider is inspired by http://www.flickr.com/search/show/

Depends on jQuery (1.3.2/1.4.2) by John Resig.

Thanks to Carlo Denaro, Simone Parato, Aaron Hutten, Alain Bourgeoa, Steffen Wenzel, krko.

COMMENTS & CONTACTS

Post a comment on my blog.
http://maxb.net/blog/

LICENSE

Copyright (c) 2010 Massimiliano Balestrieri
Licensed GPL licenses:
http://www.gnu.org/licenses/gpl.html

The false positive was mainly caused by my initial mistake.

Before explaining the initial mistake that could still be common, and lead others in “error”, I would like to clarify that both rev.1159 and rev.1214 (current) do not contain the bug I thought I had found.

There is no need to patch the library by adding the destroy method.

The library Markerclusterer already exposes a method to correctly destroy the clusters: clearMarkers .

clearMarkers works

The initial mistake I made was to isolate within a function instance

var markerclusterer = new Markerclusterer(map, points);

Having Isolated markercluster in the function called by the form, at each form submit I wouldn’t be able to call clearMarkers methods, not having access to the previously created instances.

map.clearOverlay() is not enough .

You have to remove the clusters explicitly otherwise the first trigger ZoomIn ZoomOut keys of the map would show clusters of the previous search.

To summarize, use the library Markerclusterer

1) before removing the clusters:

markerclusterer.clearMarkers();

2) then wipe the map with

map.clearOverlays();

For those who want to analyze the working code I release two demos that are going to overwrite the previous:

• with a programming mistake not due to the library
• with a proper usage of clearMarkers

Another thing that could lead to errors (more false positives) is that after a zoom in / out clusters might be slightly different.

• many clusters

Searching “Test 2″ you’ll find 3 clusters over the Western Alps

Triggering a ZoomOut and then a ZoomIn, the clusters will be slightly different than before. Increasing the number of clusters it’s clearer something went wrong.

• PICASA
• FLICKR

Pubblico due snippets di codice, per popolare jbgallery via Flickr o Picasa.
Il vantaggio è avere a “costo zero” un backoffice per la gestione della galleria.

ISTRUZIONI PER L’USO

Includere gli script e il markup della demo, e configurare le variabili.

PICASA

var _n_albums = 10;
var _account = 'massimiliano.balestrieri';
var _filter_album = 'Japan2009009Persone';//false

Per Picasa configurare l’account, il numero di album da cui prendere le immagini, e l’eventuale filtro (impostato a false non ci sarà filtro) per visualizzare un solo album.

FLICKR

var _photoset = '72157619533884851';

Per Flickr configurare il “photoset”*.

*Foto di Chicca Vancini

• BUG
• FIX
• PATCH

Carlo and I, working together on this application have met a problem hard to isolate and solve.

Markerclusterer library (of gmaps-utility-library-dev) has a bug.
Let me try to explain the problem.

Each cluster has an event associated with it (in fact, the click event on the cluster triggers the “zoom in” on the map and the cluster splits itself in markers or smaller clusters).
When, from the outside (for example, within a form), I clean the map – map.clearOverlays(); – and then I refill it with a new search, I’m not able anymore to destroy the clusters.
It seems the clusters are disappeared but, in fact, zooming in or out, they come back.
Look at the two following pictures.

STEP 1

STEP 2

ZOOM OUT

The first and second picture shows the clusters correctly.
The third picture instead (demo bug) shows the clusters of the second search AND the ones of the first (after having done “zoom out”).

The whole thing is due to a bug in the JavaScript garbage collection (I suppose…).
The object has been “subscribed” to an event. The object is destroyed but after the first trigger of that event, the object come back.

To fix this strange bug (it’s even hard to reproduce it, without a form!) it’s mandatory to provide to the markerclusterer library a method to correctly destroy the clusters.
The patch (the diff file has been written again the 1159 revision) adds the destroy method.
Before doing a new search, it is required to call

map.clearOverlays();

AND

markerCluster.destroy();

where markerCluster is your instance of MarkerClusterer(map, points);

this.clearMarkers();
GEvent.removeListener(mcfn_);
mcfn_ = null;
me_ = null;

I reported the bug to the developers with a demo of the bug itself (and a second demo with the fix). I hope my patch could help people to not get mad on it.

(This should be a crosspost written with Carlo)

It seems that MarkerClusterer has a bug, fixed with this patch (*) written by me while I was hunting with Carlo for it on this application (now working fine): after the ajax submit and zooming out, the library was still displaying old clusters and markers, because, after destroying MarkerClusterer, the event assigned to GEvent wasn’t correctly removed.

(*) the patch is created against the r1159 version on gmaps-utility-library-dev.

Per chi non avesse la pazienza di leggere, o per chi semplicemente non è italiano, o per gli autori di Jcrop, qui sotto c’è un elenco di link in cui i linguaggi sono universali:  html, javascript (jQuery) e qualche proprietà di css.

• esempio base
• inserire le aree
• visualizzare le aree inserite
• esempio con shapes disegnate
• trigger dell’evento release

DOWNLOAD

DEMOS

IL TAG MAP

Il tag map, e il “sottotag” area permettono di “disegnare” link all’interno di un immagine.

<img src="planets.gif" width="145" height="126" alt="Planets" usemap="#planetmap" />

<map name="planetmap">
  <area shape="rect" coords="0,0,82,126" alt="Sun" href="sun.htm" />
  <area shape="circle" coords="90,58,3" alt="Mercury" href="mercur.htm" />
  <area shape="circle" coords="124,58,8" alt="Venus" href="venus.htm" />
</map>

Qui c’è un esempio di utilizzo.

LIMITI DEL TAG MAP

Il limite principale di questo tag è a mio modo di vedere l’impossibilità di applicare stili ai tag “AREA” presenti all’interno.
In pratica l’unico indizio visivo del link all’interno di una certa porzione di immagine, che viene dato all’utente, è il cursore.
Non è possibile anche solo applicare bordi.
Tutto questo fondamentalmente perchè il tag map permette di creare aree di tipo “rect” (e non sarebbe un problema per un browser disegnarne il bordo), “circle”, “poly”.
Quindi il browser dovrebbe saper disegnare (canvas).

Altro limite, ma non direttamente del tag, è la difficoltà di scrivere le coordinate.

ALTERNATIVE AL TAG MAP

Listapart ci aveva già pensato, e suggerisce di creare qualcosa di completamente diverso. Javascript legge una lista, disegna dei punti in posizione assoluta, e al click (o al mouseover) visulizza un tooltip.

L’idea è quella.

Siccome il mio problema comunque, era di dare in mano ad un redattore uno strumento per inserire i punti, ho iniziato a fare scouting di plugins che disegnassero aree sopra un’ immagine.

JQUERY JCROP

Ecco che arrivo a Jcrop.

Jcrop è un plugin jQuery principalmente pensato per tagliare immagini.

Inizialmente non pensavo di usarlo come sostituto dei tag map/area.

Pensavo solo di usare le coordinate che restuitiva, salvarle nel database e successivamente creare le aree lato “frontoffice” leggendo dal database le coordinate salvate dal redattore della mappa.

Quindi l’avevo scelto come strumento di backoffice.

Qui un semplice utilizzo di Jcrop con le coordinate restituite in campi form.

JCROP COME SOSTITUTO DEL TAG MAP

Alla fine anche per la presentazione ho deciso di provare ad utilizzare il plugin.

Questo è il risultato.

Una serie di link presi da una lista con le coordinate passate via metadata.

L’implementazione è  semplice (anche se le coordinate non sono proprio user-frendly).

L’ESEMPIO BASE

Il container:

<div class="jcropmap"></div>

L’immagine:

<img src="img/italia2006.jpg" alt="italia2006" />

La lista di aree:

<ul>
	<li><a class="{coords : [33,111,75,176,42,65]}" href="#">Gattuso</a></li>
    <li><a class="{coords : [93,104,144,180,51,76]}" href="#">Pirlo</a></li>
    <li><a class="{coords : [171,103,224,183,53,80]}" href="#">Zambrotta</a></li>
    <li><a class="{coords : [245,102,318,191,73,89]}" href="#">Camoranesi</a></li>
    <li><a class="{coords : [326,100,397,190,71,90]}" href="#">Cannavaro</a></li>
    <li><a class="{coords : [402,98,456,174,54,76]}" href="#">Perrotta</a></li>
    <li><a class="{coords : [410,14,464,90,54,76]}" href="#">Totti</a></li>
    <li><a class="{coords : [345,7,399,83,54,76]}" href="#">Grosso</a></li>
    <li><a class="{coords : [274,4,328,80,54,76]}" href="#">Toni</a></li>
    <li><a class="{coords : [211,4,265,80,54,76]}" href="#">Barzagli</a></li>
    <li><a class="{coords : [149,2,203,78,54,76]}" href="#">Buffon</a></li>
</ul>

Il JS NELL’HEAD:

jQuery(window).load(function(){
	jQuery(".jcropmap").jcropmap();
});

NB:

non ci sono regole forti per questo plugin per la struttura html. L’ importante è scegliere una classe o un id per il wrapper container e richiamarla nell’head quando si avvia il costruttore. All’interno di questo wrapper ricordarsi solo che i link vengono cercati all’interno di un ul, e l’immagine DEVE avere come classe jcropbox (sovrascrivibile da opzione).

CREARE LE AREE

Visto che non è proprio semplice scrivere le coordinate delle aree, ho creato una demo con una banale gestione della sessione.

Questa demo non è un plugin.

E’ solo uno spunto per crearsi la propria gestione dei link.

Sarà quindi necessario implementare un servizio che ad esempio salvi le informazioni su db.

VISUALIZZARE IL RISULTATO

Una volta inserite le coordinate nella demo precedente, potrete vedere il risultato dei vostri “tag” qui.

EXTRA : SHAPES, OPTIONS, RELEASE

Ho aggiunto anche la possibilità di visualizzare le aree all’interno del “viewport” di Jcrop, e di sovrascrivere le opzioni che vengono passate. Un esempio.

Qui invece mostro come ho agganciato il metodo release dell’oggetto costruito all’interno del plugin (click sul body).

Non è una tecnica pulitissima. Ma nemmeno quella di Jcrop mi sembra elegante.

FEEDBACK

Se ci sarà un certo riscontro a questo post, magari versionerò il plugin, esporrò meglio le opzioni, e magari anche un API pubblica di metodi.

Fino ad allora per maggiori informazioni o chiedete qui postando un commento, oppure guardate il codice sorgente.

Pubblico le mie 3 implementazioni del plugin jQuery Autocomplete di Jörn Zaefferer.

Queste implementazioni servono ad attivare campi form con suggest automatico senza scrivere una sola riga di javascript.

La prima implementazione autoattiva il plugin originale (con supporto ai metadata):

La seconda implementazione aggiunge “magicamente” un campo “hidden” e in fase di invio del “form” spedisce al server anche la chiave associata al valore selezionato nel suggest.

La terza invece crea un suggest “tabellare”. E’ stato necessario modificare lo script.

Per le demo ho usato:

• jQuery 1.3.2
• jQuery Metadata
• jQuery Autocomplete 1.1

HEAD HTML

Includere le librerie e i css necessari.

	<link href="lib/jquery.autocomplete.css" rel="stylesheet" type="text/css" media="screen" />
	<script src="lib/jquery-1.3.2.min.js" type="text/javascript"></script>
    <script src="lib/jquery.metadata.js" type="text/javascript"></script>
    <script src="lib/jquery.autocomplete.js" type="text/javascript"></script>
	<script src="autocomplete.custom.js" type="text/javascript"></script>

DOWNLOAD DEMO

SUGGEST BASE

Per attivare un suggest base è sufficiente

• assegnare al campo input la classe suggest.
• valorizzare l’attributo alt del campo input inserendo un url relativo es: “php/mesi.php”

Lo script php d’esempio che restituisce alle chiamate ajax l’elenco dei valori:

$q = strtolower($_GET["q"]);
if (!$q) return;
$items = array(
	'gennaio',
	'febbraio',
	'marzo',
	'aprile',
	'maggio',
	'giugno',
	'luglio',
	'agosto',
	'settembre',
	'ottobre',
	'novembre',
	'dicembre'
);

foreach ($items as $value) {
    if (strpos(strtolower($value), $q) !== false) {
        echo "$value\n";
    }
}

Chiaramente nelle applicazioni reali i dati non verranno presi da un array ma da un database

ESEMPIO 1

• DEMO

<input type="text" name="suggest1" id="suggest1" class="suggest" alt="php/mesi.php" />

ESEMPIO 2

Grazie all’uso di jQuery metadata le opzioni dell’autocomplete possono essere settate direttamente nell’html (quindi senza scrivere codice javascript).
L’elenco delle opzioni che modificano il comportamento del plugin si trova qui.

• DEMO

<input type="text" name="suggest2" id="suggest2" class="suggest {multiple:true}" alt="php/mesi.php" />

ESEMPIO 3

• DEMO

<input type="text" name="suggest3" id="suggest3" class="suggest {minChars:3, max:3}" alt="php/search.php" />

SUGGEST CHIAVE VALORE

La seconda implementazione di jQuery Autocomplete crea un campo hidden per la chiave legata al valore visualizzato in suggest in modo da poter inviare al server sia la chiave sia il valore in fase di submit.

Per attivare un suggest chiave/valore è sufficiente

• assegnare al campo input la classe suggest_keys.
• valorizzare l’attributo alt del campo input inserendo un url relativo es: “php/keys.php”

Lo script php d’esempio che restituisce alle chiamate ajax l’elenco di chiavi|valori:

$q = strtolower($_GET["q"]);
if (!$q) return;
$items = array(
	"10024" => "Moncalieri",
	"20000" => "Monza",
	"10100"	=> "Torino"
);

foreach ($items as $key=>$value) {
    if (strpos(strtolower($value), $q) !== false) {
        echo "$key|$value\n";
    }
}

ESEMPIO 4

• DEMO

<input type="text" name="suggest4" id="suggest4" class="suggest_keys" alt="php/keys.php" />

Se utilizzate firebug potrete vedere che viene creato un campo nascosto. Es:

<input type="hidden" value="" id="suggest4_hidden" name="suggest4_hidden"/>

ESEMPIO 5

• DEMO

<input type="text" name="entita[campo]" id="entita_campo" class="suggest_keys" alt="php/keys.php" />

Se utilizzate firebug potrete vedere che viene creato un campo nascosto. Es:

<input type="hidden" value="" id="entita_campo_hidden" name="entita[campo_hidden]"/>

SUGGEST TABELLARE

La terza implementazione di jQuery Autocomplete è un po’ più complessa e prevede l’utilizzo di una versione modificata di jquery autocomplete.

Per attivare un suggest tabellare è sufficiente

• Includere nell’head la versione modificata di jQuery Autocomplete
• assegnare al campo input la classe suggest_table.
• personalizzare le intestazioni di colonna nell’attributo class (vedi sotto l’esempio)
• valorizzare l’attributo alt del campo input inserendo un url relativo es: “php/table.php”
• Includere le seguenti istruzioni css personalizzando “le larghezze” che nell’esempio settano le 3 colonne della tabella

.ac_results ul li div.tbl{clear:both;}
.ac_results ul li div.tbl div{float:left;width:30%;overflow-x:hidden;}
.ac_intestazione{position:absolute;left:0px;top:-0px;z-index:1000;background:#000;color:#fff;}

/*PERSONALIZZA*/
.ac_results ul li div.tbl div.fld_1, #int_1{width:150px;}
.ac_results ul li div.tbl div.fld_2, #int_2{width:70px;}
.ac_results ul li div.tbl div.fld_3, #int_3{width:70px;}

Lo script php d’esempio che restituisce alle chiamate ajax l’elenco dei valori della tabella.

$q = strtolower($_GET["q"]);
if (!$q) return;
$items = array(
	"10024" => array(
		"Moncalieri",
		"Torino",
		"Piemonte"
	),
	"20000" => array(
		"Conegliano",
		"Treviso",
		"Veneto"
	),
	"10100"	=> array(
		"Alba",
		"Cuneo",
		"Piemonte"
	)
);

foreach ($items as $key=>$array) {
	$str = join($array,"#");
    if (strpos(strtolower($str), $q) !== false) {
        echo "$key|$str\n";
    }
}

ESEMPIO TABELLARE

• DEMO

<input type="text" id="suggest1" name="suggest1" class="suggest_table {th : ['città', 'provincia', 'regione']}" alt="php/table.php" style="width:300px;" />

AGGIORNAMENTO 13-11-2009:

Ho aggiornato lo ZIP con le demo e gli script di questo post.

Ho aggiornato in particolare

• jQuery Autocomplete “modificato”
• jQuery Autocomplete “custom”

Ho aggiunto questa DEMO per il passaggio delle opzioni autocomplete al plugin base (jquery.autocomplete.mod.js).

Le porzioni di jquery.autocomplete.js modificate sono a questo punto due, entrambe nel metodo/funzione fillList:

var li = $("<li/>").html( options.highlight(formatted, term) ).addClass(i%2 == 0 ? "ac_even" : "ac_odd").appendTo(list)[0];
//PATCH
if(i == 0 &amp;&amp; $(input).is(".suggest_table")){
	$(li).addClass("ac_first");
	var _ie_sucks = typeof document.body.style.maxHeight === "undefined" || //IE6
					(document.all &amp;&amp; !window.opera &amp;&amp; window.XMLHttpRequest); //IE7
	if (_ie_sucks || max == 1) {
		$(li).attr("style", "padding-top:20px");
	}
}
//PATCH
$.data(li, "ac_data", data[i]);

listItems = list.find("li");
if ( options.selectFirst ) {
	//PATCH
	//listItems.slice(0, 1).addClass(CLASSES.ACTIVE);
	listItems.slice(1, 2).addClass(CLASSES.ACTIVE);
	//PATCH
	active = 0;
}

Per questa seconda modifica, ringrazio Mansportivo che nei commenti qui sotto mi ha segnalato l’anomalia.

• il problema
• soluzione “manuale” (responsabilità dello sviluppatore)
• soluzione nel plugin (responsabilità affidata al plugin)

IL PROBLEMA

• DEMO
• SORGENTE

Javascript non intrusivo ha un problema di fondo.
Lavorando sull’evento window.onload, i componenti javascript non intrusivi, NON si attivano nel momento in cui viene fatta un’ iniezione html nel DOM (AHAH).

Qui ho scritto un banale esempio.

Il plugin aggiunge le funzionalità draggable e resizable (jQuery UI) agli elementi HTML selezionati.

Il plugin come “comportamento di default” agisce su tutti gli elementi con classe “box” :

$(document).ready(function(){
	$(".box").myplugin();
});

Quindi nella demo tutti gli elementi con classe “box” saranno draggabili e ridimensionabili.

Il link ADD, nella DEMO, aggiunge elementi box via ajax (AHAH):

$("#add").click(function(){
    $.ajax({
        url     : 'box.html',
        success : function(html){
            $("body").append($(html).myplugin());
        }
    });
});

Questi elementi arrivando da un iniezione HTML non vengono “arricchiti” dal plugin (non sono quindi ridimensionabili ne trascinabili) perchè non sono presenti al window.onload (al document.ready per chi usa jquery).

Questo problema non si avvertirebbe se il componente fosse intrusivo (js cablato nell’html):

<div id="box1"></div>
<script type="text/javascript">
//<![CDATA[
$("#box1").myplugin();
//]]>
</script>

Se io iniettassi il codice qui sopra il box si attiverebbe perchè verrebbe valutato il js (almeno se iniettato via jquery) immediatamente senza eventi onload di mezzo.

Spesso i framework server-side sono intrusivi proprio per essere più flessibili.
Il codice html generato sarà sporco (richfaces ad esempio) ma i componenti saranno sempre “funzionanti” sia al primo caricamento sia a seguito di iniezioni html.

SOLUZIONE MANUALE

• DEMO

La soluzione “manuale” (a carico dello sviluppatore che implementa il comportamento e USA il plugin) è attivare le funzionalità js prima di appendere il nuovo pezzo di html. DEMO

$("#add").click(function(){
    $.ajax({
        url     : 'box.html',
        success : function(html){
            $("body").append($(html).myplugin());
        }
    });
});

Questa è la soluzione che più di frequente utilizzo.

Se invece avessi scritto il plugin ecco come potrei fare (quindi spostando la responsabilità al plugin stesso).

SOLUZIONE AUTOMATICA

• DEMO
• SORGENTE

L’idea è : quello che attivo al document.ready lo attivo anche all’evento ajaxStop (quindi inizializzo il plugin sia al window.onload sia alla chiusura di ogni chiamata ajax).

$(document)
.ready(function(){
    $(".box").myplugin();
})
.ajaxStop(function(){
    $(".box").myplugin();
});

Il problema di questa soluzione è che applicando 2 volte ad un elemento lo stesso plugin si “rischia” spesso di ottenere degli effetti indesiderati (doppi eventi al click, interfaccia che si moltiplica a mo’ di matrioska, ecc…).

La soluzione quindi è realizzare un qualche sistema di singleton all’elemento che si arrichisce.
Nel plugin finale ho scritto un banale if che aggiunge una certa classe (flag) all’elemento arricchito.
Se un evento (ajaxStop) invoca il costruttore del plugin più volte il codice non verrà eseguito.

//singleton
if ($(that).is(".myplugin")) {
   return;
} else {
   $(that).addClass(".myplugin");
}
//plugin code...