diff options
Diffstat (limited to 'files/es/learn/javascript/client-side_web_apis')
4 files changed, 1488 insertions, 0 deletions
diff --git a/files/es/learn/javascript/client-side_web_apis/client-side_storage/index.html b/files/es/learn/javascript/client-side_web_apis/client-side_storage/index.html new file mode 100644 index 0000000000..0c03392e7d --- /dev/null +++ b/files/es/learn/javascript/client-side_web_apis/client-side_storage/index.html @@ -0,0 +1,788 @@ +--- +title: Almacenamiento del lado cliente +slug: Learn/JavaScript/Client-side_web_APIs/Client-side_storage +tags: + - API + - Almacenaje + - Article + - CodingScripting + - Guía + - IndexedDB + - JavaScript + - Principiante + - aprende +translation_of: Learn/JavaScript/Client-side_web_APIs/Client-side_storage +--- +<p>{{LearnSidebar}}</p> + +<div>{{PreviousMenu("Learn/JavaScript/Client-side_web_APIs/Video_and_audio_APIs", "Learn/JavaScript/Client-side_web_APIs")}}</div> + +<p class="summary">Los navegadores web modernos admiten varias formas para que los sitios web almacenen datos en la computadora del usuario, con el permiso del usuario, y luego los recuperen cuando sea necesario. Esto te permite conservar los datos para el almacenamiento a largo plazo, guardar sitios o documentos para su uso sin conexión, conservar la configuración específica del usuario para tu sitio y más. Este artículo explica los conceptos básicos de cómo funcionan.</p> + +<table class="learn-box standard-table"> + <tbody> + <tr> + <th scope="row">Prerrequisitos:</th> + <td>Conceptos básicos de JavaScript (consulta {{web.link("/es/docs/Learn/JavaScript/First_steps", "primeros pasos")}}, {{web.link("/es/docs/Learn/JavaScript/Building_blocks", "bloques de construcción")}}, {{web.link("/es/docs/Learn/JavaScript/Objects", "objetos JavaScript")}}), los {{web.link("/es/docs/Learn/JavaScript/Client-side_web_APIs/Introducción", "conceptos básicos de las APIs de lado del cliente")}}</td> + </tr> + <tr> + <th scope="row">Objetivo:</th> + <td>Aprender a utilizar las APIs de almacenamiento de lado del cliente para almacenar datos de aplicaciones.</td> + </tr> + </tbody> +</table> + +<h2 id="¿Almacenamiento_de_lado_del_cliente">¿Almacenamiento de lado del cliente?</h2> + +<p>En otra parte del área de aprendizaje de MDN, hablamos sobre la diferencia entre {{web.link("/es/docs/Learn/Server-side/First_steps/Client-Server_overview#Sitios_estaticos", "sitios estáticos")}} y {{web.link("/es/docs/Learn/Server-side/First_steps/Client-Server_overview#Sitios_dinamicos", "sitios dinámicos")}}. La mayoría de los principales sitios web modernos son dinámicos: almacenan datos en el servidor utilizando algún tipo de base de datos (almacenamiento de lado del servidor) y luego ejecutan {{web.link("/es/docs/Learn/Server-side", "de lado del servidor")}} para recuperar los datos necesarios, insertarlos en plantillas de páginas estáticas y entregar el HTML resultante al cliente para que lo muestre el navegador del usuario.</p> + +<p>El almacenamiento de lado del cliente funciona con principios similares, pero tiene diferentes usos. Consiste en una API de JavaScript que te permiten almacenar datos en el cliente (es decir, en la máquina del usuario) y luego recuperarlos cuando sea necesario. Esto tiene muchos usos distintos, como:</p> + +<ul> + <li>Personalizar las preferencias del sitio (por ejemplo, mostrar la elección de un usuario de artilugios personalizados, combinación de colores o tamaño del tipo de letra).</li> + <li>Persistencia de la actividad anterior del sitio (por ejemplo, almacenar el contenido de un carrito de compras de una sesión anterior, recordar si un usuario inició sesión anteriormente).</li> + <li>Guardar datos y activos localmente para que un sitio sea más rápido (y potencialmente menos costoso) de descargar o se pueda usar sin una conexión de red.</li> + <li>Guardar documentos generados por aplicaciones web localmente para usarlos sin conexión</li> +</ul> + +<p>A menudo, el almacenamiento de lado del cliente y de lado del servidor se utilizan juntos. Por ejemplo, puedes descargar un lote de archivos de música (quizás utilizados por un juego web o una aplicación de reproducción de música), almacenarlos dentro de una base de datos de lado del cliente y reproducirlos según sea necesario. El usuario solo tendría que descargar los archivos de música una vez; en las visitas posteriores, se recuperarían de la base de datos.</p> + +<div class="note"> +<p><strong>Nota</strong>: Existen límites en la cantidad de datos que puedes almacenar utilizando las APIs de almacenamiento de lado del cliente (posiblemente tanto por API individual como acumulativamente); el límite exacto varía según el navegador y posiblemente según la configuración del usuario. Consulta {{web.link("/es/docs/Web/API/IndexedDB_API/Browser_storage_limits_and_eviction_criteria", "límites de almacenamiento del navegador y criterios de desalojo")}} para obtener más información.</p> +</div> + +<h3 id="Vieja_escuela_cookies">Vieja escuela: <em>cookies</em></h3> + +<p>El concepto de almacenamiento de lado del cliente existe desde hace mucho tiempo. Desde los primeros días de la web, los sitios han utilizado <em>{{web.link("/es/docs/Web/HTTP/Cookies", "cookies")}}</em> para almacenar información y personalizar la experiencia del usuario en los sitios web. Son la forma más antigua de almacenamiento de lado del cliente que se usa comúnmente en la web.</p> + +<p>En estos días, existen mecanismos más fáciles disponibles para almacenar datos de lado del cliente, por lo tanto, no te enseñaremos cómo usar las <em>cookies</em> en este artículo. Sin embargo, esto no significa que las <em>cookies</em> sean completamente inútiles en la web moderna; todavía se usan comúnmente para almacenar datos relacionados con la personalización y el estado del usuario, p. ej. ID de sesión y fragmentos de acceso. Para obtener más información sobre las <em>cookies</em>, consulta nuestro artículo {{web.link("/es/docs/Web/HTTP/Cookies", "Uso de cookies HTTP")}}.</p> + +<h3 id="Nueva_escuela_almacenamiento_web_e_IndexedDB">Nueva escuela: almacenamiento web e <code>IndexedDB</code></h3> + +<p>Las características "más fáciles" que mencionamos anteriormente son las siguientes:</p> + +<ul> + <li>La {{web.link("/es/docs/Web/API/Web_Storage_API", "API de almacenamiento web")}} proporciona una sintaxis muy simple para almacenar y recuperar elementos de datos más pequeños que constan de un nombre y un valor correspondiente. Esto es útil cuando solo necesitas almacenar algunos datos simples, como el nombre del usuario, si está conectado, qué color usar para el fondo de la pantalla, etc.</li> + <li>La {{web.link("/es/docs/Web/API/IndexedDB_API", "API IndexedDB")}} proporciona al navegador un sistema de base de datos completo para almacenar datos complejos. Esto se puede usar para cosas desde conjuntos completos de registros de clientes, hasta incluso tipos de datos complejos como archivos de audio o video.</li> +</ul> + +<p>Aprenderás más sobre estas APIs a continuación.</p> + +<h3 id="El_futuro_API_de_caché">El futuro: API de caché</h3> + +<p>Algunos navegadores modernos admiten la nueva API {{domxref("Cache")}}. Esta API está diseñada para almacenar respuestas HTTP a solicitudes específicas y es muy útil para hacer cosas como almacenar activos del sitio web sin conexión para que el sitio se pueda usar posteriormente sin una conexión de red. La caché generalmente se usa en combinación con la {{web.link("/es/docs/Web/API/Service_Worker_API", "API del servicio Worker")}}, aunque no necesariamente tiene que ser así.</p> + +<p>El uso de caché y el servicio <em>Workers</em> es un tema avanzado, y no lo cubriremos con gran detalle en este artículo, aunque mostraremos un ejemplo simple en la sección {{anch("Almacenamiento_de_activos_sin_conexion", "Almacenamiento de activos sin conexión")}} a continuación.</p> + +<h2 id="Almacenamiento_de_datos_simples_almacenamiento_web">Almacenamiento de datos simples: almacenamiento web</h2> + +<p>La {{web.link("/es/docs/Web/API/Web_Storage_API", "API de almacenamiento web")}} es muy fácil de usar: almacena pares de datos simples de nombre/valor (limitado a cadenas, números, etc.) y recupera estos valores cuando sea necesario.</p> + +<h3 id="Sintaxis_básica">Sintaxis básica</h3> + +<p>Te mostramos como:</p> + +<ol> + <li> + <p>Primero, ve a nuestra <a href="https://mdn.github.io/learning-area/javascript/apis/client-side-storage/web-storage/index.html">plantilla en blanco de almacenamiento web</a> en GitHub (abre esto en una nueva pestaña).</p> + </li> + <li> + <p>Abre la consola JavaScript de las herramientas de desarrollo de tu navegador.</p> + </li> + <li> + <p>Todos tus datos de almacenamiento web están contenidos en dos estructuras similares a objetos dentro del navegador: {{domxref("Window.sessionStorage", "sessionStorage")}} y {{domxref("Window.localStorage", "localStorage")}}. El primero conserva los datos mientras el navegador está abierto (los datos se pierden cuando se cierra el navegador) y el segundo conserva los datos incluso después de que el navegador se cierra y luego se vuelve a abrir. Usaremos el segundo en este artículo, ya que generalmente es más útil.</p> + + <p>El método {{domxref("Storage.setItem()")}} te permite guardar un elemento de datos en el almacenamiento; toma dos parámetros: el nombre del elemento y su valor. Intenta escribir esto en tu consola de JavaScript (cambia el valor a tu propio nombre, si lo deseas):</p> + + <pre class="brush: js notranslate">localStorage.setItem('nombre','Chris');</pre> + </li> + <li> + <p>El método {{domxref("Storage.getItem()")}} toma un parámetro, el nombre de un elemento de datos que deseas recuperar, y devuelve el valor del elemento. Ahora escribe estas líneas en tu consola JavaScript:</p> + + <pre class="brush: js notranslate">let miNombre = localStorage.getItem('nombre'); +miNombre</pre> + + <p>Al escribir en la segunda línea, deberías ver que la variable <code>miNombre</code> ahora contiene el valor del elemento de datos <code>nombre</code>.</p> + </li> + <li> + <p>El método {{domxref("Storage.removeItem()")}} toma un parámetro, el nombre de un elemento de datos que desea eliminar, y elimina ese elemento del almacenamiento web. Escribe las siguientes líneas en tu consola JavaScript:</p> + + <pre class="brush: js notranslate">localStorage.removeItem('nombre'); +let miNombre = localStorage.getItem('nombre'); +miNombre</pre> + + <p>La tercera línea ahora debería devolver <code>null</code>: el elemento <code>nombre</code> ya no existe en el almacenamiento web.</p> + </li> +</ol> + +<h3 id="¡Los_datos_persisten!">¡Los datos persisten!</h3> + +<p>Una característica clave del almacenamiento web es que los datos persisten entre las cargas de la página (e incluso cuando el navegador está apagado, en el caso de <code>localStorage</code>). Veamos esto en acción.</p> + +<ol> + <li> + <p>Abre nuestra plantilla en blanco de almacenamiento web nuevamente, ¡pero esta vez en un navegador diferente al que tiene abierto este tutorial!; Esto hará que sea más fácil de manejar.</p> + </li> + <li> + <p>Escribe estas líneas en la consola JavaScript del navegador:</p> + + <pre class="brush: js notranslate">localStorage.setItem('nombre','Chris'); +let miNombre = localStorage.getItem('nombre'); +miNombre</pre> + + <p>Deberías ver el nombre del elemento devuelto.</p> + </li> + <li> + <p>Ahora cierre el navegador y ábrelo de nuevo.</p> + </li> + <li> + <p>Ingresa las siguientes líneas nuevamente:</p> + + <pre class="brush: js notranslate">let miNombre = localStorage.getItem('nombre'); +miNombre</pre> + + <p>Deberías ver que el valor aún está disponible, aunque el navegador se haya cerrado y luego se haya abierto nuevamente.</p> + </li> +</ol> + +<h3 id="Almacenamiento_independiente_para_cada_dominio">Almacenamiento independiente para cada dominio</h3> + +<p>Hay un almacén de datos separado para cada dominio (cada dirección web separada cargada en el navegador). Verás que si cargas dos sitios web (por ejemplo, google.com y amazon.com) e intentas almacenar un elemento en un sitio web, no estará disponible para el otro sitio web.</p> + +<p>Esto tiene sentido: ¿puedes imaginar los problemas de seguridad que surgirían si los sitios web pudieran ver los datos de los demás?</p> + +<h3 id="Un_ejemplo_más_complicado">Un ejemplo más complicado</h3> + +<p>Apliquemos este conocimiento recién descubierto escribiendo un sencillo ejemplo para darte una idea de cómo se puede usar el almacenamiento web. Nuestro ejemplo te permitirá ingresar un nombre, luego de lo cual la página se actualizará para darte un saludo personalizado. Este estado también persistirá en las recargas de la página/navegador, porque el nombre se guarda en el almacenamiento web.</p> + +<p>Puede encontrar el HTML de ejemplo en <a href="https://github.com/mdn/learning-area/blob/master/javascript/apis/client-side-storage/web-storage/personal-greeting.html">personal-greeting.html</a>: contiene un sitio web simple con un encabezado, contenido y pie de página, y un formulario para ingresar tu nombre.</p> + +<p><img alt="Ejemplo de almacenamiento" src="https://mdn.mozillademos.org/files/15735/web-storage-demo.png" style="display: block; margin: 0 auto;"></p> + +<p>Construyamos el ejemplo para que puedas entender cómo funciona.</p> + +<ol> + <li> + <p>Primero, haz una copia local de nuestro archivo <a href="https://github.com/mdn/learning-area/blob/master/javascript/apis/client-side-storage/web-storage/personal-greeting.html">personal-greeting.html</a> en un nuevo directorio en tu computadora.</p> + </li> + <li> + <p>A continuación, observa cómo nuestro HTML hace referencia a un archivo JavaScript llamado <code>index.js</code> (ve la línea 40). Necesitamos crearlo y escribir nuestro código JavaScript en él. Cree un archivo <code>index.js</code> en el mismo directorio que tu archivo HTML.</p> + </li> + <li> + <p>Comenzaremos creando referencias a todas las características HTML que necesitamos manipular en este ejemplo; las crearemos todas como constantes, ya que estas referencias no necesitan cambiar en el ciclo de vida de la aplicación. Agrega las siguientes líneas a tu archivo JavaScript:</p> + + <pre class="brush: js notranslate">// crea las constantes necesarias +const rememberDiv = document.querySelector('.remember'); +const forgetDiv = document.querySelector('.forget'); +const form = document.querySelector('form'); +const nameInput = document.querySelector('#entername'); +const submitBtn = document.querySelector('#submitname'); +const forgetBtn = document.querySelector('#forgetname'); + +const h1 = document.querySelector('h1'); +const personalGreeting = document.querySelector('.personal-greeting');</pre> + </li> + <li> + <p>A continuación, necesitamos incluir un pequeño escucha de eventos para evitar que el formulario se envíe cuando se presiona el botón de envío, ya que este no es el comportamiento que queremos. Agrega este fragmento debajo de tu código anterior:</p> + + <pre class="brush: js notranslate">// Evita que el formulario se envíe cuando se presiona un botón +form.addEventListener('submit', function(e) { + e.preventDefault(); +});</pre> + </li> + <li> + <p>Ahora necesitamos agregar un escucha de eventos, cuya función controladora se ejecutará cuando se haga clic en el botón "Saludar". Los comentarios explican en detalle qué hace cada bit, pero en esencia aquí tomamos el nombre que el usuario ingresó en el cuadro de entrada de texto y lo guardamos en el almacenamiento web usando <code>setItem()</code>, luego ejecutamos una función llamada <code>nameDisplayCheck()</code> que se encargará de actualizar el texto real del sitio web. Agrega esto al final de tu código:</p> + + <pre class="brush: js notranslate">// ejecuta la función cuando se hace clic en el botón 'Saludar' +submitBtn.addEventListener('click', function() { + // guarda el nombre ingresado en el almacenamiento web + localStorage.setItem('name', nameInput.value); + // ejecuta nameDisplayCheck() para ordenar la visualización del + // saludo personalizado y actualización de la visualización del formulario + nameDisplayCheck(); +});</pre> + </li> + <li> + <p>En este punto, también necesitamos un controlador de eventos para ejecutar una función cuando se hace clic en el botón "Olvidar"; esto solo se muestra después de hacer clic en el botón "Saludar" (los dos estados del formulario se alternan hacia adelante y hacia atrás). En esta función, eliminamos el elemento <code>name</code> del almacenamiento web usando <code>removeItem()</code>, luego ejecutamos nuevamente <code>nameDisplayCheck()</code> para actualizar la pantalla. Agrega esto al final:</p> + + <pre class="brush: js notranslate">// ejecuta la función cuando se hace clic en el botón 'Olvidar' +forgetBtn.addEventListener('click', function() { + // Elimina el nombre guardado del almacenamiento web + localStorage.removeItem('nombre'); + // ejecuta nameDisplayCheck() para ordenar la visualización del + // saludo genérico nuevamente y actualiza la visualización del formulario + nameDisplayCheck(); +});</pre> + </li> + <li> + <p>Ahora es el momento de definir la propia función <code>nameDisplayCheck()</code>. Aquí verificamos si el elemento de nombre se ha guardado en el almacenamiento web utilizando <code>localStorage.getItem('name')</code> como prueba condicional. Si se ha guardado, esta llamada se evaluará como <code>true</code>; si no, será <code>false</code>. Si es <code>true</code>, mostramos un saludo personalizado, mostramos la parte "Olvidar" del formulario y ocultamos la parte "Saludar" del formulario. Si es <code>false</code>, mostramos un saludo genérico y hacemos lo contrario. Nuevamente, pon el siguiente código en la parte inferior:</p> + + <pre class="brush: js notranslate">// definir la función nameDisplayCheck() +function nameDisplayCheck() { + // verifica si el elemento de datos 'name' está guardado en el almacenamiento web + if(localStorage.getItem('name')) { + // Si es así, muestra un saludo personalizado + let name = localStorage.getItem('name'); + h1.textContent = 'Bienvenido, ' + name; + personalGreeting.textContent = '¡Bienvenido a nuestro sitio web, ' + name + '! Esperamos que te diviertas mientras estés aquí.'; + // ocultar la parte 'recordar' del formulario y mostrar la parte 'olvidar' + forgetDiv.style.display = 'block'; + rememberDiv.style.display = 'none'; + } else { + // si no, muestra un saludo genérico + h1.textContent = 'Bienvenido a nuestro sitio web '; + personalGreeting.textContent = 'Bienvenido a nuestro sitio web. Esperamos que se diviertas mientras estés aquí.'; + // ocultar la parte 'olvidar' del formulario y mostrar la parte 'recordar' + forgetDiv.style.display = 'none'; + rememberDiv.style.display = 'block'; + } +}</pre> + </li> + <li> + <p>Por último, pero no menos importante, debemos ejecutar la función <code>nameDisplayCheck()</code> cada vez que se carga la página. Si no hacemos esto, el saludo personalizado no persistirá en las recargas de la página. Agrega lo siguiente al final de tu código:</p> + + <pre class="brush: js notranslate">document.body.onload = nameDisplayCheck;</pre> + </li> +</ol> + +<p>Tu ejemplo está terminado, ¡bien hecho!; Todo lo que queda ahora es guardar tu código y probar tu página HTML en un navegador. Puedes ver nuestra <a href="https://mdn.github.io/learning-area/javascript/apis/client-side-storage/web-storage/personal-greeting.html">versión finalizada en vivo aquí</a>.</p> + +<div class="note"> +<p><strong>Nota</strong>: Hay otro ejemplo un poco más complejo para explorar en {{web.link("/es/docs/Web/API/Web_Storage_API/Using_the_Web_Storage_API", "Uso de la API de almacenamiento web")}}.</p> +</div> + +<div class="note"> +<p><strong>Nota</strong>: En la línea <code><script src="index.js" defer></script></code> del código fuente de nuestra versión final, el atributo <code>defer</code> especifica que el contenido del elemento {{htmlelement("script")}} no se ejecutará hasta que la página haya terminado de cargarse.</p> +</div> + +<h2 id="Almacenamiento_de_datos_complejos_—_IndexedDB">Almacenamiento de datos complejos — <code>IndexedDB</code></h2> + +<p>La {{web.link("/es/docs/Web/API/IndexedDB_API", "API IndexedDB")}} (a veces abreviada <em>IDB</em>) es un sistema de base de datos completo disponible en el navegador en el que puedes almacenar datos complejos relacionados, tipos de los cuales no se limitan a valores simples como cadenas o números. Puedes almacenar videos, imágenes y casi cualquier otra cosa en una instancia de <code>IndexedDB</code>.</p> + +<p>Sin embargo, esto tiene un costo: <code>IndexedDB</code> es mucho más complejo de usar que la API de almacenamiento web. En esta sección, solo vamos a arañar la superficie de lo que es capaz de hacer, pero te daremos lo suficiente para comenzar.</p> + +<h3 id="Trabajar_con_un_ejemplo_de_almacenamiento_de_notas">Trabajar con un ejemplo de almacenamiento de notas</h3> + +<p>Aquí, mostraremos un ejemplo que te permite almacenar notas en tu navegador y verlas y eliminarlas cuando lo desees, lo cual te permitirá crearlo tú mismo y explicar las partes más fundamentales del <em>IDB</em> a medida que avanzamos.</p> + +<p>La aplicación se parece a esta:</p> + +<p><img alt="IDB en acción" src="https://mdn.mozillademos.org/files/15744/idb-demo.png" style="border-style: solid; border-width: 1px; display: block; margin: 0px auto;"></p> + +<p>Cada nota tiene un título y un cuerpo de texto, cada uno editable individualmente. El código JavaScript que veremos a continuación tiene comentarios detallados para ayudarte a comprender lo que está sucediendo.</p> + +<h3 id="Primeros_pasos">Primeros pasos</h3> + +<ol> + <li>En primer lugar, haz copias locales de nuestros archivos <a href="https://github.com/mdn/learning-area/blob/master/javascript/apis/client-side-storage/indexeddb/notes/index.html"><code>index.html</code></a>, <a href="https://github.com/mdn/learning-area/blob/master/javascript/apis/client-side-storage/indexeddb/notes/style.css"><code>style.css</code></a> y <a href="https://github.com/mdn/learning-area/blob/master/javascript/apis/client-side-storage/indexeddb/notes/index-start.js"><code>index-start.js</code></a> en un nuevo directorio en tu máquina.</li> + <li>Échale un vistazo a los archivos. Verás que el HTML es bastante simple: un sitio web con encabezado y pie de página, así como un área de contenido principal que contiene un lugar para mostrar notas y un formulario para ingresar nuevas notas en la base de datos. El CSS proporciona un estilo simple para aclarar lo que está sucediendo. El archivo JavaScript contiene cinco constantes declaradas que contienen referencias al elemento {{htmlelement("ul")}} en el que se mostrarán las notas, el título y el cuerpo de elementos {{htmlelement("input")}}, el {{htmlelement("form")}} en sí mismo, y el {{htmlelement("button")}}.</li> + <li>Cambia el nombre de tu archivo JavaScript a <code>index.js</code>. Ahora estás listo para comenzar a agregarle código.</li> +</ol> + +<h3 id="Configuración_inicial_de_la_base_de_datos">Configuración inicial de la base de datos</h3> + +<p>Ahora veamos lo que tenemos que hacer en primer lugar, para configurar una base de datos.</p> + +<ol> + <li> + <p>Debajo de las declaraciones constantes, agrega las siguientes líneas:</p> + + <pre class="brush: js notranslate">// Crea una instancia de un objeto db para que almacenemos la base de datos abierta +let db;</pre> + + <p>Aquí estamos declarando una variable llamada <code>db</code>, que luego se usará para almacenar un objeto que representa nuestra base de datos. Usaremos esto en algunos lugares, por lo que hemos declarado globalmente aquí para facilitar las cosas.</p> + </li> + <li> + <p>A continuación, agrega lo siguiente al final de tu código:</p> + + <pre class="brush: js notranslate">window.onload = function() { + +};</pre> + + <p>Escribiremos todo nuestro subsiguiente código dentro de esta función controladora de eventos <code>window.onload</code>, llamada cuando se activa el evento {{event("load")}} de la ventana, para asegurarnos de que no intentemos usar la funcionalidad <code>IndexedDB</code> antes de que la aplicación haya terminado de cargarse por completo (podría fallar si no lo hacemos).</p> + </li> + <li> + <p>Dentro del controlador <code>window.onload</code>, agrega lo siguiente:</p> + + <pre class="brush: js notranslate">// Abre nuestra base de datos; se crea si aún no existe +// (ve onupgradeneeded a continuación) +let request = window.indexedDB.open('notes_db', 1);</pre> + + <p>Esta línea crea una <code>solicitud</code> para abrir la versión <code>1</code> de una base de datos llamada <code>notes_db</code>. Si esta aún no existe, se creará para ti mediante un código posterior. Verás que este patrón de solicitud se usa con mucha frecuencia en <code>IndexedDB</code>. Las operaciones de la base de datos llevan tiempo. No deseas colgar el navegador mientras esperas los resultados, por lo que las operaciones de la base de datos son {{Glossary("asíncronas")}}, lo que significa que en lugar de ocurrir de inmediato, sucederán en algún momento en el futuro, y recibirás una notificación cuando haya terminado.</p> + + <p>Para manejar esto en IndexedDB, crea un objeto de solicitud (que se puede llamar como desees; lo llamamos <code>request</code>, por lo que es obvio para qué sirve). Luego, usa controladores de eventos para ejecutar código cuando la solicitud se completa, falla, etc., que verás en uso a continuación.</p> + + <div class="note"> + <p><strong>Nota</strong>: El número de versión es importante. Si deseas actualizar tu base de datos (por ejemplo, cambiando la estructura de la tabla), debes ejecutar tu código nuevamente con un número de versión aumentado, un esquema diferente especificado dentro del controlador <code>onupgradeneeded</code> (ve más abajo), etc. No cubriremos la actualización de bases de datos en este sencillo tutorial.</p> + </div> + </li> + <li> + <p>Ahora agrega los siguientes controladores de eventos justo debajo de tu adición anterior, nuevamente dentro del controlador <code>window.onload</code>:</p> + + <pre class="brush: js notranslate">// un controlador de error significa que la base de datos no se abrió correctamente +request.onerror = function() { + console.log('No se pudo abrir la base de datos'); +}; + +// controlador onsuccess significa que la base de datos se abrió correctamente +request.onsuccess = function() { + console.log('Base de datos abierta con éxito'); + + // Almacena el objeto de base de datos abierto en la variable db. Esto se usa mucho a continuación + db = request.result; + + // Ejecute la función displayData() para mostrar las notas que ya están en la IDB + displayData(); +};</pre> + + <p>El controlador {{domxref("IDBRequest.onerror", "request.onerror")}} se ejecutará si el sistema dice que la solicitud falló. Esto te permite responder a este problema. En nuestro sencillo ejemplo, simplemente imprimimos un mensaje en la consola de JavaScript.</p> + + <p>El controlador {{domxref("IDBRequest.onsuccess", "request.onsuccess")}} por otro lado se ejecutará si la solicitud regresa con éxito, lo que significa que la base de datos se abrió correctamente. Si este es el caso, un objeto que representa la base de datos abierta pasa a estar disponible en la propiedad {{domxref("IDBRequest.result", "request.result")}}, lo que nos permite manipular la base de datos. Almacenamos esto en la variable <code>db</code> que creamos anteriormente para su uso posterior. También ejecutamos una función personalizada llamada <code>displayData()</code>, que muestra los datos en la base de datos dentro de {{HTMLElement("ul")}}. Lo ejecutamos ahora para que las notas que ya están en la base de datos se muestren tan pronto como se cargue la página. Verás esto definido más adelante.</p> + </li> + <li> + <p>Finalmente, en esta sección, agregaremos probablemente el controlador de eventos más importante para configurar la base de datos: {{domxref("IDBOpenDBRequest.onupgradeneeded", "request.onupgradeneeded")}}. Este controlador se ejecuta si la base de datos aún no se ha configurado, o si la base de datos se abre con un número de versión mayor que la base de datos almacenada existente (al realizar una actualización). Agrega el siguiente código, debajo de tu controlador anterior:</p> + + <pre class="brush: js notranslate">// Configura las tablas de la base de datos si esto aún no se ha hecho +request.onupgradeneeded = function(e) { + // Toma una referencia a la base de datos abierta + let db = e.target.result; + + // Crea un objectStore para almacenar nuestras notas (básicamente como una sola tabla) + // incluyendo una clave de incremento automático + let objectStore = db.createObjectStore('notes_os', {keyPath: 'id', autoIncrement: true}); + + // Define qué elementos de datos contendrá el objectStore + objectStore.createIndex('title', 'title', { unique: false }); + objectStore.createIndex('body', 'body', { unique: false }); + + console.log('Configuración de la base de datos completa'); +};</pre> + + <p>Aquí es donde definimos el esquema (estructura) de nuestra base de datos; es decir, el conjunto de columnas (o campos) que contiene. Aquí primero tomamos una referencia a la base de datos existente de la propiedad <code>result</code> del objetivo del evento (<code>e.target.result</code>), que es el objeto <code>request</code>. Esto es equivalente a la línea <code>db = request.result;</code> dentro del controlador <code>onsuccess</code>, pero aquí, debemos hacer esto por separado porque el controlador <code>onupgradeneeded</code> (si es necesario) se ejecutará antes que el controlador <code>onsuccess</code>, lo que significa que el valor <code>db</code> no estaría disponible si no hiciéramos esto.</p> + + <p>Luego usamos {{domxref("IDBDatabase.createObjectStore()")}} para crear un nuevo almacén de objetos dentro de nuestra base de datos abierta llamada <code>notes_os</code>. Esto es equivalente a una sola tabla en un sistema de base de datos convencional. Le hemos dado el nombre <em>notas</em>, y también hemos especificado un campo clave <code>autoIncrement</code> llamado <code>id</code> — en cada nuevo registro se le dará automáticamente un valor incrementado — el desarrollador no lo hace No es necesario establecer esto explícitamente. Al ser la clave, el campo <code>id</code> se utilizará para identificar registros de forma única, como cuando se elimina o muestra un registro.</p> + + <p>También creamos otros dos índices (campos) usando el método {{domxref("IDBObjectStore.createIndex()")}}: <code>title</code> (que contendrá un título para cada nota) y <code>body</code> (que contendrá el texto del cuerpo de la nota).</p> + </li> +</ol> + +<p>Entonces, con este esquema de base de datos simple configurado, cuando comenzamos a agregar registros a la base de datos; cada uno se representará como un objeto siguiendo estas líneas:</p> + +<pre class="brush: js notranslate">{ + title: "Compra leche", + body: "Necesita leche de vaca y soja", + id: 8 +}</pre> + +<h3 id="Agregar_datos_a_la_base_de_datos">Agregar datos a la base de datos</h3> + +<p>Ahora veamos cómo podemos agregar registros a la base de datos. Esto se hará mediante el formulario de nuestra página.</p> + +<p>Debajo de tu controlador de eventos anterior (pero aún dentro del controlador <code>window.onload</code>), agrega la siguiente línea, que configura un controlador <code>onsubmit</code> que ejecuta una función llamada <code>addData()</code> cuando se envía el formulario (cuando se presiona el {{htmlelement("button")}} de enviar, lo que lleva a un envío exitoso del formulario):</p> + +<pre class="brush: js notranslate">// Crea un controlador onsubmit para que cuando se envíe el formulario se ejecute la función addData() +form.onsubmit = addData;</pre> + +<p>Ahora definamos la función <code>addData()</code>. Agrega esto debajo de tu línea anterior:</p> + +<pre class="brush: js notranslate">// Define la función addData() +function addData(e) { + // evitar el predeterminado: no queremos que el formulario se envíe de la forma convencional + e.preventDefault(); + + // toma los valores ingresados en los campos del formulario y los almacenar en un objeto listo para ser insertado en la base de datos + let newItem = { title: titleInput.value, body: bodyInput.value }; + + // abre una transacción de base de datos de lectura/escritura, lista para agregar los datos + let transaction = db.transaction(['notes_os'], 'readwrite'); + + // llama a un almacén de objetos que ya se ha agregado a la base de datos + let objectStore = transaction.objectStore('notes_os'); + + // Hacer una solicitud para agregar nuestro objeto newItem al almacén de objetos + let request = objectStore.add(newItem); + request.onsuccess = function() { + // Limpiar el formulario, listo para agregar la siguiente entrada + titleInput.value = ''; + bodyInput.value = ''; + }; + + // Informa sobre el éxito de la transacción completada, cuando todo esté hecho + transaction.oncomplete = function() { + console.log('Transacción completada: modificación de la base de datos finalizada.'); + + // actualiza la visualización de datos para mostrar el elemento recién agregado, ejecutando displayData() nuevamente. + displayData(); + }; + + transaction.onerror = function() { + console.log('Transacción no abierta debido a error'); + }; +}</pre> + +<p>Esto es bastante complejo; desglosándolo, podemos:</p> + +<ul> + <li>Ejecuta {{domxref("Event.preventDefault()")}} en el objeto de evento para detener el envío del formulario de la manera convencional (esto provocaría una actualización de la página y estropearía la experiencia).</li> + <li>Crea un objeto que represente un registro para ingresar a la base de datos, llenándolo con valores de las entradas del formulario. ten en cuenta que no tenemos que incluir explícitamente un valor de <code>id</code>; como explicamos anteriormente, esto se completa automáticamente.</li> + <li>Abre una transacción <code>readwrite</code> contra el almacén de objetos <code>notes_os</code> utilizando el método {{domxref("IDBDatabase.transaction()")}}. Este objeto de transacción nos permite acceder al almacén de objetos para que podamos hacerle algo, p. ej. agregar un nuevo registro.</li> + <li>Accede a la tienda de objetos utilizando el método {{domxref("IDBTransaction.objectStore()")}}, guardando el resultado en la variable <code>objectStore</code>.</li> + <li>Agrega el nuevo registro a la base de datos usando {{domxref("IDBObjectStore.add()")}}. Esto crea un objeto <code>request</code>, de la misma manera que hemos visto antes.</li> + <li>Agrega un grupo de controladores de eventos a <code> request</code> y a <code>transaction</code> para ejecutar código en puntos críticos del ciclo de vida. Una vez que la solicitud ha tenido éxito, borramos las entradas del formulario y estamos listos para ingresar la siguiente nota. Una vez que la transacción se ha completado, ejecutamos la función <code>displayData()</code> nuevamente para actualizar la visualización de notas en la página.</li> +</ul> + +<h3 id="Visualización_de_los_datos">Visualización de los datos</h3> + +<p>Ya hemos hecho referencia a <code>displayData()</code> dos veces en nuestro código, por lo que probablemente sea mejor definirla. Agrega esto a tu código, debajo de la definición de función anterior:</p> + +<pre class="brush: js notranslate">// Define la función displayData() +function displayData() { + // Aquí vaciamos el contenido del elemento de la lista cada vez que se actualiza la pantalla + // Si no hiciste esto, obtendrás duplicados en la lista cada vez que se agregue una nueva nota + while (list.firstChild) { + list.removeChild(list.firstChild); + } + + // Abre el almacén de objetos y luego obtiene un cursor, que recorre todos los + // diferentes elementos de datos en el almacén + let objectStore = db.transaction('notes_os').objectStore('notes_os'); + objectStore.openCursor().onsuccess = function(e) { + // Obtiene una referencia al cursor + let cursor = e.target.result; + + // Si todavía hay otro elemento de datos para iterar, sigue ejecutando este código + if(cursor) { + // Crea un elemento de lista, h3 y p para poner cada elemento de datos dentro al mostrarlo + // estructura el fragmento HTML y lo anexa dentro de la lista + const listItem = document.createElement('li'); + const h3 = document.createElement('h3'); + const para = document.createElement('p'); + + listItem.appendChild(h3); + listItem.appendChild(para); + list.appendChild(listItem); + + // Coloca los datos del cursor dentro de h3 y para + h3.textContent = cursor.value.title; + para.textContent = cursor.value.body; + + // Almacena el ID del elemento de datos dentro de un atributo en listItem, para que sepamos + // a qué elemento corresponde. Esto será útil más adelante cuando queramos eliminar elementos. + listItem.setAttribute('data-note-id', cursor.value.id); + + // Crea un botón y lo coloca dentro de cada listItem + const deleteBtn = document.createElement('button'); + listItem.appendChild(deleteBtn); + deleteBtn.textContent = 'Delete'; + + // Establece un controlador de eventos para que cuando se hace clic en el botón, el elemento deleteItem() + // se ejecuta la función + deleteBtn.onclick = deleteItem; + + // Iterar al siguiente elemento del cursor + cursor.continue(); + } else { + // Nuevamente, si el elemento de la lista está vacío, muestra el mensaje 'No hay notas almacenadas' + if(!list.firstChild) { + const listItem = document.createElement('li'); + listItem.textContent = 'No hay notas almacenadas.'; + list.appendChild(listItem); + } + // si no hay más elementos de cursor para iterar, dilo + console.log('Se muestran todas las notas'); + } + }; +}</pre> + +<p>De nuevo, analicemos esto:</p> + +<ul> + <li>Primero vaciamos el contenido del elemento {{htmlelement("ul")}}, antes de llenarlo con el contenido actualizado. Si no hiciera esto, terminarías con una enorme lista de contenido duplicado que se agrega con cada actualización.</li> + <li>A continuación, obtenemos una referencia al almacén de objetos <code>notes_os</code> usando {{domxref("IDBDatabase.transaction()")}} y {{domxref("IDBTransaction.objectStore()")}} como hicimos en <code>addData()</code>, excepto que aquí los estamos encadenando juntos en una línea.</li> + <li>El siguiente paso es usar el método {{domxref("IDBObjectStore.openCursor()")}} para abrir una solicitud de un cursor; esta es una construcción que se puede usar para iterar sobre los registros en un almacén de objetos. Encadenamos un controlador <code>onsuccess</code> al final de esta línea para que el código sea más conciso: cuando el cursor se devuelve correctamente, se ejecuta el controlador.</li> + <li>Obtenemos una referencia al propio cursor (un objeto {{domxref("IDBCursor")}}) usando let <code>cursor = e.target.result</code>.</li> + <li>A continuación, verificamos si el cursor contiene un registro del almacén de datos (<code>if (cursor) {...}</code>); si es así, creamos un fragmento DOM, lo llenamos con los datos del registro y lo insertamos en la página (dentro del elemento <code><ul></code>). También incluimos un botón para eliminar que, al hacer clic, eliminará esa nota ejecutando la función <code>deleteItem()</code>, que veremos en la siguiente sección.</li> + <li>Al final del bloque <code>if</code>, usamos el método {{domxref("IDBCursor.continue()")}} para hacer avanzar el cursor al siguiente registro en el almacén de datos y ejecutar el contenido de el bloque <code>if</code> nuevamente. Si hay otro registro para iterar, esto hace que se inserte en la página, y luego se ejecuta <code>continue()</code> nuevamente, y así sucesivamente.</li> + <li>Cuando no hay más registros sobre los que iterar, <code>cursor</code> devolverá <code>undefined</code> y, por lo tanto, el bloque <code>else</code> se ejecutará en lugar del bloque <code>if</code>. Este bloque comprueba si se insertaron notas en el <code><ul></code>; de lo contrario, inserta un mensaje para indicar que no se almacenó ninguna nota.</li> +</ul> + +<h3 id="Eliminar_una_nota">Eliminar una nota</h3> + +<p>Como se indicó anteriormente, cuando se presiona el botón de eliminación de una nota, la nota se elimina. Esto se logra mediante la función <code>deleteItem()</code>, que se ve así:</p> + +<pre class="brush: js notranslate">// Define la función deleteItem() +function deleteItem(e) { + // recuperamos el nombre de la tarea que queremos eliminar. Necesitamos + // convertirla en un número antes de intentarla úselo con IDB; Clave del IDB + // los valores son sensibles al tipo. + let noteId = Number(e.target.parentNode.getAttribute('data-note-id')); + + // abre una transacción de base de datos y elimina la tarea, encontrándola usando la identificación que obtuvimos arriba + let transaction = db.transaction(['notes_os'], 'readwrite'); + let objectStore = transaction.objectStore('notes_os'); + let request = objectStore.delete(noteId); + + // informa que el elemento de datos ha sido eliminado + transaction.oncomplete = function() { + // elimina el padre del botón + // que es el elemento de la lista, por lo que ya no se muestra + e.target.parentNode.parentNode.removeChild(e.target.parentNode); + console.log('Nota ' + noteId + ' eliminada.'); + + // Nuevamente, si el elemento de la lista está vacío, muestra el mensaje 'No hay notas almacenadas' + if(!list.firstChild) { + let listItem = document.createElement('li'); + listItem.textContent = 'No hay notas almacenadas.'; + list.appendChild(listItem); + } + }; +}</pre> + +<ul> + <li>La primera parte de esto podría necesitar algo de explicación: recuperamos el ID del registro que se va a eliminar usando <code>Number(e.target.parentNode.getAttribute('data-note-id'))</code> — recuerda que el ID del registro se guardó en un atributo <code>data-note-id</code> en el <code><li></code> cuando se mostró por primera vez. Sin embargo, necesitamos pasar el atributo a través del objeto <code><a href="/es/docs/Web/JavaScript/Reference/Global_Objects/Number">Number()</a></code> integrado global ya que es de tipo cadena de datos y, por lo tanto, no sería reconocido por la base de datos, que espera un número.</li> + <li>Luego obtenemos una referencia al almacén de objetos usando el mismo patrón que hemos visto anteriormente, y usamos el método {{domxref("IDBObjectStore.delete()")}} para eliminar el registro de la base de datos, pasándole el ID.</li> + <li>Cuando se completa la transacción de la base de datos, eliminamos el <code><li></code> de la nota del DOM, y nuevamente hacemos la verificación para ver si el <code><ul></code> ahora está vacío, insertando un nota según corresponda.</li> +</ul> + +<p>¡Eso es todo!; Tu ejemplo debería funcionar ahora.</p> + +<p>Si tienes problemas con él, no dudes en <a href="https://mdn.github.io/learning-area/javascript/apis/client-side-storage/indexeddb/notes/">compararlo con nuestro ejemplo en vivo</a> (consulta el <a href="https://github.com/mdn/learning-area/blob/master/javascript/apis/client-side-storage/indexeddb/notes/index.js">código fuente</a> también).</p> + +<h3 id="Almacenamiento_de_datos_complejos_a_través_de_IndexedDB">Almacenamiento de datos complejos a través de <code>IndexedDB</code></h3> + +<p>Como mencionamos anteriormente, <code>IndexedDB</code> se puede usar para almacenar más que simples cadenas de texto. Puedes almacenar casi cualquier cosa que desees, incluidos objetos complejos como blobs de imágenes o vídeos. Y no es mucho más difícil de conseguir que cualquier otro tipo de dato.</p> + +<p>Para demostrar cómo hacerlo, hemos escrito otro ejemplo llamado <a href="https://github.com/mdn/learning-area/tree/master/javascript/apis/client-side-storage/indexeddb/video-store">almacenaje de videos con IndexedDB</a> (verlo <a href="https://mdn.github.io/learning-area/javascript/apis/client-side-storage/indexeddb/video-store/">en vivo aquí también</a>). Cuando ejecutas el ejemplo por primera vez, descarga todos los videos de la red, los almacena en una base de datos <code>IndexedDB</code> y luego muestra los videos en la IU dentro de los elementos {{htmlelement("video")}}. La segunda vez que lo ejecutas, encuentra los videos en la base de datos y los obtiene de allí antes de mostrarlos; esto hace que las cargas posteriores sean mucho más rápidas y menos necesitadas de ancho de banda.</p> + +<p>Repasemos las partes más interesantes del ejemplo. No lo veremos todo; gran parte es similar al ejemplo anterior y el código está bien comentado.</p> + +<ol> + <li> + <p>Para este ejemplo simple, hemos almacenado los nombres de los videos para buscarlos en un arreglo de objetos:</p> + + <pre class="brush: js notranslate">const videos = [ + { 'name' : 'crystal' }, + { 'name' : 'elf' }, + { 'name' : 'frog' }, + { 'name' : 'monster' }, + { 'name' : 'pig' }, + { 'name' : 'rabbit' } +];</pre> + </li> + <li> + <p>Para empezar, una vez que la base de datos se abre con éxito, ejecutamos una función <code>init()</code>. Esto recorre los diferentes nombres de video, tratando de cargar un registro identificado por cada nombre de la base de datos de <code>videos</code>.</p> + + <p>Si cada video se encuentra en la base de datos (se verifica fácilmente al ver si <code>request.result</code> se evalúa como <code>true</code>; si el registro no está presente, será <code>undefined</code>), sus archivos de video (almacenados como blobs) y el nombre del video se pasan directamente a la función <code>displayVideo()</code> para colocarlos en la interfaz de usuario. De lo contrario, el nombre del video se pasa a la función <code>fetchVideoFromNetwork()</code> para ... ¡adivinaste!: recupera el video de la red.</p> + + <pre class="brush: js notranslate">function init() { + // Recorre los nombres de los videos uno por uno + for(let i = 0; i < videos.length; i++) { + // Abre la transacción, obtiene objetos del almacén y get() cada video por nombre + let objectStore = db.transaction('videos_os').objectStore('videos_os'); + let request = objectStore.get(videos[i].name); + request.onsuccess = function() { + // Si el resultado existe en la base de datos (no está indefinido) + if(request.result) { + // Toma los videos del IDB y los muestra usando displayVideo() + console.log('tomando videos del IDB'); + displayVideo(request.result.mp4, request.result.webm, request.result.name); + } else { + // Recuperar los videos de la red + fetchVideoFromNetwork(videos[i]); + } + }; + } +}</pre> + </li> + <li> + <p>El siguiente fragmento se tomó del interior de <code>fetchVideoFromNetwork()</code> — aquí obtenemos las versiones MP4 y WebM del video usando dos peticiones {{domxref("fetch()", "WindowOrWorkerGlobalScope.fetch()")}}. Luego usamos el método {{domxref("blob()", "Body.blob()")}} para extraer el cuerpo de cada respuesta como un blob, dándonos una representación de objeto de los videos que se pueden almacenar y mostrar más adelante.</p> + + <p>Sin embargo, tenemos un problema aquí: estas dos solicitudes son asíncronas, pero solo queremos intentar mostrar o almacenar el video cuando ambas promesas se hayan cumplido. Afortunadamente, hay un método incorporado que maneja este problema: {{jsxref("Promise.all()")}}. Este toma un argumento, referencias a todas las promesas individuales que deseas verificar para su cumplimiento colocadas en un arreglo, y en sí mismo se basa en promesas.</p> + + <p>Cuando todas esas promesas se han cumplido, la promesa <code>all()</code> se cumple con un arreglo que contiene todos los valores de cumplimiento individuales. Dentro del bloque <code>all()</code>, puedes ver que luego llamamos a la función <code>displayVideo()</code> como lo hicimos antes para mostrar los videos en la interfaz de usuario, luego también llamamos a la función <code>storeVideo()</code> para almacenar esos videos dentro de la base de datos.</p> + + <pre class="brush: js notranslate">let mp4Blob = fetch('videos/' + video.name + '.mp4').then(response => + response.blob() +); +let webmBlob = fetch('videos/' + video.name + '.webm').then(response => + response.blob() +); + +// Ejecuta el siguiente código solo cuando se hayan cumplido ambas promesas +Promise.all([mp4Blob, webmBlob]).then(function(values) { + // muestra el video obtenido de la red con displayVideo() + displayVideo(values[0], values[1], video.name); + // lo almacena en el IDB usando storeVideo() + storeVideo(values[0], values[1], video.name); +});</pre> + </li> + <li> + <p>Veamos primero <code>storeVideo()</code>. Esto es muy similar al patrón que viste en el ejemplo anterior para agregar datos a la base de datos: abrimos una transacción <code>readwrite</code> y obtenemos una referencia a nuestro almacén de objetos <code>videos_os</code>, creamos un objeto que representa el registro para agregar a la base de datos, luego simplemente lo agrega usando {{domxref("IDBObjectStore.add()")}}.</p> + + <pre class="brush: js notranslate">función storeVideo(mp4Blob, webmBlob, nombre) { + // Abre transacción, obtiene el almacén de objetos; lo convierte en lectura y escritura para que podamos escribir en el IDB + let objectStore = db.transaction(['videos_os'], 'readwrite').objectStore('videos_os'); + // Crea un registro para agregar al IDB + let record = { + mp4 : mp4Blob, + webm : webmBlob, + name : name + } + + // Agrega el registro al IDB usando add() + let request = objectStore.add(record); + + ... + +};</pre> + </li> + <li> + <p>Por último, pero no menos importante, tenemos <code>displayVideo()</code>, que crea los elementos DOM necesarios para insertar el video en la interfaz de usuario y luego los agrega a la página. Las partes más interesantes de esto son las que se muestran a continuación: para mostrar realmente nuestros blobs de video en un elemento <code><video></code>, necesitamos crear URL de objeto (URL internas que apuntan a los blobs de video almacenados en la memoria) utilizando el método {{domxref("URL.createObjectURL()")}}. Una vez hecho esto, podemos configurar las URL del objeto para que sean los valores de los atributos <code>src</code> de nuestro elemento {{htmlelement("source")}}, y funciona bien.</p> + + <pre class="brush: js notranslate">function displayVideo(mp4Blob, webmBlob, title) { + // Crea URL del objeto a partir de blobs + let mp4URL = URL.createObjectURL(mp4Blob); + let webmURL = URL.createObjectURL(webmBlob); + + ... + + const video = document.createElement('video'); + video.controls = true; + const source1 = document.createElement('source'); + source1.src = mp4URL; + source1.type = 'video/mp4'; + const source2 = document.createElement('source'); + source2.src = webmURL; + source2.type = 'video/webm'; + + ... +}</pre> + </li> +</ol> + +<h2 id="Almacenamiento_de_activos_sin_conexión">Almacenamiento de activos sin conexión</h2> + +<p>El ejemplo anterior ya muestra cómo crear una aplicación que almacenará grandes activos en una base de datos <code>IndexedDB</code>, evitando la necesidad de descargarlos más de una vez. Esto ya es una gran mejora para la experiencia del usuario, pero todavía falta una cosa: los archivos HTML, CSS y JavaScript principales aún se deben descargar cada vez que se accede al sitio, lo cual significa que no funcionará cuando no haya conexión de red.</p> + +<p><img alt="Fuera de línea" src="https://mdn.mozillademos.org/files/15759/ff-offline.png" style="border-style: solid; border-width: 1px; display: block; height: 307px; margin: 0px auto; width: 765px;"></p> + +<p>Aquí es donde entran el {{web.link("/es/docs/Web/API/Service_Worker_API", "servicio workers")}} y la {{web.link("/es/docs/Web/API/Cache", "API de caché")}}.</p> + +<p>Un servicio <em>worker</em> es un archivo JavaScript que, en pocas palabras, se registra con un origen en particular (sitio web o parte de un sitio web en un determinado dominio) cuando se accede a él mediante un navegador. Cuando se registra, puede controlar las páginas disponibles en ese origen. Para ello, se sienta entre una página cargada y la red e intercepta las solicitudes de red dirigidas a ese origen.</p> + +<p>Cuando intercepta una solicitud, puede hacer lo que desees (consulta {{web.link("/es/docs/Web/API/Service_Worker_API#Other_use_case_ideas", "ideas de casos de uso")}}), pero el ejemplo clásico es guardar las respuestas de la red fuera de línea y luego proporcionarlas en respuesta a una solicitud en lugar de las respuestas de la red. De hecho, te permite hacer que un sitio web funcione completamente fuera de línea.</p> + +<p>La API de caché es otro mecanismo de almacenamiento del lado del cliente, con una pequeña diferencia: está diseñada para guardar respuestas HTTP y, por lo tanto, funciona muy bien con el servicio <em>workers</em>.</p> + +<div class="note"> +<p><strong>Nota</strong>: El servicio <em>workers</em> y la memoria caché ahora son compatibles con la mayoría de los navegadores modernos. Al momento de escribir este artículo, Safari todavía estaba ocupado implementándolo, pero debería estar allí pronto.</p> +</div> + +<h3 id="Un_ejemplo_del_servicio_worker">Un ejemplo del servicio <em>worker</em></h3> + +<p>Veamos un ejemplo para darte una idea de cómo se vería esto. Hemos creado otra versión del ejemplo del almacén de videos que vimos en la sección anterior; este funciona de manera idéntica, excepto que también guarda HTML, CSS y JavaScript en la API de caché a través de un servicio <em>worker</em>, lo que permite que el ejemplo se ejecute sin conexión.</p> + +<p>Ve <a href="https://mdn.github.io/learning-area/javascript/apis/client-side-storage/cache-sw/video-store-offline/">almacén de videos IndexedDB con servicio worker funcionando en vivo</a> y también <a href="https://github.com/mdn/learning-area/tree/master/javascript/apis/client-side-storage/cache-sw/video-store-offline">ve el código fuente</a>.</p> + +<h4 id="Registrar_el_servicio_worker">Registrar el servicio <em>worker</em></h4> + +<p>Lo primero que hay que tener en cuenta es que hay un fragmento adicional de código colocado en el archivo JavaScript principal (consulta <a href="https://github.com/mdn/learning-area/blob/master/javascript/apis/client-side-storage/cache-sw/video-store-offline/index.js">index.js</a>). Primero hacemos una prueba de detección de características para ver si el miembro <code>serviceWorker</code> está disponible en el objeto {{domxref("Navigator")}}. Si esto devuelve <code>true</code>, entonces sabemos que al menos se respaldan los conceptos básicos del servicio <em>workers</em>. Aquí adentro usamos el método {{domxref("ServiceWorkerContainer.register )")}} para registrar un servicio <em>worker</em> contenido en el archivo <code>sw.js</code> contra el origen en el que reside, para que pueda controlar páginas en el mismo directorio que él, o subdirectorios. Cuando se cumple su promesa, el trabajador del servicio se considera registrado.</p> + +<pre class="brush: js notranslate"> // Registrar el servicio workers para controlar que el sitio funcione sin conexión + + if('serviceWorker' in navigator) { + navigator.serviceWorker + .register('/learning-area/javascript/apis/client-side-storage/cache-sw/video-store-offline/sw.js') + .then(function() { console.log('Servicio Worker Registrado'); }); + }</pre> + +<div class="note"> +<p><strong>Nota</strong>: La ruta proporcionada al archivo <code>sw.js</code> es relativa al origen del sitio, no al archivo JavaScript que contiene el código. El servicio <em>worker</em> está en <code>https://mdn.github.io/learning-area/javascript/apis/client-side-storage/cache-sw/video-store-offline/sw.js</code>. El origen es <code>https://mdn.github.io</code> y, por lo tanto, la ruta dada debe ser <code>/learning-area/javascript/apis/client-side-storage/cache-sw/video-store-offline/sw.js</code>. Si quisieras alojar este ejemplo en tu propio servidor, tendrías que cambiarlo consecuentemente. Esto es bastante confuso, pero tiene que funcionar de esta manera por razones de seguridad.</p> +</div> + +<h4 id="Instalación_del_servicio_worker">Instalación del servicio <em>worker</em></h4> + +<p>La próxima vez que se accede a cualquier página bajo el control del servicio <em>worker</em> (por ejemplo, cuando se vuelve a cargar el ejemplo), el servicio <em>worker</em> se instala en esa página, lo cual significa que comenzará a controlarla. Cuando esto ocurre, se dispara un evento <code>install</code> contra el servicio <em>worker</em>; puedes escribir código dentro del propio servicio <em>worker</em> que responderá a la instalación.</p> + +<p>Veamos un ejemplo, en el archivo <a href="https://github.com/mdn/learning-area/blob/master/javascript/apis/client-side-storage/cache-sw/video-store-offline/sw.js">sw.js</a> (el servicio <em>worker</em>). Verás que el detector de instalación está registrado en <code>self</code>. Esta palabra clave <code>self</code> es una forma de hacer referencia al alcance global del servicio <em>worker</em> desde el interior del archivo del servicio <em>worker</em>.</p> + +<p>Dentro del controlador <code>install</code> usamos el método {{domxref("ExtendableEvent.waitUntil()")}}, disponible en el objeto <code>event</code>, para indicar que el navegador no debe completar la instalación del servicio <em>worker</em> hasta que la promesa interior se haya cumplido con éxito.</p> + +<p>Aquí es donde vemos en acción la API de <code>Cache</code>. Usamos el método {{domxref("CacheStorage.open()")}} para abrir un nuevo objeto <code>Cache</code> en el que se pueden almacenar las respuestas (similar a un almacén de objetos <code>IndexedDB</code>). Esta promesa se cumple con un objeto {{domxref("Cache")}} que representa la caché de <code>video-store</code>. Luego usamos el método {{domxref("Cache.addAll()")}} para obtener una serie de activos y agregar sus respuestas a la caché.</p> + +<pre class="brush: js notranslate">self.addEventListener('install', function(e) { + e.waitUntil( + caches.open('video-store').then(function(cache) { + return cache.addAll([ + '/learning-area/javascript/apis/client-side-storage/cache-sw/video-store-offline/', + '/learning-area/javascript/apis/client-side-storage/cache-sw/video-store-offline/index.html', + '/learning-area/javascript/apis/client-side-storage/cache-sw/video-store-offline/index.js', + '/learning-area/javascript/apis/client-side-storage/cache-sw/video-store-offline/style.css' + ]); + }) + ); +});</pre> + +<p>Eso es todo por ahora, instalación terminada.</p> + +<h4 id="Responder_a_más_solicitudes">Responder a más solicitudes</h4> + +<p>Con el servicio <em>worker</em> registrado e instalado en nuestra página HTML, y todos los activos relevantes agregados a nuestra caché, estamos casi listos para comenzar. Solo queda una cosa más por hacer, escribir código para responder a más solicitudes de red.</p> + +<p>Esto es lo que hace el segundo bit de código en <code>sw.js</code>. Agregamos otro escucha al ámbito global del servicio <em>worker</em>, que ejecuta la función del controlador cuando se genera el evento <code>fetch</code>. Esto sucede cada vez que el navegador solicita un activo en el directorio en el que está registrado el servicio <em>worker</em>.</p> + +<p>Dentro del controlador, primero registramos la URL del activo solicitado. Luego proporcionamos una respuesta personalizada a la solicitud, utilizando el método {{domxref("FetchEvent.respondWith()")}}.</p> + +<p>Dentro de este bloque usamos {{domxref("CacheStorage.match()")}} para verificar si una solicitud coincidente (es decir, coincide con la URL) se puede encontrar en cualquier caché. Esta promesa se cumple con la respuesta coincidente si se encuentra una coincidencia, o <code>undefined</code> si no lo es.</p> + +<p>Si se encuentra una coincidencia, simplemente la devolvemos como la respuesta personalizada. De lo contrario, {{web.link("/es/docs/Web/API/WindowOrWorkerGlobalScope/fetch", "fetch()")}} la respuesta de la red y la devolvemos en su lugar.</p> + +<pre class="brush: js notranslate">self.addEventListener('fetch', function(e) { + console.log(e.request.url); + e.respondWith( + caches.match(e.request).then(function(response) { + return response || fetch(e.request); + }) + ); +});</pre> + +<p>Y eso es todo para nuestro sencillo servicio <em>worker</em>. Hay muchas más cosas que puedes hacer con ellos; para obtener más detalles, consulta el <a href="https://serviceworke.rs/">libro de recetas para el servicio <em>worker</em></a>. Y gracias a Paul Kinlan por su artículo <a href="https://developers.google.com/web/fundamentals/codelabs/offline/">Agregar un servicio <em>worker</em> y sin conexión a tu aplicación web</a>, que inspiró este sencillo ejemplo.</p> + +<h4 id="Probando_el_ejemplo_sin_conexión">Probando el ejemplo sin conexión</h4> + +<p>Para probar nuestro <a href="https://mdn.github.io/learning-area/javascript/apis/client-side-storage/cache-sw/video-store-offline/">ejemplo de servicio <em>worker</em></a>, deberás cargarlo un par de veces para asegurarte de que esté instalado. Una vez hecho esto, puedes:</p> + +<ul> + <li>Intenta desconectar tu red/apagar tu <em>Wifi</em>.</li> + <li>Selecciona <em>Archivo → Trabajar sin conexión</em> si estás usando Firefox.</li> + <li>Ve a <em>devtools</em>, luego elige <em>Aplicación → Servicio worker</em>, luego marca la casilla de verificación <em>Sin conexión</em> si estás usando Chrome.</li> +</ul> + +<p>Si actualizas tu página de ejemplo nuevamente, deberías ver que se carga bien. Todo se almacena sin conexión: los activos de la página en una caché y los videos en una base de datos <code>IndexedDB</code>.</p> + +<h2 id="Resumen">Resumen</h2> + +<p>Eso es todo por ahora. Esperamos que hayas encontrado útil nuestro resumen de las tecnologías de almacenamiento de lado del cliente.</p> + +<h2 id="Ve_también">Ve también</h2> + +<ul> + <li>{{web.link("/es/docs/Web/API/Web_Storage_API", "API de almacenamiento Web")}}</li> + <li>{{web.link("/es/docs/Web/API/IndexedDB_API", "API IndexedDB")}}</li> + <li>{{web.link("/es/docs/Web/HTTP/Cookies", "Cookies")}}</li> + <li>{{web.link("/es/docs/Web/API/Service_Worker_API", "API del servicio worker")}}</li> +</ul> + +<p>{{PreviousMenu("Learn/JavaScript/Client-side_web_APIs/Video_and_audio_APIs", "Learn/JavaScript/Client-side_web_APIs")}}</p> + +<h2 id="En_este_módulo">En este módulo</h2> + +<ul> + <li>{{web.link("/es/docs/Learn/JavaScript/Client-side_web_APIs/Introduction", "Introducción a las APIs web")}}</li> + <li>{{web.link("/es/docs/Learn/JavaScript/Client-side_web_APIs/Manipulating_documents", "Manipulación de documentos")}}</li> + <li>{{web.link("/es/docs/Learn/JavaScript/Client-side_web_APIs/Fetching_data", "Obtener datos del servidor")}}</li> + <li>{{web.link("/es/docs/Learn/JavaScript/Client-side_web_APIs/Third_party_APIs", "API de terceros")}}</li> + <li>{{web.link("/es/docs/Learn/JavaScript/Client-side_web_APIs/Drawing_graphics", "Dibujar gráficos")}}</li> + <li>{{web.link("/es/docs/Learn/JavaScript/Client-side_web_APIs/Video_and_audio_APIs", "APIs de video y audio")}}</li> + <li>{{web.link("/es/docs/Learn/JavaScript/Client-side_web_APIs/Client-side_storage", "Almacenamiento de lado del cliente")}}</li> +</ul> diff --git a/files/es/learn/javascript/client-side_web_apis/fetching_data/index.html b/files/es/learn/javascript/client-side_web_apis/fetching_data/index.html new file mode 100644 index 0000000000..ab34b8c319 --- /dev/null +++ b/files/es/learn/javascript/client-side_web_apis/fetching_data/index.html @@ -0,0 +1,373 @@ +--- +title: Fetching data from the server +slug: Learn/JavaScript/Client-side_web_APIs/Fetching_data +translation_of: Learn/JavaScript/Client-side_web_APIs/Fetching_data +--- +<div>{{LearnSidebar}}</div> + +<div>{{PreviousMenuNext("Learn/JavaScript/Client-side_web_APIs/Manipulating_documents", "Learn/JavaScript/Client-side_web_APIs/Third_party_APIs", "Learn/JavaScript/Client-side_web_APIs")}}</div> + +<p class="summary">Otra tarea muy común en páginas web y en aplicaciones es tomar elementos individuales de datos desde el servidor para actualizar secciones de la página web sin tener que cargar toda una nueva página. Este aparentemente pequeño detalle tiene un gran impacto en el desempeño y comportamiento de los sitios, por eso en este artículo, explicaremos el concepto y veremos las tecnologías que hacen esto posible, como ser XHLHttpRequest y FetchAPI. </p> + +<table class="learn-box standard-table"> + <tbody> + <tr> + <th scope="row">Prerequisitos:</th> + <td>JavaScript básico (ver <a href="/en-US/docs/Learn/JavaScript/First_steps">first steps</a>, <a href="/en-US/docs/Learn/JavaScript/Building_blocks">building blocks</a>, <a href="/en-US/docs/Learn/JavaScript/Objects">JavaScript objects</a>), <a href="/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Introduction">basics of Client-side APIs</a></td> + </tr> + <tr> + <th scope="row">Objetivo:</th> + <td>Aprender como extraer datos desde el servidor y usarlo para cargar contenido en la página web. </td> + </tr> + </tbody> +</table> + +<h2 id="Cúal_es_el_problema_aquí">Cúal es el problema aquí?</h2> + +<p>Originalmente cargar páginas en la web era simple — tu enviabas una solicitud de la página web al servidor, y si no había ningún problema, los servicios encargados de la página web la descargaban y mostraban en tu computadora.</p> + +<p><img alt="A basic representation of a web site architecture" src="https://mdn.mozillademos.org/files/6475/web-site-architechture@2x.png" style="display: block; height: 134px; margin: 0px auto; width: 484px;"></p> + +<p>El problema con este modelo es que si tu quieres actualizar cualquier parte de la página, por ejemplo, mostrar el nuevo set de productos o cargar una nueva página, tu tenías que cargar toda la página de nuevo. Esto es extremadamente un desperdicio y resultaba ser una experiencia pobre al usuario, especialmente cuando la página es más grande y más compleja. </p> + +<h3 id="Introduciendo_Ajax">Introduciendo Ajax</h3> + +<p>This led to the creation of technologies that allow web pages to request small chunks of data (such as <a href="/en-US/docs/Web/HTML">HTML</a>, {{glossary("XML")}}, <a href="/en-US/docs/Learn/JavaScript/Objects/JSON">JSON</a>, or plain text) and display them only when needed, helping to solve the problem described above.</p> + +<p>This is achieved by using APIs like {{domxref("XMLHttpRequest")}} or — more recently — the <a href="/en-US/docs/Web/API/Fetch_API">Fetch API</a>. These technologies allow web pages to directly handle making <a href="/en-US/docs/Web/HTTP">HTTP</a> requests for specific resources available on a server and formatting the resulting data as needed before it is displayed.</p> + +<div class="note"> +<p><strong>Note</strong>: In the early days, this general technique was known as <a href="https://developer.mozilla.org/en-US/docs/Glossary/Asynchronous">Asynchronous</a> JavaScript and XML (<a href="https://developer.mozilla.org/en-US/docs/Glossary/Ajax">Ajax</a>), because it tended to use {{domxref("XMLHttpRequest")}} to request XML data. This is normally not the case these days (you'd be more likely to use <code>XMLHttpRequest</code> or Fetch to request JSON), but the result is still the same, and the term "Ajax" is still often used to describe the technique.</p> +</div> + +<p><img alt="A simple modern architecture for web sites" src="https://mdn.mozillademos.org/files/6477/moderne-web-site-architechture@2x.png" style="display: block; height: 235px; margin: 0px auto; width: 559px;"></p> + +<p>The Ajax model involves using a web API as a proxy to more intelligently request data rather than just having the browser reload the entire page. Let's think about the significance of this:</p> + +<ol> + <li>Go to one of your favorite information-rich sites, like Amazon, YouTube, CNN, etc., and load it.</li> + <li>Now search for something, like a new product. The main content will change, but most of the surrounding information, like the header, footer, navigation menu, etc., will stay the same.</li> +</ol> + +<p>This is a really good thing because:</p> + +<ul> + <li>Page updates are a lot quicker and you don't have to wait for the page to refresh, meaning that the site feels faster and more responsive.</li> + <li>Less data is downloaded on each update, meaning less wasted bandwidth. This may not be such a big issue on a desktop on a broadband connection, but it's a major issue on mobile devices and in developing countries that don't have ubiquitous fast Internet service.</li> +</ul> + +<p>To speed things up even further, some sites also store assets and data on the user's computer when they are first requested, meaning that on subsequent visits they use the local versions instead of downloading fresh copies when the page is first loaded. The content is only reloaded from the server when it has been updated.</p> + +<p><img alt="A basic web app data flow architecture" src="https://mdn.mozillademos.org/files/6479/web-app-architecture@2x.png" style="display: block; height: 383px; margin: 0px auto; width: 562px;"></p> + +<h2 id="A_basic_Ajax_request">A basic Ajax request</h2> + +<p>Let's look at how such a request is handled, using both {{domxref("XMLHttpRequest")}} and <a href="/en-US/docs/Web/API/Fetch_API">Fetch</a>. For these examples, we'll request data out of a few different text files and use them to populate a content area.</p> + +<p>This series of files will act as our fake database; in a real application, we'd be more likely to use a server-side language like PHP, Python, or Node to request our data from a database. Here, however, we want to keep it simple and concentrate on the client-side part of this.</p> + +<h3 id="XMLHttpRequest">XMLHttpRequest</h3> + +<p><code>XMLHttpRequest</code> (which is frequently abbreviated to XHR) is a fairly old technology now — it was invented by Microsoft in the late '90s, and has been standardized across browsers for quite a long time.</p> + +<ol> + <li> + <p>To begin this example, make a local copy of <a href="https://github.com/mdn/learning-area/blob/master/javascript/apis/fetching-data/ajax-start.html">ajax-start.html</a> and the four text files — <a href="https://github.com/mdn/learning-area/blob/master/javascript/apis/fetching-data/verse1.txt">verse1.txt</a>, <a href="https://github.com/mdn/learning-area/blob/master/javascript/apis/fetching-data/verse2.txt">verse2.txt</a>, <a href="https://github.com/mdn/learning-area/blob/master/javascript/apis/fetching-data/verse3.txt">verse3.txt</a>, and <a href="https://github.com/mdn/learning-area/blob/master/javascript/apis/fetching-data/verse4.txt">verse4.txt</a> — in a new directory on your computer. In this example, we will load a different verse of the poem (which you may well recognize) via XHR when it's selected in the drop-down menu.</p> + </li> + <li> + <p>Just inside the {{htmlelement("script")}} element, add the following code. This stores a reference to the {{htmlelement("select")}} and {{htmlelement("pre")}} elements in variables and defines an {{domxref("GlobalEventHandlers.onchange","onchange")}} event handler function so that when the select's value is changed, its value is passed to an invoked function <code>updateDisplay()</code> as a parameter.</p> + + <pre class="brush: js">var verseChoose = document.querySelector('select'); +var poemDisplay = document.querySelector('pre'); + +verseChoose.onchange = function() { + var verse = verseChoose.value; + updateDisplay(verse); +};</pre> + </li> + <li> + <p>Let's define our <code>updateDisplay()</code> function. First of all, put the following beneath your previous code block — this is the empty shell of the function:</p> + + <pre class="brush: js">function updateDisplay(verse) { + +};</pre> + </li> + <li> + <p>We'll start our function by constructing a relative URL pointing to the text file we want to load, as we'll need it later. The value of the {{htmlelement("select")}} element at any time is the same as the text inside the selected {{htmlelement("option")}} (unless you specify a different value in a value attribute) — so for example "Verse 1". The corresponding verse text file is "verse1.txt", and is in the same directory as the HTML file, therefore just the file name will do.</p> + + <p>However, web servers tend to be case sensitive, and the file name doesn't have a space in it. To convert "Verse 1" to "verse1.txt" we need to convert the V to lower case, remove the space, and add .txt on the end. This can be done with {{jsxref("String.replace", "replace()")}}, {{jsxref("String.toLowerCase", "toLowerCase()")}}, and simple <a href="/en-US/docs/Learn/JavaScript/First_steps/Strings#Concatenating_strings">string concatenation</a>. Add the following lines inside your <code>updateDisplay()</code> function:</p> + + <pre class="brush: js">verse = verse.replace(" ", ""); +verse = verse.toLowerCase(); +var url = verse + '.txt';</pre> + </li> + <li> + <p>To begin creating an XHR request, you need to create a new request object using the {{domxref("XMLHttpRequest.XMLHttpRequest", "XMLHttpRequest()")}} constructor. You can call this object anything you like, but we'll call it <code>request</code> to keep things simple. Add the following below your previous lines:</p> + + <pre class="brush: js">var request = new XMLHttpRequest();</pre> + </li> + <li> + <p>Next, you need to use the {{domxref("XMLHttpRequest.open","open()")}} method to specify what <a href="/en-US/docs/Web/HTTP/Methods">HTTP request method</a> to use to request the resource from the network, and what its URL is. We'll just use the <code><a href="/en-US/docs/Web/HTTP/Methods/GET">GET</a></code> method here and set the URL as our <code>url</code> variable. Add this below your previous line:</p> + + <pre class="brush: js">request.open('GET', url);</pre> + </li> + <li> + <p>Next, we'll set the type of response we are expecting — which is defined by the request's {{domxref("XMLHttpRequest.responseType", "responseType")}} property — as <code>text</code>. This isn't strictly necessary here — XHR returns text by default — but it is a good idea to get into the habit of setting this in case you want to fetch other types of data in the future. Add this next:</p> + + <pre class="brush: js">request.responseType = 'text';</pre> + </li> + <li> + <p>Fetching a resource from the network is an {{glossary("asynchronous")}} operation, meaning that you have to wait for that operation to complete (e.g., the resource is returned from the network) before you can do anything with that response, otherwise, an error will be thrown. XHR allows you to handle this using its {{domxref("XMLHttpRequest.onload", "onload")}} event handler — this is run when the {{event("load")}} event fires (when the response has returned). When this has occurred, the response data will be available in the <code>response</code> property of the XHR request object.</p> + + <p>Add the following below your last addition. You'll see that inside the <code>onload</code> event handler we are setting the <code><a href="/en-US/docs/Web/API/Node/textContent">textContent</a></code> of the <code>poemDisplay</code> (the {{htmlelement("pre")}} element) to the value of the {{domxref("XMLHttpRequest.response", "request.response")}} property.</p> + + <pre class="brush: js">request.onload = function() { + poemDisplay.textContent = request.response; +};</pre> + </li> + <li> + <p>The above is all set up for the XHR request — it won't actually run until we tell it to, which is done using the {{domxref("XMLHttpRequest.send","send()")}} method. Add the following below your previous addition to complete the function:</p> + + <pre class="brush: js">request.send();</pre> + </li> + <li> + <p>One problem with the example as it stands is that it won't show any of the poem when it first loads. To fix this, add the following two lines at the bottom of your code (just above the closing <code></script></code> tag) to load verse 1 by default, and make sure the {{htmlelement("select")}} element always shows the correct value:</p> + + <pre class="brush: js">updateDisplay('Verse 1'); +verseChoose.value = 'Verse 1';</pre> + </li> +</ol> + +<h3 id="Serving_your_example_from_a_server">Serving your example from a server</h3> + +<p>Some browsers (including Chrome) will not run XHR requests if you just run the example from a local file. This is because of security restrictions (for more on web security, read <a href="/en-US/docs/Learn/Server-side/First_steps/Website_security">Website security</a>).</p> + +<p>To get around this, we need to test the example by running it through a local web server. To find out how to do this, read <a href="/en-US/docs/Learn/Common_questions/set_up_a_local_testing_server">How do you set up a local testing server?</a></p> + +<h3 id="Fetch">Fetch</h3> + +<p>The Fetch API is basically a modern replacement for XHR; it was introduced in browsers recently to make asynchronous HTTP requests easier to do in JavaScript, both for developers and other APIs that build on top of Fetch.</p> + +<p>Let's convert the last example to use Fetch instead.</p> + +<ol> + <li> + <p>Make a copy of your previous finished example directory. (If you didn't work through the previous exercise, create a new directory and inside it make copies of <a href="https://github.com/mdn/learning-area/blob/master/javascript/apis/fetching-data/xhr-basic.html">xhr-basic.html</a> and the four text files — <a href="https://github.com/mdn/learning-area/blob/master/javascript/apis/fetching-data/verse1.txt">verse1.txt</a>, <a href="https://github.com/mdn/learning-area/blob/master/javascript/apis/fetching-data/verse2.txt">verse2.txt</a>, <a href="https://github.com/mdn/learning-area/blob/master/javascript/apis/fetching-data/verse3.txt">verse3.txt</a>, and <a href="https://github.com/mdn/learning-area/blob/master/javascript/apis/fetching-data/verse4.txt">verse4.txt</a>.)</p> + </li> + <li> + <p>Inside the <code>updateDisplay()</code> function, find the XHR code:</p> + + <pre class="brush: js">var request = new XMLHttpRequest(); +request.open('GET', url); +request.responseType = 'text'; + +request.onload = function() { + poemDisplay.textContent = request.response; +}; + +request.send();</pre> + </li> + <li> + <p>Replace all the XHR code with this:</p> + + <pre class="brush: js">fetch(url).then(function(response) { + response.text().then(function(text) { + poemDisplay.textContent = text; + }); +});</pre> + </li> + <li> + <p>Load the example in your browser (running it through a web server) and it should work just the same as the XHR version, provided you are running a modern browser.</p> + </li> +</ol> + +<h4 id="So_what_is_going_on_in_the_Fetch_code">So what is going on in the Fetch code?</h4> + +<p>First of all, we invoke the {{domxref("WorkerOrWindowGlobalScope.fetch()","fetch()")}} method, passing it the URL of the resource we want to fetch. This is the modern equivalent of {{domxref("XMLHttpRequest.open","request.open()")}} in XHR, plus you don't need any equivalent to <code>.send()</code>.</p> + +<p>After that, you can see the {{jsxref("Promise.then",".then()")}} method chained onto the end of <code>fetch()</code> — this method is a part of {{jsxref("Promise","Promises")}}, a modern JavaScript feature for performing asynchronous operations. <code>fetch()</code> returns a <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">promise</a>, which resolves to the response sent back from the server — we use <code>.then()</code> to run some follow-up code after the promise resolves, which is the function we've defined inside it. This is the equivalent of the <code>onload</code> event handler in the XHR version.</p> + +<p>This function is automatically given the response from the server as a parameter when the <code>fetch()</code> promise resolves. Inside the function we grab the response and run its {{domxref("Body.text","text()")}} method, which basically returns the response as raw text. This is the equivalent of <code>request.responseType = 'text'</code> in the XHR version.</p> + +<p>You'll see that <code>text()</code> also returns a promise, so we chain another <code>.then()</code> onto it, inside of which we define a function to receive the raw text that the <code>text()</code> promise resolves to.</p> + +<p>Inside the inner promise's function, we do much the same as we did in the XHR version — set the {{htmlelement("pre")}} element's text content to the text value.</p> + +<h3 id="Aside_on_promises">Aside on promises</h3> + +<p>Promises are a bit confusing the first time you meet them, but don't worry too much about this for now. You'll get used to them after a while, especially as you learn more about modern JavaScript APIs — most of the newer ones are heavily based on promises.</p> + +<p>Let's look at the promise structure from above again to see if we can make some more sense of it:</p> + +<pre class="brush: js">fetch(url).then(function(response) { + response.text().then(function(text) { + poemDisplay.textContent = text; + }); +});</pre> + +<p>The first line is saying "fetch the resource located at URL" (<code>fetch(url)</code>) and "then run the specified function when the promise resolves" (<code>.then(function() { ... })</code>). "Resolve" means "finish performing the specified operation at some point in the future". The specified operation, in this case, is to fetch a resource from a specified URL (using an HTTP request), and return the response for us to do something with.</p> + +<p>Effectively, the function passed into <code>then()</code> is a chunk of code that won't run immediately. Instead, it will run at some point in the future when the response has been returned. Note that you could also choose to store your promise in a variable and chain {{jsxref("Promise.then",".then()")}} onto that instead. The code below would do the same thing:</p> + +<pre class="brush: js">var myFetch = fetch(url); + +myFetch.then(function(response) { + response.text().then(function(text) { + poemDisplay.textContent = text; + }); +});</pre> + +<p>Because the <code>fetch()</code> method returns a promise that resolves to the HTTP response, any function you define inside a <code>.then()</code> chained onto the end of it will automatically be given the response as a parameter. You can call the parameter anything you like — the below example would still work:</p> + +<pre class="brush: js">fetch(url).then(function(dogBiscuits) { + dogBiscuits.text().then(function(text) { + poemDisplay.textContent = text; + }); +});</pre> + +<p>But it makes more sense to call the parameter something that describes its contents.</p> + +<p>Now let's focus just on the function:</p> + +<pre class="brush: js">function(response) { + response.text().then(function(text) { + poemDisplay.textContent = text; + }); +}</pre> + +<p>The response object has a method {{domxref("Body.text","text()")}} that takes the raw data contained in the response body and turns it into plain text — the format we want it in. It also returns a promise (which resolves to the resulting text string), so here we use another {{jsxref("Promise.then",".then()")}}, inside of which we define another function that dictates what we want to do with that text string. We are just setting the <code><a href="/en-US/docs/Web/API/Node/textContent">textContent</a></code> property of our poem's {{htmlelement("pre")}} element to equal the text string, so this works out pretty simple.</p> + +<p>It is also worth noting that you can directly chain multiple promise blocks (<code>.then()</code> blocks, but there are other types too) onto the end of one another, passing the result of each block to the next block as you travel down the chain. This makes promises very powerful.</p> + +<p>The following block does the same thing as our original example, but is written in a different style:</p> + +<pre class="brush: js">fetch(url).then(function(response) { + return response.text() +}).then(function(text) { + poemDisplay.textContent = text; +});</pre> + +<p>Many developers like this style better, as it is flatter and arguably easier to read for longer promise chains — each subsequent promise comes after the previous one, rather than being inside the previous one (which can get unwieldy). The only other difference is that we've had to include a <code><a href="/en-US/docs/Learn/JavaScript/Building_blocks/Return_values">return</a></code> statement in front of <code>response.text()</code>, to get it to pass its result on to the next link in the chain.</p> + +<h3 id="Which_mechanism_should_you_use">Which mechanism should you use?</h3> + +<p>This really depends on what project you are working on. XHR has been around for a long time now and has very good cross-browser support. Fetch and Promises, on the other hand, are a more recent addition to the web platform, although they're supported well across the browser landscape, with the exception of Internet Explorer.</p> + +<p>If you need to support older browsers, then an XHR solution might be preferable. If however you are working on a more progressive project and aren't as worried about older browsers, then Fetch could be a good choice.</p> + +<p>You should really learn both — Fetch will become more popular as Internet Explorer declines in usage (IE is no longer being developed, in favor of Microsoft's new Edge browser), but you might need XHR for a while yet.</p> + +<h2 id="A_more_complex_example">A more complex example</h2> + +<p>To round off the article, we'll look at a slightly more complex example that shows some more interesting uses of Fetch. We have created a sample site called The Can Store — it's a fictional supermarket that only sells canned goods. You can find this <a href="https://mdn.github.io/learning-area/javascript/apis/fetching-data/can-store/">example live on GitHub</a>, and <a href="https://github.com/mdn/learning-area/tree/master/javascript/apis/fetching-data/can-store">see the source code</a>.</p> + +<p><img alt="A fake ecommerce site showing search options in the left hand column, and product search results in the right hand column." src="https://mdn.mozillademos.org/files/14779/can-store.png" style="display: block; margin: 0 auto;"></p> + +<p>By default, the site displays all the products, but you can use the form controls in the left hand column to filter them by category, or search term, or both.</p> + +<p>There is quite a lot of complex code that deals with filtering the products by category and search terms, manipulating strings so the data displays correctly in the UI, etc. We won't discuss all of it in the article, but you can find extensive comments in the code (see <a href="https://github.com/mdn/learning-area/blob/master/javascript/apis/fetching-data/can-store/can-script.js">can-script.js</a>).</p> + +<p>We will however explain the Fetch code.</p> + +<p>The first block that uses Fetch can be found at the start of the JavaScript:</p> + +<pre class="brush: js">fetch('products.json').then(function(response) { + return response.json(); +}).then(function(json) { + products = json; + initialize(); +}).catch(function(err) { + console.log('Fetch problem: ' + err.message); +});</pre> + +<p>The <code>fetch()</code> function returns a <code>promise</code>. If this completes successfully, the function inside the first <code>.then()</code> block contains the <code>response</code> returned from the network.</p> + +<p>Inside this function we run {{domxref("Body.json","json()")}} on the response, not {{domxref("Body.text","text()")}}, as we want to return our response as structured JSON data, not plain text.</p> + +<p>Next, we chain another <code>.then()</code> onto the end of our first one, the success function that contains the <code>json</code> returned from the <code>response.json()</code> promise. We set this to be the value of the products global object, then run <code>initialize()</code>, which starts the process of displaying all the products in the user interface.</p> + +<p>To handle errors, we chain a <code>.catch()</code> block onto the end of the chain. This runs if the promise fails for some reason. Inside it, we include a function that is passed as a parameter, an <code>error</code> object. This <code>error</code> object can be used to report the nature of the error that has occurred, in this case we do it with a simple <code>console.log()</code>.</p> + +<p>However, a complete website would handle this error more gracefully by displaying a message on the user's screen and perhaps offering options to remedy the situation, but we don't need anything more than a simple <code>console.log()</code>.</p> + +<p>You can test the fail case yourself:</p> + +<ol> + <li>Make a local copy of the example files (download and unpack <a href="https://github.com/mdn/learning-area/blob/master/javascript/apis/fetching-data/can-store/can-store.zip?raw=true">the can-store ZIP file</a>).</li> + <li>Run the code through a web server (as described above, in {{anch("Serving your example from a server")}}).</li> + <li>Modify the path to the file being fetched, to something like 'produc.json' (make sure it is misspelled).</li> + <li>Now load the index file in your browser (via <code>localhost:8000</code>) and look in your browser developer console. You'll see a message similar to "Network request for products.json failed with response 404: File not found".</li> +</ol> + +<p>The second Fetch block can be found inside the <code>fetchBlob()</code> function:</p> + +<pre class="brush: js">fetch(url).then(function(response) { + return response.blob(); +}).then(function(blob) { + // Convert the blob to an object URL — this is basically an temporary internal URL + // that points to an object stored inside the browser + var objectURL = URL.createObjectURL(blob); + // invoke showProduct + showProduct(objectURL, product); +});</pre> + +<p>This works in much the same way as the previous one, except that instead of using {{domxref("Body.json","json()")}}, we use {{domxref("Body.blob","blob()")}}. In this case we want to return our response as an image file, and the data format we use for that is <a href="/en-US/docs/Web/API/Blob">Blob</a> (the term is an abbreviation of "Binary Large Object" and can basically be used to represent large file-like objects, such as images or video files).</p> + +<p>Once we've successfully received our blob, we create an object URL out of it using {{domxref("URL.createObjectURL()", "createObjectURL()")}}. This returns a temporary internal URL that points to an object referenced inside the browser. These are not very readable, but you can see what one looks like by opening up the Can Store app, Ctrl-/Right-clicking on an image, and selecting the "View image" option (which might vary slightly depending on what browser you are using). The object URL will be visible inside the address bar, and should be something like this:</p> + +<pre>blob:http://localhost:7800/9b75250e-5279-e249-884f-d03eb1fd84f4</pre> + +<h3 id="Challenge_An_XHR_version_of_the_Can_Store">Challenge: An XHR version of the Can Store</h3> + +<p>We'd like you to try converting the Fetch version of the app to use XHR as a useful bit of practice. Take a <a href="https://github.com/mdn/learning-area/blob/master/javascript/apis/fetching-data/can-store/can-store.zip?raw=true">copy of the ZIP file</a>, and try modifying the JavaScript as appropriate.</p> + +<p>Some helpful hints:</p> + +<ul> + <li>You might find the {{domxref("XMLHttpRequest")}} reference material useful.</li> + <li>You will basically need to use the same pattern as you saw earlier in the <a href="https://github.com/mdn/learning-area/blob/master/javascript/apis/fetching-data/xhr-basic.html">XHR-basic.html</a> example.</li> + <li>You will, however, need to add the error handling we showed you in the Fetch version of the Can Store: + <ul> + <li>The response is found in <code>request.response</code> after the <code>load</code> event has fired, not in a promise <code>then()</code>.</li> + <li>About the best equivalent to Fetch's <code>response.ok</code> in XHR is to check whether {{domxref("XMLHttpRequest.status","request.status")}} is equal to 200, or if {{domxref("XMLHttpRequest.readyState","request.readyState")}} is equal to 4.</li> + <li>The properties for getting the status and status message are the same, but they are found on the <code>request</code> (XHR) object, not the <code>response</code> object.</li> + </ul> + </li> +</ul> + +<div class="note"> +<p><strong>Note</strong>: If you have trouble with this, feel free to check your code against the finished version on GitHub (<a href="https://github.com/mdn/learning-area/blob/master/javascript/apis/fetching-data/can-store-xhr/can-script.js">see the source here</a>, and also <a href="https://mdn.github.io/learning-area/javascript/apis/fetching-data/can-store-xhr/">see it running live</a>).</p> +</div> + +<h2 id="Summary">Summary</h2> + +<p>This article shows how to start working with both XHR and Fetch to fetch data from the server.</p> + +<h2 id="See_also">See also</h2> + +<p>There are however a lot of different subjects discussed in this article, which has only really scratched the surface. For a lot more detail on these subjects, try the following articles:</p> + +<ul> + <li><a href="/en-US/docs/AJAX/Getting_Started">Ajax — Getting started</a></li> + <li><a href="/en-US/docs/Web/API/Fetch_API/Using_Fetch">Using Fetch</a></li> + <li><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promises</a></li> + <li><a href="/en-US/docs/Learn/JavaScript/Objects/JSON">Working with JSON data</a></li> + <li><a href="/en-US/docs/Web/HTTP/Overview">An overview of HTTP</a></li> + <li><a href="/en-US/docs/Learn/Server-side">Server-side website programming</a></li> +</ul> + +<div>{{PreviousMenuNext("Learn/JavaScript/Client-side_web_APIs/Manipulating_documents", "Learn/JavaScript/Client-side_web_APIs/Third_party_APIs", "Learn/JavaScript/Client-side_web_APIs")}}</div> + +<div> +<h2 id="In_this_module">In this module</h2> + +<ul> + <li><a href="/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Introduction">Introduction to web APIs</a></li> + <li><a href="/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Manipulating_documents">Manipulating documents</a></li> + <li><a href="/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Fetching_data">Fetching data from the server</a></li> + <li><a href="/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Third_party_APIs">Third party APIs</a></li> + <li><a href="/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Drawing_graphics">Drawing graphics</a></li> + <li><a href="/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Video_and_audio_APIs">Video and audio APIs</a></li> + <li><a href="/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Client-side_storage">Client-side storage</a></li> +</ul> +</div> diff --git a/files/es/learn/javascript/client-side_web_apis/index.html b/files/es/learn/javascript/client-side_web_apis/index.html new file mode 100644 index 0000000000..731edea2a3 --- /dev/null +++ b/files/es/learn/javascript/client-side_web_apis/index.html @@ -0,0 +1,53 @@ +--- +title: Client-side web APIs +slug: Learn/JavaScript/Client-side_web_APIs +tags: + - API + - Articles + - Beginner + - CodingScripting + - DOM + - Graphics + - JavaScript + - Landing + - Learn + - Media + - Module + - NeedsTranslation + - TopicStub + - WebAPI + - data +translation_of: Learn/JavaScript/Client-side_web_APIs +--- +<div>{{LearnSidebar}}</div> + +<p class="summary">Cuando se escribe JavaScript para sitios web o aplicaciones del lado del cliente, no pasará mucho tiempo antes de que comience a usar APIs ("Application Programming Interfaces"). Estas son interfaces para manipular diferentes aspectos del navegador y el sistema operativo sobre el cuál se esta ejecutando, o incluso datos de otros sitios web o servicios. En este módulo, vamos a aprender que son las APIs y cómo utilizar algunas de las API más comunes que encuentran al momento de desarrollar. </p> + +<h2 id="Requisitos">Requisitos</h2> + +<p>Para aprovechar al máximo este módulo, debería haber trabajado con los módulos anteriores de JavaScript (<a href="/en-US/docs/Learn/JavaScript/First_steps">Primeros Pasos</a>, <a href="https://developer.mozilla.org/es/docs/Learn/JavaScript/Building_blocks">Bloques de construcción</a>, y <a href="https://developer.mozilla.org/es/docs/Learn/JavaScript/Objects">Objetos en JavaScript</a>). De todos modos, esos módulos involucran el uso de varias APIs simples, ya que es dificil escribir ejemplos en Javascript del lado del cliente sin dar uso de ellos! Para este tutorial, asumiremos que se tiene conocimiento basico sobre JavaScript y exploraremos las API web mas comunes con un poco más de detalle.</p> + +<p>Conocimiento basico de <a href="/en-US/docs/Learn/HTML">HTML</a> y <a href="/en-US/docs/Learn/CSS">CSS</a> tambien seria util.</p> + +<div class="note"> +<p><strong>Nota</strong>: Si está trabajando en un dispositivo en el que no tiene la capacidad de crear sus propios archivos, puede probar (la mayoría de) los ejemplos de código en un programa de codificación en línea como <a href="http://jsbin.com/">JSBin</a> o <a href="https://thimble.mozilla.org/">Thimble</a>.</p> +</div> + +<h2 id="Guías">Guías</h2> + +<dl> + <dt><a href="/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Introduction">Introducción a web APIs</a></dt> + <dd>En primer lugar, comenzaremos observando las API de alto nivel: ¿qué son, cómo funcionan, cómo las utilizan en su código y cómo están estructuradas? También veremos cuáles son las diferentes principales clases de APIs y qué tipo de usos tienen.</dd> + <dt><a href="/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Manipulating_documents">Manipulacion de documentos</a></dt> + <dd>Al escribir páginas web y aplicaciones, una de las cosas más comunes que querrás hacer es manipular los documentos web de alguna manera. Esto generalmente se hace usando el Document Object Model (DOM), un conjunto de APIs para controlar el HTML y la información de sus estilos que hace un uso intensivo del objeto {{domxref("Document")}} . En este artículo, veremos cómo usar el DOM en detalle, junto con algunas otras API que pueden alterar su entorno de maneras interesantes.</dd> + <dt><a href="/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Fetching_data">Obteniendo data desde el servidor</a></dt> + <dd>Otra tarea frecuente en las en las aplicaciones y los sitios web modernos, es recuperar los datos individuales de un elemento del seridor para actualizar solo una seccion de la pagina sin tener que cargar una pagina web completamente nueva. Este detalle, aparentemente pequeño, ha tenido un gran impacto en el rendimiento y el comportamiento de los sitios, En este artículo, explicaremos el concepto y veremos las tecnologías que hacen esto posible, como {{domxref("XMLHttpRequest")}} y el <a href="/en-US/docs/Web/API/Fetch_API">Fetch API</a>.</dd> + <dt><a href="/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Third_party_APIs">APIs de terceros</a></dt> + <dd>Las APIs que hemos cubierto hasta ahora están integradas en el navegador, pero no todas las APIs lo estan. Muchos grandes sitios web y servicios tales como Google Maps, Twitter, Facebook, PayPal, etc. proporcionan APIs que permiten a los desarrolladores hacer uso de sus datos (p.ej. mostrando tu actividad en twitter dentro de tu blog) o sus servicios (p.ej. mostrar una ubicacion personalizada porGoogle Maps en tu sitio, o usar el inicio de sesión de Facebook para que inicien sesión tus usuarios). Este artículo analiza la diferencia entre las API del navegador y las API de terceros y muestra algunos usos típicos de este último.</dd> + <dt><a href="/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Drawing_graphics">Dibujar gráficos</a></dt> + <dd>El navegador contiene algunas herramientas de programación poderosas para gráficos, desde el lenguaje de Gráficos de Vectores Escalables (<a href="/en-US/docs/Web/SVG">SVG</a>), hasta APIs para dibujar elementos HTML {{htmlelement("canvas")}}, (ver <a href="/en-US/docs/Web/API/Canvas_API">El API Canvas</a> y <a href="/en-US/docs/Web/API/WebGL_API">WebGL</a>). Este articulo provee una introducción al Canvas API, y además recursos que te van a permirir aprender más.</dd> + <dt><a href="/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Video_and_audio_APIs">APIs de audio y video</a></dt> + <dd>HTML5 for embedding rich media in documents — {{htmlelement("video")}} and {{htmlelement("audio")}} — which in turn come with their own APIs for controlling playback, seeking, etc. This article shows you how to do common tasks such as creating custom playback controls.</dd> + <dt><a href="/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Client-side_storage">Almacenamiento del lado del Cliente</a></dt> + <dd>Modernos navegadores web implementan un número de diferente de tecnologías que te permiten almacenar datos relacionados a sitios y recuperarlos cuando sea necesario permitiendote almacenarlos por mucho tiempo, almacenar sitios fuera de linea, y más. Este articulo explica aspectos los principios de como trabaja.</dd> +</dl> diff --git a/files/es/learn/javascript/client-side_web_apis/introducción/index.html b/files/es/learn/javascript/client-side_web_apis/introducción/index.html new file mode 100644 index 0000000000..fc73d4ebc9 --- /dev/null +++ b/files/es/learn/javascript/client-side_web_apis/introducción/index.html @@ -0,0 +1,274 @@ +--- +title: Introducción a las APIs web +slug: Learn/JavaScript/Client-side_web_APIs/Introducción +translation_of: Learn/JavaScript/Client-side_web_APIs/Introduction +--- +<div>{{LearnSidebar}}</div> + +<div>{{NextMenu("Learn/JavaScript/Client-side_web_APIs/Manipulating_documents", "Learn/JavaScript/Client-side_web_APIs")}}</div> + +<p class="summary">En primer lugar empezaremos echando un vistazo a las APIS desde un nivel superior — ¿qué son, cómo funcionan, cómo usarlas en el código, y cómo están estructuradas?. También echaremos un vistazo a cuáles son los principales tipos de APIs, y para qué se usan.</p> + +<table class="learn-box standard-table"> + <tbody> + <tr> + <th scope="row">Pre requisitos:</th> + <td>Conocimientos básicos de informática, principios básicos de <a href="/es/docs/Learn/HTML">HTML</a>, <a href="/es/docs/Learn/CSS">CSS</a> y JavaScript (ver <a href="/es/docs/Learn/JavaScript/First_steps">primeros pasos</a>, <a href="/es/docs/Learn/JavaScript/Building_blocks">bloques de construcción</a>, <a href="/es/docs/Learn/JavaScript/Objects">objetos JavaScript</a>).</td> + </tr> + <tr> + <th scope="row">Objetivo:</th> + <td>Familiarizarse con las APIs, saber qué pueden hacer y cómo usarlas en tu código.</td> + </tr> + </tbody> +</table> + +<h2 id="¿Qué_son_las_APIs">¿Qué son las APIs?</h2> + +<p>Las Interfaces de Programacion de Aplicaciones (APIs por sus siglas en inglés) son construcciones disponibles en los lenguajes de programación que permiten a los desarrolladores crear funcionalidades complejas de una manera simple. Estas abstraen el código más complejo para proveer una sintaxis más fácil de usar en su lugar.</p> + +<p>Como ejemplo, piensa en el suministro de electricidad de tu casa, apartamento, o cualquier otro edificio. Si quieres usar un electrodoméstico, simplemente lo conectas en un enchufe y funciona. No intentas conectarlo directamente a la fuente de alimentación — hacerlo sería muy ineficiente y, si no eres electricista, dificil y peligroso.</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/14317/plug-socket.png" style="display: block; height: 472px; margin: 0px auto; width: 700px;"></p> + +<p><em>Fuente de la imagen: <a href="https://www.flickr.com/photos/easy-pics/9518184890/in/photostream/lightbox/">Overloaded plug socket</a> por <a href="https://www.flickr.com/photos/easy-pics/">The Clear Communication People</a>, en Flickr.</em></p> + +<p>De la misma manera, si quisieras programar gráficos 3D, sería mucho más facil hacerlo usando una API escrita en un lenguaje de alto nivel como JavaScript o Python, en lugar de intentar escribir código de bajo nivel (por ejemplo: C o C++) que controle directamente la GPU del equipo u otras funciones gráficas.</p> + +<div class="note"> +<p><strong>Nota</strong>: Consulta también la <a href="/es/docs/Glossary/API">entrada API en el glosario</a> para una descripción más detallada.</p> +</div> + +<h3 id="APIs_en_JavaScript_del_lado_cliente">APIs en JavaScript del lado cliente</h3> + +<p>JavaScript del lado cliente, particularmente, tiene muchas APIs disponibles — estas <span id="result_box" lang="es"><span>no son parte del lenguaje en sí, sino que están construidas sobre el núcleo de este lenguaje de programación, proporcionándote superpoderes adicionales para usar en tu código.</span> <span>Por lo general, se dividen en dos categorías:</span></span></p> + +<ul> + <li><span id="result_box" lang="es"><span><strong>Las APIs de navegador</strong> están integradas en tu navegador web y pueden exponer datos del navegador y del entorno informático circundante y hacer cosas complejas y útiles con él.</span> <span>Por ejemplo, la API de Geolocalización proporciona algunas construcciones simples de JavaScript para obtener datos de ubicación con los que, por ejemplo, trazar tu ubicación en un mapa de Google.</span> Realmente, el navegador está haciendo uso<span> de códigos de bajo nivel complejos en segundo plano (por ejemplo, C++) para comunicarse con el hardware GPS del dispositivo (o lo que esté disponible para determinar los datos de posición), recuperar datos de posición y devolverlos al entorno del navegador para su uso</span> <span>en tu código.</span> <span>Pero una vez más, la API se encarga de abstraer esta complejidad.</span></span></li> + <li><strong>Las APIs de terceros </strong>no están incluídas por defecto en el navegador, y por lo general es necesario obtener el código e información desde algún lugar de la Web. Por ejemplo, <a href="https://dev.twitter.com/overview/documentation">la API de Twitter</a> permite hacer cosas como mostrar tus últimos tweets en un sitio web. Proporciona un conjunto especial de construcciones que puedes usar para consultar el servicio de Twitter y devolver información específica.</li> +</ul> + +<p><img alt="" src="https://mdn.mozillademos.org/files/13508/browser.png" style="display: block; height: 511px; margin: 0px auto; width: 815px;"></p> + +<h3 id="Relacion_entre_JavaScript_APIs_y_otras_herramientas_de_JavaScript">Relacion entre JavaScript, APIs, y otras herramientas de JavaScript</h3> + +<p><span id="result_box" lang="es"><span>Anteriormente hablamos sobre qué son las APIs de JavaScript del lado cliente y cómo se relacionan con este lenguaje.</span> <span>Recapitulemos ahora para dejarlo claro, y veamos también dónde encajan otras herramientas de JavaScript:</span></span></p> + +<ul> + <li>JavaScript — Un lenguaje de scripts de alto nivel incorporado en los navegadores que permite implementar interactividad en páginas web / apps. <span id="result_box" lang="es"><span>Ten en cuenta que JavaScript también está disponible en otros entornos de programación, como <a href="https://developer.mozilla.org/en-US/docs/Learn/Server-side/Express_Nodejs/Introduction">Node</a>.</span></span></li> + <li>APIs de navegador — Construcciones integradas en el navegador creadas con el lenguaje JavaScript y que permiten implementar funcionalidad mucho más fácilmente.</li> + <li>APIs de terceros — <span id="result_box" lang="es"><span>Construcciones integradas en plataformas de terceros (por ejemplo Twitter, Facebook) que permiten usar algunas de las funcionalidades de esa plataforma en tus páginas web (como por ejemplo mostrar tus últimos Tweets en tu página web).</span></span></li> + <li>Librerías JavaScript — Por lo general uno o más archivos JavaScript que contienen <a href="/es/docs/Learn/JavaScript/Building_blocks/Functions#Custom_functions">funciones personalizadas</a> que puedes añadir a tu página web para acelerar o habilitar la escritura de funcionalidades comunes. Por ejemplo jQuery, Mootools y React.</li> + <li>Frameworks JavaScript — <span id="result_box" lang="es"><span>El siguiente paso a las librerías, los frameworks JavaScript (como Angular y Ember) suelen ser paquetes de HTML, CSS, JavaScript y otras tecnologías que se instalan y luego se usan para escribir una aplicación web completa desde cero.</span> <span>La diferencia clave entre una librería y un framework es la "Inversión del control".</span> <span>Cuando se llama a un método desde una librería, el desarrollador tiene el control.</span> <span>Con un framework el control se invierte: el framework llama al código del desarrollador.</span></span></li> +</ul> + +<h2 id="¿Qué_pueden_hacer_las_APIs"><span class="short_text" id="result_box" lang="es"><span>¿Qué pueden hacer las APIs?</span></span></h2> + +<p><span id="result_box" lang="es"><span>Hay una gran cantidad de APIs disponibles en los navegadores modernos que te permiten hacer una gran variedad de cosas en tu código.</span> <span>Puedes verlo echando un vistazo al</span></span> <a href="https://developer.mozilla.org/es/docs/Web/API">índice de APIs de MDN</a>.</p> + +<h3 id="APIs_de_navegador_más_comunes">APIs de navegador más comunes</h3> + +<p><span id="result_box" lang="es"><span>En particular, las categorías más comunes de APIs de navegador más usadas (y que trataremos con mayor detalle en este módulo) son:</span></span></p> + +<ul> + <li><strong>APIs para manipular documentos</strong> cargados en el navegador. El ejemplo más obvio es la <a href="https://developer.mozilla.org/es/docs/Web/API/Document_Object_Model">API DOM (Document Object Model)</a>, que permite manipular HTML y CSS — crear, eliminar y modificar HTML, aplicar estilos dinámicos a una página, etc. Cada vez que se muestra una ventana emergente en una página, o un nuevo contenido, por ejemplo, es el DOM en acción. Más información sobre este tipo de APIs en <a href="/es/docs/Learn/JavaScript/Client-side_web_APIs/Manipulating_documents">Manipulando documentos</a>.</li> + <li><strong>APIs que obtienen datos del servidor,</strong> comunmente usadas para actualizar pequeñas secciones de una página web. Este aparente pequeño detalle tiene un gran impacto en el performance y en el comportamiento de los sitios. — Sí solo necesitas actualizar un Stock de artículos o una lista de tiendas disponibles, al utilizar APIs para obtener datos desde el servidor lo lograrás sin tener que volver a cargar toda la página o aplicación logrando que estas tengan una sensación de rapidez y agilidad. Las APIs hacen esto posible gracias a que incluyen <a href="https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest" title="XMLHttpRequest is an API that provides client functionality for transferring data between a client and a server. It provides an easy way to retrieve data from a URL without having to do a full page refresh. This enables a Web page to update just a part of the page without disrupting what the user is doing."><code>XMLHttpRequest</code></a> y la <a href="https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API">Fetch API</a>. Tambièn puede encontrar el termino Ajax que describe esta técnica. Más información sobre este tipo de APIs en <a href="/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Fetching_data">Fetching data from the server</a>.</li> + <li><strong>Las APIs para dibujar y manipular graficos</strong> ya son soportadas por la mayoría de navegadores. Las más populares son <a href="/en-US/docs/Web/API/Canvas_API">Canvas</a> y <a href="/en-US/docs/Web/API/WebGL_API">WebGL</a>, que permiten actualizar la información de cada uno de los píxeles contenidos en un {{htmlelement("canvas")}} HTML, para crear escenas 2D y 3D. Por ejemplo, se pueden dibujar formas como rectángulos o círculos, importar una imagen en el canvas y aplicarle filtros como sepia o escala de grises usando la API de Canvas, o crear una escena compleja 3D con iluminación y texturas usando WebGL. Estas APIs, a menudo se combinan con apis para crear bucles de animación (como {{domxref("window.requestAnimationFrame()")}}) y otras veces para hacer que se actualicen constantemente escenas de dibujos animados o videojuegos.</li> + <li><strong><a href="https://developer.mozilla.org/en-US/Apps/Fundamentals/Audio_and_video_delivery">APIS de audio y vídeo</a></strong> como {{domxref("HTMLMediaElement")}}, la <a href="/en-US/docs/Web/API/Web_Audio_API">Web Audio API</a>, y <a href="/en-US/docs/Web/API/WebRTC_API">WebRTC</a> te permitirán hacer cosas realmente interesantes con elementos multimedia: crear una interfaz personalizada para los controles de reproducción de audio y vídeo, mostrar pistas de texto con subtítulos junto con el vídeo, capturar vídeo de la cámara web para ser manipulado en un canvas (ver más arriba) o mostrado en el ordenador de otra persona en una videoconferencia, añadir efectos a las pistas de audio (como ganancia, distorsión, retardo, etc).</li> + <li><strong>Las APIs de dispositivos</strong> son básicamente APIs para manipular y recuperar información de dispositivos modernos de hardware de forma que sean útiles para aplicaciones web. Ya hemos hablado de la API de geolocalización, que accede a la información de ubicación del dispositivo, de forma que te pueda localizar en un mapa. Otros ejemplos incluyen indicar al usuario de que una actulización útil está disponible en una aplicación web mediante notificaciones de sistema (ver <a href="/en-US/docs/Web/API/Notifications_API">Notifications API</a>) o la vibración de hardware (ver <a href="/en-US/docs/Web/API/Vibration_API">Vibration API</a>).</li> + <li>Las <strong>APIS de almacenamiento en el lado del cliente</strong> se están popularizando en los navegadores. La habilidad de almacenar información en el lado del cliente es muy útil para hacer aplicaciones que salven su estado entre carga de páginas, e incluso trabajar cuando el dispositivo está fuera de línea. Hay varias opciones disponibles, por ejemplo el almacenamiento en pares de clave/valor con <a href="/en-US/docs/Web/API/Web_Storage_API" style="font-size: 1rem; letter-spacing: -0.00278rem;">Web Storage API</a><span style="font-size: 1rem; letter-spacing: -0.00278rem;">, y una forma más compleja de almacenar datos tabulados mediante la </span><a href="/en-US/docs/Web/API/IndexedDB_API" style="font-size: 1rem; letter-spacing: -0.00278rem;">IndexedDB API</a><span style="font-size: 1rem; letter-spacing: -0.00278rem;">.</span></li> +</ul> + +<h3 id="APIs_populares_de_terceros">APIs populares de terceros</h3> + +<p>Existe una gran variedad de APIs de terceros, algunas de las más populares de las que querrás hacer uso en algún momento son:</p> + +<ul> + <li>La <a href="https://dev.twitter.com/overview/documentation">API de Twitter</a>, que te permite hacer cosas como mostrar tus ultimos tweets en tu sitio web.</li> + <li>La <a href="https://developers.google.com/maps/">API de Google Maps</a> permite hacer todo tipo de cosas con mapas en tus páginas web (incluso hace funcionar Google Maps). Actualmente, existe todo un conjunto de apis que te permiten realizar una gran variedad de tareas, como se puede ver en <a href="https://developers.google.com/maps/documentation/api-picker">Google Maps API Picker</a>.</li> + <li>El <a href="https://developers.facebook.com/docs/">conjunto de APIs de Facebook</a> te permite usar partes del ecosistema de facebook para mejorar tu aplicación, por ejemplo aportando la posiblidad de identificación mediante el login de Facebook, aceptar pagos en la aplicación, desplegar campañas de anuncios para un target concreto, etc.</li> + <li>La <a href="https://developers.google.com/youtube/">YouTube API</a>, te permite integrar videos de Youtube en tu sitio, buscar en Youtube, construir listas de reproducción y más.</li> + <li>La <a href="https://www.twilio.com/">Twilio API</a>, provee de un framework para crear la funcionalidad de llamadas y videollamadas en tus aplicaciones, enviar SMS o MMS y más.</li> +</ul> + +<div class="note"> +<p><strong>Nota</strong>: puedes encontrar información de una gran cantidad de APIs de terceros en el <a href="http://www.programmableweb.com/category/all/apis">Programmable Web API directory</a>.</p> +</div> + +<h2 id="¿Cómo_funcionan_las_APIs">¿Cómo funcionan las APIs?</h2> + +<p>Las distintas APIs de JavaScript funcionan de forma ligeramente diferente, pero generalmente tienen características similares y una forma parecida en cómo trabajan.</p> + +<h3 id="Están_basadas_en_objetos">Están basadas en objetos</h3> + +<p>Las APIs interactúan con tu código usando uno o más <a href="/en-US/docs/Learn/JavaScript/Objects">Objetos JavaScript,</a> que sirven como contenedores para los datos que usa la API (contenidos en las propiedades del objeto), y la funcionalidad que la API provee (contenida en los métodos del objeto).</p> + +<div class="note"> +<p><strong>Nota</strong>: si no estás familiarizado en cómo trabajar con objetos, deberías volver atrás y revisar el módulo de <a href="/en-US/docs/Learn/JavaScript/Objects">objetos JavaScript </a>antes de seguir.</p> +</div> + +<p>Volvamos al ejemplo de la API de Geolocalización, que es una API muy simple que consiste en unos pocos objetos sencillos:</p> + +<ul> + <li>{{domxref("Geolocation")}}, que contiene tres métodos para controlar la recuperación de los datos geográficos.</li> + <li>{{domxref("Position")}}, que representa la posición de un dispositivo en un momento dado — esto contiene un objeto {{domxref("Coordinates")}} que contiene la información de la posición actual, además de una marca de tiempo con el momento exacto.</li> + <li>{{domxref("Coordinates")}}, que contiene una gran cantidad de datos útiles sobre la posición del dispositivo, incluyendo latitud y longitud, altitud, velocidad, dirección de movimiento y más.</li> +</ul> + +<p>¿Cómo interactúan estos objetos? Si miras a nuestro ejemplo <a href="https://github.com/mdn/learning-area/blob/master/javascript/apis/introduction/maps-example.html">maps-example.html</a> (<a href="http://mdn.github.io/learning-area/javascript/apis/introduction/maps-example.html">ver también en vivo</a>), encontrarás el siguiente código:</p> + +<pre class="brush: js">navigator.geolocation.getCurrentPosition(function(position) { + var latlng = new google.maps.LatLng(position.coords.latitude,position.coords.longitude); + var myOptions = { + zoom: 8, + center: latlng, + mapTypeId: google.maps.MapTypeId.TERRAIN, + disableDefaultUI: true + } + var map = new google.maps.Map(document.querySelector("#map_canvas"), myOptions); +});</pre> + +<div class="note"> +<p><strong>Nota</strong>: cuando cargues por primera vez el ejemplo de arriba, se te mostrará un mensaje preguntando si deseas compartir tu localización con esta aplicación (ver la sección {{anch("They have additional security mechanisms where appropriate")}} que se encuentra más adelante en este artículo). Deberás estar de acuerdo con esto para poder ver tu localización en el mapa. Si aún así sigues sin ver tu localización, tal vez debas establecer los permisos manualmente; lo puedes hacer de varias formas dependiendo del navegador que estés usando; por ejemplo en Firefox debes ir a > <em>Tools</em> > <em>Page Info</em> > <em>Permissions</em>, y cambiar la configuración para <em>Share Location</em>; en Chrome ve a <em>Settings</em> > <em>Privacy</em> > <em>Show advanced settings</em> > <em>Content settings</em> y cambia las opciones para <em>Location</em>.</p> +</div> + +<p>Primero queremos usar el método {{domxref("Geolocation.getCurrentPosition()")}} para retornar la posición actuali de nuestro dispositivo. El objeto {{domxref("Geolocation")}} del navegador es accedido llamando a la propiedad {{domxref("Navigator.geolocation")}}, así que comenzaremos haciendo:</p> + +<pre class="brush: js">navigator.geolocation.getCurrentPosition(function(position) { ... });</pre> + +<p>Lo que es equivalente a hacer algo como:</p> + +<pre class="brush: js">var myGeo = navigator.geolocation; +myGeo.getCurrentPosition(function(position) { ... });</pre> + +<p>Pero podemos usar la sintaxis con punto para concatener nuestros accesos a propiedades/métodos reduciendo el número de líneas que tenemos que escribir.</p> + +<p>El método {{domxref("Geolocation.getCurrentPosition()")}} solamente tiene un parámetroobligatorio, que es una función anónima que se ejecutará cuando se recupere correctamente la ubicación del dispositivo. Esta función tiene un parámetro, que contiene un objeto<span style="font-size: 1rem; letter-spacing: -0.00278rem;"> {{domxref("Position")}} con la representación de los datos de la posición actual.</span></p> + +<div class="note"> +<p><strong>Nota</strong>: una función que es tomada por otra función como argumento es conocida con el nombre de <a href="/en-US/docs/Glossary/Callback_function">callback function</a>.</p> +</div> + +<p>Este patrón de invocar una función solamente cuando una operación ha sido completada es muy común en las APIs de Javascript — asegurando que una operación ha sido completada antes de intentar usar los datos que retorna en otra operación. Estas operaciones se llaman <strong><a href="/en-US/docs/Glossary/Asynchronous">operaciones asíncronas</a></strong>. Puesto que obtener la posición actual del dispositivo recae en un componente externo (el GPS del dispositivo u otro hardware de geolocalización), no podemos asegurar que se haga a tiempo para usar inmediatamente los datos. Por tanto, algo así no funcionará:</p> + +<pre class="brush: js example-bad">var position = navigator.geolocation.getCurrentPosition(); +var myLatitude = position.coords.latitude;</pre> + +<p>Si la primera línea no ha retornado todavía su resultado, la segunda línea lanzará un error puesto que los datos de posición no estarán disponibles. Por esa razón, las APIs que tienen operaciones asíncronas se diseñan para usar<span style="font-size: 1rem; letter-spacing: -0.00278rem;"> {{glossary("callback function")}}s, o el sistema más moderno de </span><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" style="font-size: 1rem; letter-spacing: -0.00278rem;">Promises</a><span style="font-size: 1rem; letter-spacing: -0.00278rem;">, que se ha introducido en ECMAScript 6 y se está usando mucho en las APIs más nuevas.</span></p> + +<p>Vamos a combinar la API de geolocalización con una API de terceros — la API de Google Maps — que se usa para dibujar la localización retornada por <code>getCurrentPosition()</code> en un mapa de Google. Haremos disponible esta API en nuestra página vinculándonos a ella — encontrarás esta línea en el HTML:</p> + +<pre class="brush: html"><script type="text/javascript" src="https://maps.google.com/maps/api/js?key=AIzaSyDDuGt0E5IEGkcE6ZfrKfUtE9Ko_de66pA"></script></pre> + +<p>Para usar la API, primero creamos una instancia del objeto <code>LatLng</code> usando el constructor <code>google.maps.LatLng()</code>, que toma los valores de nuestra {{domxref("Coordinates.latitude")}} y {{domxref("Coordinates.longitude")}} geolocalizada como parámetros:</p> + +<pre class="brush: js">var latlng = new google.maps.LatLng(position.coords.latitude,position.coords.longitude);</pre> + +<p>Este objeto quedará establecido como el valor de la propiedad<span style="font-size: 1rem; letter-spacing: -0.00278rem;"> </span><code style="font-size: 1rem; letter-spacing: -0.00278rem;">center</code><span style="font-size: 1rem; letter-spacing: -0.00278rem;"> de un objeto de opciones que hemos llamado </span><code style="font-size: 1rem; letter-spacing: -0.00278rem;">myOptions</code><span style="font-size: 1rem; letter-spacing: -0.00278rem;">. Entonces crearemos una instancia de objeto para representar nuestro mapa llamando al constructor de </span><code style="font-size: 1rem; letter-spacing: -0.00278rem;">google.maps.Map()</code><span style="font-size: 1rem; letter-spacing: -0.00278rem;">, pasándole sus dos parámetros — una referencia al elemento {{htmlelement("div")}} donde queremos presentar el mapa (con ID </span><code style="font-size: 1rem; letter-spacing: -0.00278rem;">map_canvas</code><span style="font-size: 1rem; letter-spacing: -0.00278rem;">), y el objeto de opciones que acabamos de definir.</span></p> + +<pre class="brush: js">var myOptions = { + zoom: 8, + center: latlng, + mapTypeId: google.maps.MapTypeId.TERRAIN, + disableDefaultUI: true +} + +var map = new google.maps.Map(document.querySelector("#map_canvas"), myOptions);</pre> + +<p>Una vez hecho, veremos dibujado nuestro mapa.</p> + +<p>Este último bloque de código muestra dos patrones habituales que veremos en muchas APIs. Primero, los objetos de las APIs habitualmente disponen de constructores, que son invocados para crear instancias de esos objetos que que habitualmente usaremos en nuestros programas. Segundo, los objetos de las APIs a menudo ofrecen múltiples opciones que pueden ser adaptadas para obtener exactamente lo que queremos en nuestro programa. Los constructores de las APIs habitualmente aceptan un objeto de opciones como parámetro, que es donde se deben establecer dichas opciones.</p> + +<div class="note"> +<p><strong>Nota</strong>: no te preocupes si no entiendes todos los detalles de este ejemplo inmediantamente. Los repasaremos usando APIs de terceros con más detalle en un artículo futuro.</p> +</div> + +<h3 id="Tienen_puntos_de_acceso_reconocibles">Tienen puntos de acceso reconocibles</h3> + +<p>Cuando uses una API, debes estar seguro que conoces dónde están los puntos de acceso para ella. En la API de Geolocalización esto es bastante sencillo — es la propiedad {{domxref("Navigator.geolocation")}}, que retorna el objeto del navegador {{domxref("Geolocation")}} que contiene todos los métodos útiles de geolocalización disponibles en su interior.</p> + +<p>La API del Modelo de Objetos del Navegador (DOM) tiene un punto de acceso todavía más simple — sus características las podemos encontrar colgando del objeto {{domxref("Document")}}, o una instancia de un elemento HTML que queremos modificar de alguna forma, por ejemplo:</p> + +<pre class="brush: js">var em = document.createElement('em'); // crear un nuevo elemento em +var para = document.querySelector('p'); // referencia a un elemento p existente +em.textContent = 'Hello there!'; // dar al em algo de contenido textual +para.appendChild(em); // ubicar el em dentro del párrafo</pre> + +<p>Otras APIs tienen puntos de acceso ligeramente más complejos, que a menudo implican crear un contexto específico para escribir el código de la API. Por ejemplo, el objeto de contexto de la API Canvas se crea obteniendo una referencia al elemento<span style="font-size: 1rem; letter-spacing: -0.00278rem;"> {{htmlelement("canvas")}} en el que quieres dibujar, y a continuación invocando su método {{domxref("HTMLCanvasElement.getContext()")}}:</span></p> + +<pre class="brush: js">var canvas = document.querySelector('canvas'); +var ctx = canvas.getContext('2d');</pre> + +<p>Cualquier cosa que queramos hacerle al canvas, se conseguirá llamando a las propiedades y métodos del objeto de contexto (que es una instancia de {{domxref("CanvasRenderingContext2D")}}), por ejemplo:</p> + +<pre class="brush: js">Ball.prototype.draw = function() { + ctx.beginPath(); + ctx.fillStyle = this.color; + ctx.arc(this.x, this.y, this.size, 0, 2 * Math.PI); + ctx.fill(); +};</pre> + +<div class="note"> +<p><strong>Nota</strong>: puedes ver este código en acción en nuetro <a href="https://github.com/mdn/learning-area/blob/master/javascript/apis/introduction/bouncing-balls.html">bouncing balls demo</a> (y también verlo <a href="http://mdn.github.io/learning-area/javascript/apis/introduction/bouncing-balls.html">funcionando</a>).</p> +</div> + +<h3 id="Usan_eventos_para_manejar_cambios_en_su_estado">Usan eventos para manejar cambios en su estado</h3> + +<p>Ya hemos discutido anteriormente los eventos en este curso, en nuestro artículo de <a href="/en-US/docs/Learn/JavaScript/Building_blocks/Events">Introducción a los eventos</a> — este artículo detalla qué son los eventos del lado del cliente y cómo se usan en el código. Si no estás familiarizado en cómo se trabaja con la API de eventos del lado del cliente, deberías ir a consultar este artículo antes de continuar.</p> + +<p>Algunas APIs web no contienen eventos, pero algunas otras sí contienen un buen número de ellos. Las propiedades para manejarlos, que nos permiten ejecutar funciones cuando los eventos se producen, generalmente se listan en nuestro material de referencia en secciones de "Manejadores de Eventos" separadas. Como ejemplo simple, instancias del objeto <code><a href="/en-US/docs/Web/API/XMLHttpRequest">XMLHttpRequest</a></code> (cada uno representa una petición HTTP al servidor para recuperar un nuevo recurso de algún tipo) tienen un número de eventos disponibles, por ejemplo el evento <code>load</code> que es disparado cuando una respuesta ha sido retornada satisfactoriamente conteniendo el recurso solicitado, y ahora está disponible.</p> + +<p>El siguiente código aporta un ejemplo simple de cómo se debe usar esto:</p> + + + +<pre class="brush: js">var requestURL = 'https://mdn.github.io/learning-area/javascript/oojs/json/superheroes.json'; +var request = new XMLHttpRequest(); +request.open('GET', requestURL); +request.responseType = 'json'; +request.send(); + +request.onload = function() { + var superHeroes = request.response; + populateHeader(superHeroes); + showHeroes(superHeroes); +}</pre> + +<div class="note"> +<p><strong>Nota</strong>: puedes ver este código en acción en nuestro ejemplo <a href="https://github.com/mdn/learning-area/blob/master/javascript/apis/introduction/ajax.html">ajax.html</a> (<a href="http://mdn.github.io/learning-area/javascript/apis/introduction/ajax.html">verlo en vivo</a>).</p> +</div> + +<p>Las primeras cinco líneas especifican la licalización del recurso que queremos recuperar, se crea una nueva instancia del objeto con la petición usando el constructor <code>XMLHttpRequest()</code>, se abre una petición HTTP <code>GET</code> para recuperar el recurso especificado, se indica que la respuesta debería ser enviada en formato JSON, y finalmente se envía la petición.</p> + +<p>El manejador <code>onload</code> especifica entonces qué hacer con la respuesta. Ya sabemos que la respuesta será retornada satisfactoriamente y estará disponible tras producirse el evento load (a menos que haya sucedido un error), así que salvamos la respuesta que contiene el código JSON retornado en la variable <code style="font-size: 1rem; letter-spacing: -0.00278rem;">superHeroes</code><span style="font-size: 1rem; letter-spacing: -0.00278rem;">, luego lo pasamos a dos funciones diferentes para un procesado posterior.</span></p> + +<h3 id="Tienen_mecanismos_adicionales_de_seguridad_donde_sea_necesario">Tienen mecanismos adicionales de seguridad donde sea necesario</h3> + +<p>Las características de las WebAPI están sujetas a las mismas consideraciones de seguridad que JavaScript y otras tecnologías web (por ejemplo <a href="/en-US/docs/Web/Security/Same-origin_policy">same-origin policy</a>), pero a veces tienen mecanismos adicionales de seguridad. Por ejemplo, algunas de las WebAPIs más modernas solamente funcionan en páginas servidas mediante HTTPS debido a que transmiten información potencialmente sensible (algunos ejemplos son <a href="/en-US/docs/Web/API/Service_Worker_API">Service Workers</a> y <a href="/en-US/docs/Web/API/Push_API">Push</a>).</p> + +<p>Además, algunas WebAPIs solicitarán permiso al usuario para ser activadas cuando se produzcan las llamadas desde el código. Como ejemplo, habrás observado un cuadro de diálogo como éste al probar nuestro ejemplo anterior de <a href="/en-US/docs/Web/API/Geolocation">Geolocalización</a>:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/14313/location-permission.png" style="border-style: solid; border-width: 1px; display: block; height: 188px; margin: 0px auto; width: 413px;"></p> + +<p>La <a href="/en-US/docs/Web/API/Notifications_API">Notifications API</a> solicita los permisos de una forma parecida:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/14315/notification-permission.png" style="border-style: solid; border-width: 1px; display: block; margin: 0px auto;"></p> + +<p>Estos diálogos solicitando permiso se muestran al usuario por motivos de seguridad — si no estuvieran, los sitios podrían rastrear la localización sin que el usuario lo supiera o bombardearlo con un montón de notificaciones molestas.</p> + +<h2 id="Resumen">Resumen</h2> + +<p>En este punto, deberías tener ya una buena idea de los que son las APIs, cómo trabajan y qué puedes hacer con ellas en tu código JavaScript. Seguramente estarás con ganas de comenzar a hacer cosas divertidas con algunas APIs específicas, así que ¡vamos allá! A continuación veremos cómo manipular documentos con el Modelo de Objetos del Documento (DOM).</p> + +<p>{{NextMenu("Learn/JavaScript/Client-side_web_APIs/Manipulating_documents", "Learn/JavaScript/Client-side_web_APIs")}}</p> + +<h2 id="En_este_módulo">En este módulo</h2> + +<ul> + <li><a href="/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Introduction">Introducción a las APIs web</a></li> + <li><a href="/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Manipulating_documents">Manipulando documentos</a></li> + <li><a href="/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Fetching_data">Recuperando información del servidor</a></li> + <li><a href="/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Third_party_APIs">APIs de terceros</a></li> + <li><a href="/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Drawing_graphics">Dibujando gráficos</a></li> + <li><a href="/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Video_and_audio_APIs">APIs de vídeo y audio</a></li> + <li><a href="/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Client-side_storage">Almacenamiento en el lado del cliente</a></li> +</ul> |