lunes, 7 de enero de 2013

JavaScript/NodeJS URL parser: Analizador de URL - Actualizado 17/01/13

Bien es sabido lo tedioso que puede resultar lidiar con las direcciones URL, especialmente en JavaScript, que no posee ninguna función de ayuda robusta para manipularlas, cosa que si sucede en algunas de sus derivadas como NodeJS con su módulo url, aunque en este caso, la solución que traigo pueda ser más potente que la que ofrece NodeJS.

Las distintas alternativas disponibles para JavaScript no me han parecido suficientemente potentes y ello me llevó a desarrollar este analizador de URL, o también conocido como URL parser.

Cuidado al detalle, con numerosas funcionalidades, siguiendo al dedillo la normativa RFC3986 que dicta la sintaxis general de los identificadores uniformes de recursos (URI) y con muchas posibilidades más: JavaScript/NodeJS URL.

Actualizado: desde la versión inicial, hace poco más de una semana, se han corregido varios fallos, añadido nuevas funcionalidades y optimizado el código. También se ha añadido una ligera documentación en español sobre los métodos de la instancia en esta misma entrada. Para más información sobre los cambios, visite la sección changelog de la documentación.

¿Qué es JavaScript/NodeJS URL?

Es una clase escrita en JavaScript que permite analizar y manipular muy fácilmente una URL. Además, tiene soporte para trabajar sobre NodeJS (kurl), por lo que se convierte en una buena herramienta de trabajo.

JavaScript/NodeJS URL se caracteriza por su manera de analizar las direcciones URL, ya que su misión no es validar la misma como una única entrada entera, sino que primero divine la URL en atributos para luego ir validando y normalizando cada uno de ellos. De esta manera podemos mantener la integridad de la URL a pesar de que haya un atributo erróneo, y así comprobar más tarde si dicho atributo se encuentra vacío o no.

La clase URL cuenta con una suite de herramientas que nos permitirán operar con la dirección a nuestro antojo y con una característica a destacar, llamada localización, lo que nos permitirá formar direcciones completas a partir de una incompleta.

Esto sucede por ejemplo con las carpetas relativas, si un enlace tiene como dirección sublevel.html (nótese que no empieza con una barra) y la dirección sobre la que se encuentra el navegador es http://localhost/level/ (nótese la última barra), la dirección resultante será http://localhost/level/sublevel.html.

Lo mismo sucede con direcciones que comienzan con doble barra (//localhost), que que adoptarán el protocolo actual de la página o con las direcciones que comienzan con signo interrogación o almohadilla.

¿Cómo se utiliza?

Los métodos disponibles se encuentran documentados en el propio repositorio: https://github.com/yeikos/js.url. También hay a vuestra disposición unos ejemplos y una serie de pruebas unitarias, las cuales recomiendo echar un ojo, que os permitirán entender cada uno de los métodos disponibles. Aún así haré un breve resumen sobre su utilización.

La función URL puede recibir dos parámetros: dirección y localización. La primera es simplemente la dirección URL que queremos manejar, y el segundo parámetro es el que se comentó anteriormente. Ambos parámetros pueden ser introducidos en forma de cadena de texto o en forma de objeto de atributos (seguir leyendo).

Las diferentes partes de la dirección URL son clasificadas en atributos, cuyos nombres coinciden en parte con los del objeto Location: protocol, auth, host, hostname, port, pathname, search, hash.

Estos atributos pueden ser manipulados mediante el método attr, cuyo comportamiento es similar al de jQuery. Ademas, durante el establecimiento del valor de un atributo, éste pasará por un proceso de validación y normalización basado en el estándar RFC3986, y en caso de incumplimiento el valor guardado pasará a ser una cadena vacía. Cada atributo recibe su normalización especial y esta se realiza en segundo plano.

Finalmente la reconstrucción de la URL viene dada con el método href, que concatenará los atributos adecuadamente para dar como resultado la dirección URL en forma de cadena de texto.

URL('//www.yeikos.com').attr('pathanme', '/2013/01/javascript-nodejs-url-parser.html').attr({ protocol: 'http' }).href();
Además también provee una serie de métodos para una manipulación más rápida y exhaustiva de la dirección URL, y de los que se habla a continuación.

Métodos

A continuación se detallan los métodos disponibles de la instancia, partiendo de que url es una instancia de URL ya creada.

url.location

Es una instancia URL añadida por el constructor y cuyos atributos serán usados internamente para calcular la dirección en base la la localización.

retorna la instancia de la localización.

url.href()

Construye una dirección URL en base a los atributos establecidos.

retorna una dirección URL como cadena de texto.

url.href(url)

- url: cadena de texto, objeto de atributos o elemento DOM.

Establece una nueva dirección reemplazando todos los atributos.

retorna la instancia.

url.attr()

Obtiene todos los atributos.

retorna objeto de atributos

url.attr(name)

- name: nombre del atributo (cadena de texto)

Obtiene el valor del atributo.

retorna el valor del atributo como cadena de texto.

url.attr(name, value)

- name: nombre de atributo.
- value: valor del atributo.

Establece un nuevo valor al atributo.

retorna la instancia.

url.attr(object)

- object: objeto de atributos.

Establece múltiples valores de atributos.

retorna la instancia.

url.search()

Obtiene el atributo `search` en forma de objeto.

retorna un objeto.

url.search(name)

- name: nombre del componente.

Obtiene el valor del componente.

retorna el valor del componente (cadena de texto).

url.search(name, value)

- name: nombre del componente.
- value: valor del componente. Si es `null` el componente será eliminado.

Establece un nuevo valor al componente.

retorna la instancia.

url.hash()

Obtiene el atributo `hash` en forma de objeto.

retorna un objeto.

url.hash(name)

- name: nombre del componente.

Obtiene el valor del componente.

retorna el valor del componente (cadena de texto).

url.hash(name, value)

- name: nombre del componente.
- value: valor del componente. Si es `null` el componente será eliminado.

Establece un nuevo valor al componente.

retorna la instancia.

url.isExternal()

Comprueba si la dirección es externa basándose en la localización definida, y si esta no se encuentra definida, lo determinará comprobando si la dirección es una carpeta o no (si es una carpeta se considerará no externa).

retorna `true` o `false`.

url.select(name, name, ...)

- name: nombre del atributo.

Construye una dirección URL utilizando solamente los atributos seleccionados.

retorna la dirección URL (cadena de texto).

url.unselect(name, name, ...)

- name: nombre del atributo.

Construye una dirección URL excluyendo los atributos seleccionados.

retorna la dirección URL (cadena de texto).

url.from(name)

- name: nombre del atributo.

Construye una dirección URL empezando desde el atributo seleccionado.

retorna la dirección URL (cadena de texto).

url.to(name)

- name: nombre del atributo.

Construye una dirección URL empezando desde el primer atributo hasta el seleccionado.

retorna la dirección URL (cadena de texto).

Colabora

Para más información recomiendo que visite la documentación extendida del repositorio y los ejemplos. Y si desea ver todo el potencia de esta suite revise las pruebas unitarias.

No hay comentarios:

Publicar un comentario en la entrada