Front End

29 jun, 2011

Criando um plugin para jQuery

Publicidade

Texto original disponível em  http://devheart.org/articles/tutorial-creating-a-jquery-plugin/

?

Aprenda
como criar um plug in para jQuery do zero – o básico, as opções, a compatibilidade e
exemplos.

O básico

Um plugin é escrito como um
método ou uma função.


Criando uma
Função jQuery

Sintaxe

A função tem que retornar this.each(..) para manter a capacidade de
“acorrentamento” – de modo que a função possa ser usada com um ou com vários objetos
jQuery.

jQuery.fn.myFunction = function(){
return this.each(function(){
// element-specific code here
});
};

Exemplo

jQuery.fn.makeTextRed = function(){
return this.each(function(){
$(this).css('color', 'red');
});
};

// Example usage
$('#my-div').makeTextRed(); // make text in "my-div" red
$('p').makeTextRed(); // make all paragraphs red

Criando um Método jQuery

Sintaxe

jQuery.myMethod = function(){
// code here
};

Exemplo

jQuery.sayHelloWorld = function(){
alert('Hello World');
};

// Example usage
$.sayHelloWorld(); // alerts "Hello World"

Opções

Deixe seu plugin o
mais flexível e amigável possível para o usuário, usando as opções. O método $.extend() pega dois ou mais
objetos como argumentos e une seus conteúdos dentro do primeiro objeto.

Exemplo

Uma função que configura a cor do texto (vermelho, como padrão).

jQuery.fn.makeTextColored = function(settings){
var config = {
'color': 'red'
};
if (settings){$.extend(config, settings);}

return this.each(function(){
$(this).css('color', config.color);
});
};

Agora podemos escolher usar essa função passando as configurações do parâmetro ou não.

$('#my-div').makeTextColored(); // make text red (default)
$('#my-div').makeTextColored('blue'); // make text blue

Compatibilidade

Como a variável $ pode ser usada por
outros plugins, use uma técnica “disfarçada” para deixar seu plugin compatível
futuramente.

(function($){
$.fn.myFunction = function() {
return this.each(function() {
// element-specific code here
});
};
})(jQuery);

Nós passamos o jQuery para a
função e agora podemos usar qualquer disfarce para o jQuery que quisermos.
Então, em vez do $, você poderia usar qualquer outro nome válido de variáveis
JavaScript.

A checklist
do plugin jQuery

Esta é uma lista de pontos
importantes para se lembrar quando for desenvolver um plugin jQuery (do
jQuery.com
).

  • Nomeie seu
    arquivo jquery.[insira o nome do plugin].js, eg. jquery.debug.js.
  • Todos os novos
    métodos são anexados ao objeto jQuery.fn object, e todas as funções ao
    objeto jQuery.
  • Para métodos
    internos, this é uma referência ao
    objeto jQuery atual.
  • Quaisquer
    métodos ou funções que você anexe devem ter um ponto e vírgula (;) no
    final – caso contrário, o código irá quebrar quando comprimido.
  • O seu método
    deve retornar o objeto jQuery, a não ser que tenha sido explicitamente
    notado o contrário.
  • Use this.each para iterar sobre o conjunto atual de
    elementos correspondentes.
  • Sempre anexe o
    plugin ao jQuery em vez de $, para que os
    usuários possam usar um disfarce customizado via noConflict().

Templates do plugin jQuery

Estes são dois bons templates
de código para começar a desenvolver um plugin jQuery.

Template de Função

(function($){
$.fn.myPlugin = function(settings){
var config = {
'foo': 'bar'
};
if (settings){$.extend(config, settings);}

return this.each(function(){
// element-specific code here
});
};
})(jQuery);

Template de Método

(function($){
$.myPlugin = function(settings){
var config = {
'foo': 'bar'
};
if (settings){$.extend(config, settings);}

// code here

return this;
};
})(jQuery);

Exemplo: Plugin
Slideshow jQuery

Decidi usar exemplos bem
simples até agora para que você pudesse se familiarizar. O exemplo a seguir é
um pouco mais complexo e pode te ajudar a encontrar sua inspiração.

Ele usa a função setInterval() juntamente com os efeitos fadeOut() e fadeIn() do jQuery para gerar o ciclo de quaisquer
imagens dentro de um elemento HTML.

Configuração

HTML

<div id="slideshow">
<img src="img/sample-image-1.png" alt="" />
<img src="img/sample-image-2.png" alt="" />
<img src="img/sample-image-3.png" alt="" />
<img src="img/sample-image-4.png" alt="" />
</div>

CSS

#slideshow img {
display: none;
position: absolute;
}

JavaScript

(function($){
$.simpleSlideShow = function(selector, settings){
// settings
var config = {
'delay': 2000,
'fadeSpeed': 500
};
if ( settings ){$.extend(config, settings);}

// variables
var obj = $(selector);
var img = obj.children('img');
var count = img.length;
var i = 0;

// show first image
img.eq(0).show();

// run slideshow
setInterval(function(){
img.eq(i).fadeOut(config.fadeSpeed);
i = ( i+1 == count ) ? 0 : i+1;
img.eq(i).fadeIn(config.fadeSpeed);
}, config.delay);

return this;
};
})(jQuery);

Uso

Para ativar o slideshow
na div #slideshow, nós simplesmente a chamamos usando o código JavaScript a seguir:

<script type="text/javascript">
$.simpleSlideShow('#slideshow');
</script>

Como permitimos que a configuração mudasse o comportamento do
slideshow, poderíamos deixar 5 segundos
entre as imagens e configurar a duração do “fade” para 200 ms usando:

<script type="text/javascript">
$.simpleSlideShow('#slideshow', {'delay':5000, 'fadeSpeed': 200});
</script>

Veja o Examplo Faça o download do Exemplo

Não é mais difícil que isso!
Boa sorte na criação de seu próprio plugin jQuery!