Crear persistentes notas adhesivas con Local Storage

Spanish (Español) translation by Elías Nicolás (you can also view the original English article)

El almacenamiento local HTML5 es como las cookies con esteroides; es increíblemente simple de usar y aún así tan poderoso. En este tutorial, le mostraré cómo crear la funcionalidad de "notas adhesivas", que permite a los usuarios tomar notas persistentes mientras navega por su sitio.

Paso 1: El HTML

Debido a la naturaleza dinámica de este proyecto, no hay mucho para codificar en el camino del antiguo marcado semántico. Simplemente simularemos una página web reuniendo un poco de contenido de relleno:

  <!DOCTYPE html>
    <html>
    <head>
        <meta charset='utf-8' />
        <title>HTML 5 complete</title>
        <link rel="stylesheet" href="default.css" />
        <link rel="stylesheet" href="stickies/stickies.css" />
        <!--[if IE]>
        <script src="https://html5shiv.googlecode.com/svn/trunk/html5.js"></script>
        <![endif]-->
    </head>
    <body>
        <article>
            <header>
                <h1> Sample Article Title</h1>
            </header>
            <p>Lorem ipsum dolor. . . </p>
            <!-- a few lorem-ipsum paragraphs later . . . -->
            <footer>
                <p>Copyright 2010 Andrew Burgess</p>
            </footer>
        </article>

        <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
        <script src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8.2/jquery-ui.min.js"></script>
        <script src="json2.js"></script>
        <script src="stickies/stickies.js"></script>
        <script>
        </script>
    </body>
    </html>

Hay algunas cosas importantes que notar aquí: estamos incluyendo dos archivos CSS: el primero es el estilo simple de la página, que hemos llamado default.css. Luego, tenemos un archivo CSS especial para estilos relacionados con nuestras notas adhesivas; se llama stickies.css, y como puede ver, vive en la carpeta "stickies". En la parte inferior, estamos incluyendo cuatro scripts:

jQuery, del CDN de Google
JQuery UI, del CDN de Google
JSON2, de Douglas Crockford
Nuestro propio stickies.js, que vive en el directorio "stickies"

Luego, tenemos una etiqueta de script vacía que usaremos para iniciar el motor un poco más tarde.

¡Y eso es todo por HTML!

Paso 2: El CSS

El contenido de default.css es increíblemente simple:

   body {
        margin:0;
        padding:0;
        background:#ccc;
        font:14px/1.5 "Helvetica Neue", Helvetica, Arial, san-serif;
    }
    article, footer, header { display: block; }
    article {
        width:880px;
        background:#fff;
        margin:auto;
        padding:40px;
    }
    article header {
        color:#474747;
        border-bottom:1px solid #474747
    }
    article footer {
        font-size:90%;
        color:#ccc;
    }

Eso es; ahora, está el CSS de stickies.css que cuidar ... pero aún no tenemos ese marcado. Empecemos con JavaScript, y cuando lo hagamos, veremos el CSS de las notas adhesivas.

Paso 3: El JavaScript

Aquí está el esqueleto de nuestra aplicación de JavaScript:

    var STICKIES = (function () {
        var initStickies = function () {},
            openStickies = function () {},
            createSticky = function (data) {},
            deleteSticky = function (id) {},
            saveSticky   = function () {},
            markUnsaved  = function () {};
            
        return {
            open   : openStickies,
            init   : initStickies
        };
    }());

Aquí tenemos algunas técnicas interesantes. Primero está la función de auto-involuntario: puede parecer que asignamos una función a la variable STICKIES, pero si miras detenidamente al final de la función, verás que la estamos ejecutando de inmediato. Como sugerencia, para recordarnos que esta no es una función normal, estamos envolviendo toda la función entre paréntesis. Entonces, STICKIES no es una función, es el valor devuelto por esa función, que es un objeto, en este caso.

Eso nos lleva a la siguiente técnica: cierre. Tenga en cuenta que de las seis funciones que creamos, solo dos de ellas están expuestas al usuario (realmente, solo una es necesaria para el uso que estamos planificando, si quisiéramos crear soporte para crear notas en su sitio web, podríamos exponer el createSticky y deleteSticky). Aunque la función de autoinversión finaliza antes de que usemos los métodos, podremos usar las otras funciones que hemos definido.

De acuerdo, pasemos al contenido de estas funciones.

initStickies

Comenzaremos mirando la función initStickies:

    var initStickies = function initStickies() {
        $("<div />", { 
            text : "+", 
            "class" : "add-sticky",
            click : function () { createSticky(); }
        }).prependTo(document.body);
        initStickies = null;
    },

