Crea un plugin de búsqueda y reemplazo en jQuery

Spanish (Español) translation by Victor Manuel (you can also view the original English article)

Si alguna vez has utilizado jQuery, hay una muy buena probabilidad de que también hayas utilizado al menos uno de sus innumerables complementos. Piensa en algo útil que te gustaría hacer en jQuery, y estoy casi seguro de que existe un plugin para hacer exactamente eso.

A veces, cuando un plugin no existe, es posible que tengas que crear uno tú mismo. No es tan difícil como parece. En este tutorial, repasaré algunas reglas generales que hay que seguir al crear plugins, y más tarde crearemos nuestro propio plugin de búsqueda y de reemplazo.

Las bases

Hay algunas cosas que debes tener en cuenta al desarrollar complementos. En esta sección, los trataré uno por uno. Considera el siguiente fragmento de código:

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

En primer lugar, es posible que hayas notado que estoy usando thisen lugar de $(this) en nuestro plugin. Esto se debe a que $.fn hace que functionName forme parte del mismo objeto jQuery que .addClass() método.

Me explico para que sea más claro. El uso de $.fn siempre devuelve un objeto jQuery que contiene todos los métodos que se utilizan en jQuery. Si alguna vez creas tus propios métodos, también formarán parte de este objeto. Como su función es ahora parte del objeto jQuery, puede utilizar thisen lugar de $(this).

En segundo lugar, debes tratar que tu plugin sea encadenable. Esta es una de las muchas características importantes de jQuery que los desarrolladores utilizan todo el tiempo. Para que un método sea encadenable, debes devolver el objeto jQuery original. Esto se puede lograr simplemente anexando return como lo hice en el código anterior.

Por último, debes proteger el alias $ y asegurarte de que el uso de tu plugin con otro código JavaScript no provoque ningún conflicto. Todo lo que necesitas hacer para asegurarte de que esto no sucede es simplemente envolver la función en una expresión de función invocada inmediatamente al igual que el código anterior.

Crea el plugin

Una vez eliminados los aspectos básicos, podemos centrarnos en nuestra tarea principal, es decir, crear el plugin. Comenzamos con una versión primitiva, en la que sólo sustituiremos el texto original por un texto predefinido. Aquí está el código para hacerlo:

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

Estoy usando regex para reemplazar todas las ocurrencias de Lorem Ipsum con Replacement. Para ser honesto, en su forma actual, nuestro plugin es totalmente inútil. Los usuarios deben al menos tener la opción de encontrar un fragmento de texto y luego reemplazarlo con algún otro texto de su elección.

En este punto, la capacidad de aceptar varias opciones viene a nuestro rescate. Proporcionaremos a los usuarios tres opciones: algunos texto para buscar, algunos textos para reemplazar y la capacidad de establecer el color de fondo del texto reemplazado. También puedes usar esta oportunidad para establecer valores predeterminados para varios parámetros, en caso de que los usuarios, a sabiendas o sin saberlo, no establecieron el valor ellos mismos. Aquí está el código para hacerlo:

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

He establecido findText en null. Para replaceText, una cadena vacía tiene más sentido porque si un usuario no estableció un valor de reemplazo, tal vez él o ella simplemente quería que estuviera vacío. El valor más adecuado para backgroundColor sería el color de fondo de la página web, que en la mayoría de los casos es blanco. También puedes realizar algunas comprobaciones para notificar a los usuarios si han olvidado proporcionar los valores.

Para usar estos valores, también tendremos que cambiar nuestro código original del complemento. Nuestro código de plugin ahora debería ser:

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)
  );
});

Se puede acceder al texto que se necesita encontrar mediante setting.findText. Esto se almacena en una variable para su uso posterior. Estoy usando el constructor RegExp para crear un objeto de expresión regular. Esto se puede utilizar para reemplazar dinámicamente las expresiones regulares.

El uso del modificador global garantiza que se reemplacen todas las apariciones de StringToFind. He incluido el texto de reemplazo en un elemento span con estilo en línea. Finalmente, actualizo el HTML del elemento que llamó a nuestra función findReplace.

Esta demostración muestra nuestro plugin en acción.

Realiza mejoras

Nuestro pequeño plugin agradable funciona perfectamente. Puedes hacerlo aún más impresionante con algunas modificaciones. Ya hemos proporcionado la opción de cambiar el color de fondo de los elementos reemplazados.

Sin embargo, si los usuarios deciden cambiar el tamaño del tipo de letra, agregar algo de relleno o realizar algunos otros cambios, no pueden. También es poco práctico proporcionar todas estas opciones. Lo que vamos a hacer en su lugar es dar a los usuarios la capacidad de agregar una clase de su elección a los elementos reemplazados. De esta manera pueden hacer cambios en el CSS ellos mismos, y nuestro plugin también será ligero.

Todo lo que tienes que hacer es cambiar la opción backgroundColor en nuestra versión anterior a customClass en los lugares correspondientes.

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>";

Algunos usuarios de tu plugin podrían estar interesados en llamar a una función de devolución de llamada después de que el plugin haya hecho su trabajo. Esto es bastante fácil de lograr. Solo necesitas agregar una opción completeCallback para obtener la función de devolución de llamada de los usuarios. A continuación, el siguiente código se encargará del resto:

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

En el fragmento del código anterior, el método .isFunction comprueba si el usuario ha pasado realmente una función antes de ejecutarla. Para llamar a funciones personalizadas, debes llamar a la función de la siguiente manera:

$("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́ hay una captura de pantalla del plugin en acción:

Estoy publicando el código completo de nuestro plugin para asegurarme de que no haya ninguna confusión:

(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));

Nuestra demostración final.

Reflexiones finales

Crear un plugin en jQuery no es nada difícil. Sólo hay que seguir unas cuantas reglas básicas y ya está.

Si estás interesado en algunos otros complementos que tenemos disponibles, así como lo que pueden hacer por ti en cualquiera de sus proyectos existentes, consulta el trabajo de jQuery que tenemos en el mercado.

Una cosa que recomendaría es hacer que el plugin sea lo más flexible posible y mantener su tamaño lo más pequeño posible. Nadie va a usar un plugin de 15k que solo encuentra y reemplaza texto.

Por último, espero que les haya gustado este tutorial, y si tienes alguna duda respecto al tutorial, haganmelo saber en los comentarios.