Crie um plugin jQuery de Find and Replace

() translation by (you can also view the original English article)

Se você já tiver usado jQuery, há uma boa chance que você também tenha usado pelo menos um dos seus inúmeros plugins. Só pense em algo útil que você gostaria de fazer em jQuery, e eu estou quase certo de que um plugin existe para fazer exatamente isso.

Às vezes, quando não existe um plugin, talvez você precise criar um seu. Não é tão difícil quanto parece. Neste tutorial, eu irei por algumas regras gerais que você precisa seguir ao criar plugins, e mais tarde vamos criar nossos próprio localizar e substituir o plugin.

O básico

Existem algumas coisas que você precisa estar ciente quando desenvolver o plugins. Nesta seção, vou cobrir todos eles, um por um. Considere o trecho de código a seguir:

(function ( $ ) {
    $.fn.functionName = function() {
        return this.addClass("my-class");
    };
}( jQuery ));

Primeiro, você deve ter notado que eu estou usando this em vez de $(this) no nosso plugin. Isso ocorre porque $.fn faz functionName parte do mesmo objeto jQuery como o .addClass() método.

Deixe-me explicar para tornar mais claro. Usar o $.fn sempre retorna um objeto jQuery que contém todos os métodos que você usa no jQuery. Se você já cria seus próprios métodos, farão parte deste objeto também. Uma vez que sua função agora é parte do objeto jQuery, você pode usar this no lugar de $(this).

Em segundo lugar, você deve tentar fazer seu plugin encadeável. Esta é uma das muitas características importantes do jQuery que os desenvolvedores usam o tempo todo. Para fazer um método encadeável, ele deve retornar o objeto original do jQuery. Isto pode ser conseguido, apenas acrescentando o return como fiz no código acima.

Finalmente, você deve proteger o alias $ e certifique-se que usando o seu plugin com outro código JavaScript não resulte em qualquer conflito. Tudo o que você precisa fazer para garantir que isso não aconteça é só enrolar a função em uma expressão de função imediatamente invocada como o código acima.

Criando o Plugin

Com o básico do nosso caminho, podemos focar nossa tarefa principal, ou seja, criar o plugin. Começamos com uma versão primitiva, onde só iremos substituir o texto original com algum texto predefinido. Aqui está o código para fazer isso:

(function($) {
  $.fn.findReplace = function(options) {
    return this.each(function() {
      $(this).html(
        $(this).html().replace(/Lorem Ipsum/g, "Replacement")
      );
    });
  };
}(jQuery));

Eu estou usando regex para substituir todas as ocorrências de Lorem Ipsum com Replacement. Para ser honesto, na sua forma atual, o nosso plugin é totalmente inútil. Os usuários devem, pelo menos, tem a opção de encontrar um pedaço de texto e em seguida, substituí-lo por algum outro texto de sua escolha.

Neste ponto, a capacidade de aceitar várias opções vem em nosso socorro. Nós forneceremos os usuários com três opções: algum texto para encontrar, algum texto para substituir e a capacidade de definir a cor de fundo do texto substituído. Você também pode usar esta oportunidade para definir valores padrão para parâmetros diferentes, caso os usuários consciente ou inconscientemente não definiu o valor. Aqui está o código para fazer isso:

var settings = $.extend({
    // These are the defaults.    
    findText: null,
    replaceText: "",
    backgroundColor: "#FFF"
}, options);

Eu ajustei findText para null. Para replaceText, uma seqüência de caracteres vazia faz mais sentido porque se um usuário não definiu um valor para substituir, talvez ele ou ela só queria que fosse vazio. O valor mais apropriado para backgroundColor seria a cor de fundo da página, que na maioria dos casos é branco. Você também pode colocar algumas verificações no local para notificar os usuários se eles esqueceram-se de fornecer os valores.

Para utilizar estes valores, teremos de mudar nosso código do plugin original também. Nosso código agora vai ficar assim:

return this.each(function() {
  var StringToFind = settings.findText; 
  var regExpression = new RegExp(StringToFind, "g");
  var replacement = "<span style='background:" + settings.backgroundColor + ";'>" + settings.replaceText + "</span>";
  $(this).html(
    $(this).html().replace(regExpression, replacement)
  );
});