Esto es bastante simple. Usaremos jQuery para crear elementos bastante, y estamos usando alguna sintaxis especial en v. 1.4: eso es pasar un literal de objeto con las especificaciones para el elemento como un segundo parámetro a la función jQuery. Aquí, estamos creando un botón para crear una nueva nota. Eso significa que necesitamos un nuevo div; estamos configurando el texto en "+" y dándole una clase "add-sticky"; entonces, estamos configurando un manejador de clics para llamar al método createSticky (es importante llamar a createSticky desde dentro de una función, y no tener la llamada del manejador de clics directamente a createSticky; esto es porque createSticky puede tomar un solo parámetro, y no quiero que sea el objeto del evento). Finalmente, estamos anteponiendo este div al cuerpo. Terminamos estableciendo initStickies en null; Sí, básicamente nos estamos deshaciendo de la función que estamos ejecutando. Esto nos asegura que esta función solo se ejecutará una vez; no queremos que el usuario de nuestra API agregue involuntariamente múltiples botones de "agregar nota" a la página.

openStickies

Pasemos al siguiente método, openStickies:

    openStickies = function openStickies() {
        initStickies && initStickies();
        for (var i = 0; i < localStorage.length; i++) {
            createSticky(JSON.parse(localStorage.getItem(localStorage.key(i))));
        }
    },

Comenzamos ejecutando initStickies... pero ¿qué pasa con la sintaxis sofisticada? Bueno, probablemente esté familiarizado con el operador &&: el operador AND booleano. Usualmente lo usaría para verificar múltiples condiciones en una instrucción if. Esto es lo que hace: evalúa la primera expresión, y si eso es cierto, continuará evaluando la segunda expresión. En este caso, si initStickies aún no se ha establecido en nulo, ejecutaremos la función. Esto evita el error que vendría al tratar de ejecutar una variable nula como una función.

A continuación, colocamos un bucle sobre cada elemento en localStorage. Esto es lo que hacemos en ese for-loop (de adentro hacia afuera):

localStorage.key() es una gran función que devuelve el nombre clave del valor localStorage; toma un número como un parámetro. Es una excelente forma de recorrer cada elemento en localStorage.
Una vez que tenemos la clave para un artículo almacenado, podemos pasarlo a localStorage.getItem() para obtener su valor.
Luego, pasamos ese valor a JSON.parse(); esto proviene de la biblioteca de Crockford. Debido a que estamos almacenando algunos valores para cada nota, estamos usando JSON.stringify() en el otro extremo para convertir un objeto en una cadena JSON, que almacenamos. Aquí, lo convertimos de una cadena a un objeto.
Finalmente, pasamos ese objeto a createSticky(), que lo vuelve a convertir en una nota adhesiva.

createSticky

Ahora, veamos ese método createSticky.

    createSticky = function createSticky(data) {
        data = data || { id : +new Date(), top : "40px", left : "40px", text : "Note Here" }
        
        return $("<div />", { 
            "class" : "sticky",
            'id' : data.id
             })
            .prepend($("<div />", { "class" : "sticky-header"} )
                .append($("<span />", { 
                    "class" : "status-sticky", 
                    click : saveSticky 
                }))
                .append($("<span />", { 
                    "class" : "close-sticky", 
                    text : "trash", 
                    click : function () { deleteSticky($(this).parents(".sticky").attr("id")); }
                }))
            )
            .append($("<div />", { 
                html : data.text, 
                contentEditable : true, 
                "class" : "sticky-content", 
                keypress : markUnsaved
            }))
        .draggable({ 
            handle : "div.sticky-header", 
            stack : ".sticky",
            start : markUnsaved,
            stop  : saveSticky  
         })
        .css({
            position: "absolute",
            "top" : data.top,
            "left": data.left
        })
        .focusout(saveSticky)
        .appendTo(document.body);
    },

Sí, es largo, pero no va a ser muy difícil. Primero, observe que esta función toma un objeto de datos; como acabamos de ver en openStickies, estamos pasando los datos almacenados a esta función. Sin embargo, si no transmitimos ningún dato (es decir, estamos creando una nota nueva), crearemos el objeto de nota predeterminado. Como todas las notas deben crearse en un punto, todas las notas comenzarán con esta configuración. Tenga en cuenta que para el ID de la nota, estamos usando +new Date(); El operador unario plus antepuesto convierte la fecha que obtenemos de una nueva fecha en un número, por lo que esta declaración da como resultado un número que representa el número de milisegundos desde el 1 de enero de 1970. Obviamente, este número cambiará continuamente, por lo que es una excelente forma de identificar de forma única cada nota.

