Il plugin che si vedrà è anche presente come funzionalità base nel repository di jQuery, il suo nome è: jTruncate che potete trovare sul sito dell'autore ossia qui oppure sul sito di jQuery Plugins dova ha il suo spazio (se avete necessità di utilizzare il truncate su lingue asiatiche c'è un plugin appositamente modificato: jTruncSubstr).
L'articolo originale in lingua inglese lo trovate sul sito di Jeremy Martin ma di seguito vi inserisco una traduzione libera con tutto il codice, esempi funzionanti e funzioni utilizzate. Buona lettura!
Titolo: Costruire il tuo primo plugin jQuery (Jeremy Martin)
L'architettura di jquery è così ben pensata e friendly che è possibile creare il proprio plugin molto facilmente. Prima di tutto è indispensabile avere preso confindeza col codice jQuery, sapere quindi bene la sintassi, le potenzialità e soprattutto cosa si vuole ottenere dal plugin (anche solo questo punto non è poi così semplice come sembra, ndt).
Questo tutorial passerà attraverso tutti i punti della creazione del tuo primo plugin, come esempio viene creato un plugin in grado di visualizzare il consiglio o messaggio del giorno da poter inserire nella propria pagina principale. Questo plugin dovrà troncare il messaggio a una specifica lunghezza se necessario e tramite un link espandere l'intero contenuto. Eccovi un esempio funzionante:
Da notare che se Javascript risulta disabilitato (o non supportato) il contenuto sarà visualizzato interamente (quindi pienamente accessibile, ndt).
Ok iniziamo..
step 1
il primo passo è implementare in jQuery la funzione che vogliamo aggiungere. Nel nostro caso, la funzionalità di troncare "truncate". Così prima di tutto bisogna creare un file jquery.truncate.js dopodichè è possibile aggiungere il codice per estendere questa funzionalità, ossia:
Ora, se hai programmato con altri frameworks o hai una certa esperienza con jQuery sicuramente saprai che non sempre è possibile usare il $ come alias, perchè potrebbe risultare in conflitto con altri frameworks. Questo è parzialmente vero, per non incappare in questo problema è necessario ritoccare la definizione precedente permettendo di utilizzare un differente alias.
In pratica è sufficiente:
step 2
prima di continuare nella scrittura del nostro plugin è consigliato creare una pagina di prova per provare il plugin di volta in volta. Quindi, creiamo una pagina whatever_you_want.html e inseriamo il codice seguente come esempio:
Guardando il codice è possibile notare che sono presenti sia la libreria jQuery sia quella da noi creata (ossia jquery.truncate.js) entrambe sono presenti in una cartella js. Nello script successivo abbiamo invocato il metodo che abbiamo definito nella classe, anche se di fatto non abbiamo ancora inserito del codice nella funzione truncate.
step 3
Il prossimo passo è inserire un meccanismo per personalizzare il plugin e il suo comportamento, anche perché altrimenti non avrebbe senso creare un plugin. L'ideale sarebbe creare il plugin il più flessibile possibile, dobbiamo anche prevedere dei defaults così che l'utente non sia costretto a inserire ogni volta una lunga lista di parametri. Per fare questo possiamo usare il metodo extend di jQuery e applicandolo al nostro plugin trasformiamo il contenuto del file jquery.truncate.js in:
I default inseriti sono sufficienti per visualizzare l'esempio, di conseguenza per ora non modificheremo nessuno di questi parametri ma lo faremo alla fine per dimostrarne la funzionalità.
step 4
Prendendosi cura e il tempo necessario epr eseguire tutti i passi precedenti è possibile iniziare a scrivere il codice funzionale, il vero è proprio core del nostr o plugin. Guardando l'ultimo blocco di codice si vede che viene restituito this.each( ... )
Questa linea eseguirà una funzione per ogni elemento dell'array jQuery passato. Così, se per esempio noi chiamiamo $('p').truncate() il codice che scriveremo verrà eseguito su tutti i tag p presenti!!
Dal momento che ipotizzo una certa conoscenza di jQuery, non vi mostrerò nel dettaglio come vengono gestite attualmente le chiamate ai metodi e alle funzioni. Se qualcosa nel codice non è chiaro bisognerebbe far riferimento alla documentazione. Per completare il plugin viene implementato proprio la linea this.each( ... ) aggiungendoci il codice necessario per far funzionare il nostro plugin di esempio:
Ti accorgerai che ovunque ho avuto la necessità di selezionare un elemento all'interno del plugin, ho sempre usato obj come contesto (per esempio moreLink = $('.truncate_more_link', obj)). Questo è necessario per limitare le selezioni nell'attuale elemento troncato, senza avresti dei risultati imprevedibili.
Ecco, questo è il vostro primo plugin! Anche se, non abbiamo completamente finito dal momento che vi avevo promesso di mostrarvi come modificare le opzioni predefinite.
Nell'esempio successivo - infatti - ogni opzione è stata sovrascritta, anche se era comunque possibile modificare solo una o più opzioni a seconda delle necessità.
E' sufficiente sostituire lo script precedente nella pagina di test ottenendo quindi:
Questo codice produrrà un risultato leggermente diverso dal primo mostrato, eccovi l'esempio funzionante:
Questo è quanto, complimenti il vostro primo plugin è pronto per essere utilizzato!
Collegamenti esterni: jTruncate Plugin (jeremymartin.name) | jTruncate Plugin (jQuery.com) | jTruncSubstr Plugin (jQuery.com) | Tutorial originale (jeremymartin.name, in inglese) | jQuery
Titolo: Costruire il tuo primo plugin jQuery (Jeremy Martin)
L'architettura di jquery è così ben pensata e friendly che è possibile creare il proprio plugin molto facilmente. Prima di tutto è indispensabile avere preso confindeza col codice jQuery, sapere quindi bene la sintassi, le potenzialità e soprattutto cosa si vuole ottenere dal plugin (anche solo questo punto non è poi così semplice come sembra, ndt).
Questo tutorial passerà attraverso tutti i punti della creazione del tuo primo plugin, come esempio viene creato un plugin in grado di visualizzare il consiglio o messaggio del giorno da poter inserire nella propria pagina principale. Questo plugin dovrà troncare il messaggio a una specifica lunghezza se necessario e tramite un link espandere l'intero contenuto. Eccovi un esempio funzionante:
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Etiam fringilla, purus a ultrices blandit,
odio ante scelerisque neque, vitae imperdiet odio velit ac nisl. Sed tortor metus, placerat condimentum,
feugiat in, feugiat adipiscing, mi. Donec pulvinar sem vitae leo. Vestibulum eget lectus et ligula hendrerit
pharetra. Sed porta justo ac nisl. Aliquam nisi erat, pellentesque sed, sagittis eu, fringilla sit amet,
dolor. Nam ac mi. Pellentesque pede purus, mattis aliquet, semper nec, cursus a, orci. Duis bibendum nibh
ac massa. Integer eu tortor. Aenean convallis quam at nunc. Nunc mollis tincidunt nisi. Suspendisse mauris
odio, iaculis ut, feugiat vitae, ultrices in, tortor. Quisque at elit. In hac habitasse platea dictumst.
odio ante scelerisque neque, vitae imperdiet odio velit ac nisl. Sed tortor metus, placerat condimentum,
feugiat in, feugiat adipiscing, mi. Donec pulvinar sem vitae leo. Vestibulum eget lectus et ligula hendrerit
pharetra. Sed porta justo ac nisl. Aliquam nisi erat, pellentesque sed, sagittis eu, fringilla sit amet,
dolor. Nam ac mi. Pellentesque pede purus, mattis aliquet, semper nec, cursus a, orci. Duis bibendum nibh
ac massa. Integer eu tortor. Aenean convallis quam at nunc. Nunc mollis tincidunt nisi. Suspendisse mauris
odio, iaculis ut, feugiat vitae, ultrices in, tortor. Quisque at elit. In hac habitasse platea dictumst.
Da notare che se Javascript risulta disabilitato (o non supportato) il contenuto sarà visualizzato interamente (quindi pienamente accessibile, ndt).
Ok iniziamo..
step 1
il primo passo è implementare in jQuery la funzione che vogliamo aggiungere. Nel nostro caso, la funzionalità di troncare "truncate". Così prima di tutto bisogna creare un file jquery.truncate.js dopodichè è possibile aggiungere il codice per estendere questa funzionalità, ossia:
$.fn.truncate = function(options) {
return this.each(function() {
});
};
Ora, se hai programmato con altri frameworks o hai una certa esperienza con jQuery sicuramente saprai che non sempre è possibile usare il $ come alias, perchè potrebbe risultare in conflitto con altri frameworks. Questo è parzialmente vero, per non incappare in questo problema è necessario ritoccare la definizione precedente permettendo di utilizzare un differente alias.
In pratica è sufficiente:
(function($){
$.fn.truncate = function() {
return this.each(function() {
});
};
})(jQuery);
step 2
prima di continuare nella scrittura del nostro plugin è consigliato creare una pagina di prova per provare il plugin di volta in volta. Quindi, creiamo una pagina whatever_you_want.html e inseriamo il codice seguente come esempio:
<html>
<head>
<title>Truncation Plugin Test</title>
<script src="js/jquery.js" type="text/javascript"></script>
<script src="js/jquery.truncate.js" type="text/javascript"></script>
<script type="text/javascript">
$().ready(function() {
$('.tip').truncate();
});
</script>
</head>
<body>
<div class="tip" style="width:200px;background-color:#ccc;padding:10px;">
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Etiam fringilla, purus a ultrices blandit,
odio ante scelerisque neque, vitae imperdiet odio velit ac nisl. Sed tortor metus, placerat condimentum,
feugiat in, feugiat adipiscing, mi. Donec pulvinar sem vitae leo. Vestibulum eget lectus et ligula hendrerit
pharetra. Sed porta justo ac nisl. Aliquam nisi erat, pellentesque sed, sagittis eu, fringilla sit amet,
dolor. Nam ac mi. Pellentesque pede purus, mattis aliquet, semper nec, cursus a, orci. Duis bibendum nibh
ac massa. Integer eu tortor. Aenean convallis quam at nunc. Nunc mollis tincidunt nisi. Suspendisse mauris
odio, iaculis ut, feugiat vitae, ultrices in, tortor. Quisque at elit. In hac habitasse platea dictumst.
</div>
</body>
</html>
Guardando il codice è possibile notare che sono presenti sia la libreria jQuery sia quella da noi creata (ossia jquery.truncate.js) entrambe sono presenti in una cartella js. Nello script successivo abbiamo invocato il metodo che abbiamo definito nella classe, anche se di fatto non abbiamo ancora inserito del codice nella funzione truncate.
step 3
Il prossimo passo è inserire un meccanismo per personalizzare il plugin e il suo comportamento, anche perché altrimenti non avrebbe senso creare un plugin. L'ideale sarebbe creare il plugin il più flessibile possibile, dobbiamo anche prevedere dei defaults così che l'utente non sia costretto a inserire ogni volta una lunga lista di parametri. Per fare questo possiamo usare il metodo extend di jQuery e applicandolo al nostro plugin trasformiamo il contenuto del file jquery.truncate.js in:
(function($){
$.fn.truncate = function(options) {
var defaults = {
length: 300,
minTrail: 20,
moreText: "more",
lessText: "less",
ellipsisText: "..."
};
var options = $.extend(defaults, options);
return this.each(function() {
});
};
})(jQuery);
I default inseriti sono sufficienti per visualizzare l'esempio, di conseguenza per ora non modificheremo nessuno di questi parametri ma lo faremo alla fine per dimostrarne la funzionalità.
step 4
Prendendosi cura e il tempo necessario epr eseguire tutti i passi precedenti è possibile iniziare a scrivere il codice funzionale, il vero è proprio core del nostr o plugin. Guardando l'ultimo blocco di codice si vede che viene restituito this.each( ... )
Questa linea eseguirà una funzione per ogni elemento dell'array jQuery passato. Così, se per esempio noi chiamiamo $('p').truncate() il codice che scriveremo verrà eseguito su tutti i tag p presenti!!
Dal momento che ipotizzo una certa conoscenza di jQuery, non vi mostrerò nel dettaglio come vengono gestite attualmente le chiamate ai metodi e alle funzioni. Se qualcosa nel codice non è chiaro bisognerebbe far riferimento alla documentazione. Per completare il plugin viene implementato proprio la linea this.each( ... ) aggiungendoci il codice necessario per far funzionare il nostro plugin di esempio:
(function($){
$.fn.truncate = function(options) {
var defaults = {
length: 300,
minTrail: 20,
moreText: "more",
lessText: "less",
ellipsisText: "..."
};
var options = $.extend(defaults, options);
return this.each(function() {
obj = $(this);
var body = obj.html();
if(body.length > options.length + options.minTrail) {
var splitLocation = body.indexOf(' ', options.length);
if(splitLocation != -1) {
// truncate tip
var splitLocation = body.indexOf(' ', options.length);
var str1 = body.substring(0, splitLocation);
var str2 = body.substring(splitLocation, body.length - 1);
obj.html(str1 + '<span class="truncate_ellipsis">' + options.ellipsisText +
'</span>' + '<span class="truncate_more">' + str2 + '</span>');
obj.find('.truncate_more').css("display", "none");
// insert more link
obj.append(
'<div class="clearboth">' +
'<a href="#" class="truncate_more_link">' + options.moreText + '</a>' +
'</div>'
);
// set onclick event for more/less link
var moreLink = $('.truncate_more_link', obj);
var moreContent = $('.truncate_more', obj);
var ellipsis = $('.truncate_ellipsis', obj);
moreLink.click(function() {
if(moreLink.text() == options.moreText) {
moreContent.show('normal');
moreLink.text(options.lessText);
ellipsis.css("display", "none");
} else {
moreContent.hide('normal');
moreLink.text(options.moreText);
ellipsis.css("display", "inline");
}
return false;
});
}
} // end if
});
};
})(jQuery);
Ti accorgerai che ovunque ho avuto la necessità di selezionare un elemento all'interno del plugin, ho sempre usato obj come contesto (per esempio moreLink = $('.truncate_more_link', obj)). Questo è necessario per limitare le selezioni nell'attuale elemento troncato, senza avresti dei risultati imprevedibili.
Ecco, questo è il vostro primo plugin! Anche se, non abbiamo completamente finito dal momento che vi avevo promesso di mostrarvi come modificare le opzioni predefinite.
Nell'esempio successivo - infatti - ogni opzione è stata sovrascritta, anche se era comunque possibile modificare solo una o più opzioni a seconda delle necessità.
$().ready(function() {
$('.tip').truncate( {
length: 120,
minTrail: 10,
moreText: 'show more',
lessText: 'show less',
ellipsisText: " [there's more...]"
});
});
E' sufficiente sostituire lo script precedente nella pagina di test ottenendo quindi:
<html>
<head>
<title>Truncation Plugin Test</title>
<script src="js/jquery.js" type="text/javascript"></script>
<script src="js/jquery.truncate.js" type="text/javascript"></script>
<script type="text/javascript">
$().ready(function() {
$('.tip').truncate( {
length: 120,
minTrail: 10,
moreText: 'show more',
lessText: 'show less',
ellipsisText: " [there's more...]"
});
});
</script>
</head>
<body>
<div class="tip" style="width:200px;background-color:#ccc;padding:10px;">
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Etiam fringilla, purus a ultrices blandit,
odio ante scelerisque neque, vitae imperdiet odio velit ac nisl. Sed tortor metus, placerat condimentum,
feugiat in, feugiat adipiscing, mi. Donec pulvinar sem vitae leo. Vestibulum eget lectus et ligula hendrerit
pharetra. Sed porta justo ac nisl. Aliquam nisi erat, pellentesque sed, sagittis eu, fringilla sit amet,
dolor. Nam ac mi. Pellentesque pede purus, mattis aliquet, semper nec, cursus a, orci. Duis bibendum nibh
ac massa. Integer eu tortor. Aenean convallis quam at nunc. Nunc mollis tincidunt nisi. Suspendisse mauris
odio, iaculis ut, feugiat vitae, ultrices in, tortor. Quisque at elit. In hac habitasse platea dictumst.
</div>
</body>
</html>
Questo codice produrrà un risultato leggermente diverso dal primo mostrato, eccovi l'esempio funzionante:
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Etiam fringilla, purus a ultrices blandit,
odio ante scelerisque neque, vitae imperdiet odio velit ac nisl. Sed tortor metus, placerat condimentum,
feugiat in, feugiat adipiscing, mi. Donec pulvinar sem vitae leo. Vestibulum eget lectus et ligula hendrerit
pharetra. Sed porta justo ac nisl. Aliquam nisi erat, pellentesque sed, sagittis eu, fringilla sit amet,
dolor. Nam ac mi. Pellentesque pede purus, mattis aliquet, semper nec, cursus a, orci. Duis bibendum nibh
ac massa. Integer eu tortor. Aenean convallis quam at nunc. Nunc mollis tincidunt nisi. Suspendisse mauris
odio, iaculis ut, feugiat vitae, ultrices in, tortor. Quisque at elit. In hac habitasse platea dictumst.
odio ante scelerisque neque, vitae imperdiet odio velit ac nisl. Sed tortor metus, placerat condimentum,
feugiat in, feugiat adipiscing, mi. Donec pulvinar sem vitae leo. Vestibulum eget lectus et ligula hendrerit
pharetra. Sed porta justo ac nisl. Aliquam nisi erat, pellentesque sed, sagittis eu, fringilla sit amet,
dolor. Nam ac mi. Pellentesque pede purus, mattis aliquet, semper nec, cursus a, orci. Duis bibendum nibh
ac massa. Integer eu tortor. Aenean convallis quam at nunc. Nunc mollis tincidunt nisi. Suspendisse mauris
odio, iaculis ut, feugiat vitae, ultrices in, tortor. Quisque at elit. In hac habitasse platea dictumst.
Questo è quanto, complimenti il vostro primo plugin è pronto per essere utilizzato!
Collegamenti esterni: jTruncate Plugin (jeremymartin.name) | jTruncate Plugin (jQuery.com) | jTruncSubstr Plugin (jQuery.com) | Tutorial originale (jeremymartin.name, in inglese) | jQuery