O texto que precisa ser encontrado pode ser acessado usando setting.findText. Isso é armazenado em uma variável para uso posterior. Eu estou usando o RegExp para criar um objeto de expressão regular. Isto pode ser usado para substituir dinamicamente expressões regulares.

Usando o modificador global, todas as ocorrências de StringToFind são substituídas. Mando substituindo o texto em um elemento span com um estilo inline. Finalmente, eu atualizo o HTML do elemento que chamou nossa função findReplace.

Esta demonstração mostra nosso plugin em ação.

Fazendo Melhorias

Nosso bom pequeno plugin funciona perfeitamente. Você pode fazer algo ainda mais impressionante com algumas modificações. Já oferecemos a opção de mudar a cor de fundo dos elementos substituídos.

No entanto, se os usuários decidirem mudar o tamanho da fonte, adicionar um preenchimento ou fazer outras mudanças, eles não podem. Também é impraticável fornecer todas essas opções. O que vamos fazer em vez disso é dar aos usuários a capacidade de adicionar uma classe de sua escolha para os elementos substituídos. Desta forma podem fazer alterações nos próprios CSS, e nosso plugin será leve também.

Tudo o que você precisa fazer é alterar a propriedade background color em nossa versão anterior para customClass nos lugares correspondentes.

var settings = $.extend({
  findText: null,
  replaceText: "",
  backgroundColor: "#FFF"
}, options);
// Should Now Be
var settings = $.extend({
  findText: null,
  replaceText: "",
  customClass: ""
}, options);


var replacement = "<span style='background:" + settings.backgroundColor + ";'>" + settings.replaceText + "</span>";
// Should Now Be
var replacement = "<span class='" + settings.customClass + "'>" + settings.replaceText + "</span>";

Alguns usuários de seu plug-in podem estar interessados em chamar uma função de retorno de chamada depois que o plugin tenha feito seu trabalho. Isto é bem fácil. Você só precisa adicionar uma opção de completeCallback para obter a função de retorno de chamada de usuários. Então o código abaixo vai cuidar do resto:

1	if ($.isFunction(settings.completeCallback)) {
2	settings.completeCallback.call(this);
3	}

No trecho de código acima, o método .isFunction verifica se o usuário realmente passou a função antes de executá-lo. Para chamar funções personalizadas, você precisará chamar a função da seguinte maneira:

$("a").findReplace({
  findText: "Lorem Ipsum",
  replaceText: "I was replaced too!",
  customClass: "match-link",
  completeCallback: function() {
    $('.notification').text('Executed the plugin on all links').fadeOut(5000);
  }
});

Aqui está um screenshot do plugin em ação:

Estou postando o código completo do nosso plugin para certificar-se de que não há qualquer confusão:

(function($) {
  $.fn.findReplace = function(options) {

    var settings = $.extend({
      findText: null,
      replaceText: "",
      customClass: "",
      completeCallback: null
    }, options);
    return this.each(function() {
      var StringToFind = settings.findText;
      var regExpression = new RegExp(StringToFind, "g");
      var replacement = "<span class='" + settings.customClass + "'>" + settings.replaceText + "</span>";
      $(this).html(
        $(this).html().replace(regExpression, replacement)
      );

      if ($.isFunction(settings.completeCallback)) {
        settings.completeCallback.call(this);
      }
    });
  };
}(jQuery));

Nossa demo final.

Considerações finais

Criar um plugin em jQuery não custa nada. Você só tem que seguir algumas regras básicas e pronto.

Se você está interessado em alguns outros plugins que temos disponíveis, bem como o que eles podem fazer por você em qualquer um dos seus projetos existentes, então por favor, confira o trabalho em jQuery que temos no mercado.

Uma coisa que eu recomendo é fazer com que o plugin seja tão flexível quanto possível e manter seu tamanho pequeno. Ninguém vai usar um plugin de 15k que só encontra e substitui o texto.

Finalmente, espero que você goste deste tutorial e se você tiver qualquer dúvida sobre o tutorial, me avise nos comentários.