El resto de la función es una larga cadena de métodos jQuery encadenados. Antes de pasar por esto, observe que estamos devolviendo el resultado. Si expusimos este método a los desarrolladores que usan nuestro mirco-API, devolvería una referencia al elemento div de nota adhesiva.

Entonces, esto es lo que está pasando:

Primero, creamos el div que es el caparazón de la nota adhesiva. Usando esa útil sintaxis de jQuery 1.4, le damos una clase de "pegajoso" y la identificación del objeto de datos.
Entonces, anteponemos un div a ese; este div obtiene una clase "sticky-header". div.sticky-header recibe dos tramos agregados a él. El primer, span.sticky-status, obtiene un controlador de clics que llama a la función saveSticky. Sin embargo, eso es en realidad una función oculta: este lapso mostrará el estado del adhesivo: guardado o no guardado. Habrá algunas formas en las que Sticky guardará sus datos en localStorage; es posible que el usuario piense que al hacer clic en "no guardado" se guardará la nota, por lo que le proporcionaremos esa funcionalidad. El segundo tramo, span.close-sticky, será el botón Eliminar: cuando el usuario haga clic en él, eliminaremos el material adhesivo de localStorage, a través del método deleteSticky. Pasamos ese método la identificación de la nota.
A continuación, agregamos otro div al div.sticky principal; observe que establecemos la propiedad html en data.text; cuando guardamos el texto de la nota, estamos utilizando el método html() de jQuery, porque el uso de text() elimina los saltos de línea. También establecemos contentEditable:true en este div, porque es el contenido de la nota. Como tal, también obtiene la clase sticky-content. Finalmente, cuando se presiona una tecla en este div (lo que significa que el usuario está cambiando el contenido), queremos marcarlo como no guardado, así que llamaremos a esa función (lo cual haremos pronto).
Ahora, estamos usando la característica jQuery UI que se puede arrastrar para hacer que nuestra nota adhesiva sea movible. En nuestro objeto de parámetro, usamos la propiedad handle para hacer que nuestras notas solo se puedan mover desde la barra de encabezado. La propiedad stack es un selector para los elementos arrastrables que desea "apilar"; estableciendo esto, la nota arrastrada siempre estara sobre todo. Finalmente, cuando comenzamos a arrastrar la nota, queremos marcarla como "no guardada" (porque también tenemos que guardar sus coordenadas), y cuando dejamos de arrastrarla, guardaremos esa.
A continuación, configuramos algunos estilos para nuestro div.sticky; lo posicionamos en forma absoluta, y luego establecemos sus valores superior e izquierdo a los que están en el objeto de datos. De esta manera, la nota mantendrá su posición así como su contenido cuando refresquemos la página.
Finalmente, configuraremos un manejador de eventos para cuando focusout (esencialmente, haga clic fuera luego de hacer clic dentro): queremos guardarla. Por último, lo agregaremos al cuerpo. Como referencia, aquí está la estructura html que deberíamos haber generado:

<div class="sticky ui-draggable" id="1281194825332" style="position: absolute; top: 40px; left: 40px;">
    <div class="sticky-header">
            <span class="sticky-status"></span>
            <span class="close-sticky">trash</span>
    </div>
    <div contenteditable="true" class="sticky-content">
        Note Here
    </div>
</div>

Y esa es nuestra función createSticky.

deleteSticky

Ahora tenemos la función deleteSticky; es realmente simple:

1	deleteSticky = function deleteSticky(id) {
2	localStorage.removeItem("sticky-" + id);
3	$("#" + id).fadeOut(200, function () { $(this).remove(); });
4	},

Como recordará, la función deleteSticky toma el ID de una nota como su parámetro. localStorage.removeItem() es el método de la hora: le pasamos la clave a un valor almacenado localmente para eliminar ese par clave-valor (Observe que cuando almacenamos los datos de la nota, estamos anteponiendo "sticky-" al ID). Luego, encontramos el elemento con el ID dado, lo atenuamos y lo eliminamos. Nota borrada

saveSticky

El penúltimo podría ser el método más importante hoy en día: saveSticky: este es el pegamento que hace que todo funcione.

    saveSticky = function saveSticky() {
        var that = $(this),  sticky = (that.hasClass("sticky-status") || that.hasClass("sticky-content")) ? that.parents('div.sticky'): that,
        obj = {
            id  : sticky.attr("id"),
            top : sticky.css("top"),
            left: sticky.css("left"),
            text: sticky.children(".sticky-content").html()               
        }
        localStorage.setItem("sticky-" + obj.id, JSON.stringify(obj));    
        sticky.find(".sticky-status").text("saved");
    },

La primera línea es un poco de resolución: hay tres elementos diferentes a los que podemos llamar esta función. Primero, "jQuerifaremos" this en that; luego, si el elemento tiene las clases "sticky-status" o "sticky-content", obtendremos el padre div.sticky; si no tiene ninguna de esas clases, entonces es div.sticky en sí mismo, así que solo usaremos eso.

Entonces, necesitamos obtener los valores que queremos almacenar. Como puede ver, estamos obteniendo la identificación, el desplazamiento desde la parte superior e izquierda, y el html del hijo .sticky-content; recuerde, estamos usando html() en lugar de text() porque queremos mantener los saltos de línea. Luego, usamos localStorage.setItem para almacenar los datos. Recuerde, toma dos parámetros: la clave y el valor para almacenar. Como localStorage solo almacena cadenas, usamos JSON.stringify() para convertir el objeto a una cadena.

Por último, cambie el estado adhesivo a "guardado".

markUnsaved

Tenemos una última función, que es solo una función auxiliar:

1	markUnsaved = function markUnsaved() {
2	var that = $(this), sticky = that.hasClass("sticky-content") ? that.parents("div.sticky") : that;
3	sticky.find(".sticky-status").text("unsaved");
4	}

Nuevamente, debemos comenzar resolviendo la referencia a div.sticky; una vez que lo hacemos, podemos simplemente encontrar el lapso de estado y establecer el texto como "no guardado".

Lo creas o no, eso es todo el JavaScript.

Paso 4: El CSS, revisitado

Ahora que sabemos cuál es nuestro marcado de notas adhesivas, podemos darle un estilo. Es bastante simple; pero mira, y haré algunos comentarios al final:

   :focus {
        outline:0;
    }
    .add-sticky {
        cursor: default;
        position:absolute;
        top:1px;
        left:1px;
        font-size:200%;
        background:#000;
        color:#fff;
        border:2px solid #fff;
        border-radius:40px;
        -webkit-border-radius:40px;
        -moz-border-radius:40px;
        text-align:center;
        line-height:25px;
        width:30px;
        height:30px;
    }
    .add-sticky:hover {
        background: #474747;
    }
    .sticky {
        width:300px;
        background:#fdfdbe;
        box-shadow:3px 3px 10px rgba(0,0,0,0.45);
        -webkit-box-shadow:3px 3px 10px rgba(0,0,0,0.45);
        -moz-box-shadow:3px 3px 10px rgba(0,0,0,0.45);
    }
    .sticky-content {
        min-height:150px;
        border-left:3px double rgba(238, 150, 122, .75);
        margin-left:30px;
        padding:5px;
    }
    .sticky-header {
        padding:5px;
        background:#f3f3f3;
        border-bottom:2px solid #fefefe;
        box-shadow:0 3px 5px rgba(0,0,0,0.25);
        -webkit-box-shadow:0 3px 5px rgba(0,0,0,0.25);
        -moz-box-shadow:0 3px 5px rgba(0,0,0,0.25);
    }
    .sticky-status {
        color:#ccc;
        padding:5px;
    }
    .close-sticky {
        background:#474747;
        float:right;
        cursor:default;
        color:#ececec;
        padding:1px 5px;
        border-radius:20px;
        -webkit-border-radius:20px;
        -moz-border-radius:20px;
    }

Aquí hay algunos puntos de interés:

Algunos navegadores ponen un contorno alrededor de los elementos con contenteditable=true cuando editas el contenido. No queremos eso, así que nos deshacemos de él con nuestra declaración de enfoque :focus.
El botón "Agregar adhesivo" está ubicado en la esquina superior izquierda; se ve vagamente similar al "Agregar widget del tablero de instrumentos" en Mac OS X.
Estamos utilizando las propiedades CSS3 border-box y box-shadow (y sus respectivas encarnaciones de prefijo de proveedor).
También usamos rgba() para nuestros colores de sombras. Toma cuatro parámetros: el rojo, la codicia y el azul, y el valor alfa (transparencia).

Aparte de eso, es solo su CSS estándar. Esto es lo que debería ser una nota con estilo:

Paso 5: Comenzando los Stickies

Ahora que hemos creado nuestra API, es hora de comenzar; podemos hacerlo desde la etiqueta script vacía adicional en nuestro archivo index.html:

1	STICKIES.open();

Conclusión: el producto final

Bueno, ¡ya terminamos! Aquí está el producto final en acción:

Eso es todo lo que tengo para hoy; ¿Cómo planeas utilizar el almacenamiento local HTML5 para darle más vida a tus proyectos web? ¡Házmelo saber en los comentarios!