Agregar Scripts a la Página Web – Using Zend Framework 3

Translation into this language is not yet finished. You can help this project by translating the chapters and contributing your changes.

6.7. Agregar Scripts a la Página Web

El código JavaScript se puede insertar dentro de las páginas HTML y hacerlas interactivas. Los scripts se podrían insertar en el archivo HTML entre las etiquetas <script> y <\script>. Abajo presentamos código JavaScript de ejemplo:

<script type="text/javascript">
  // Show a simple alert window with the "Hello World!" text.
  $(document).ready(function() {
    alert('Hello World!');
  });
</script>

En el ejemplo de arriba creamos el elemento <script> y colocamos la llamada a la función jQuery en él. La función que está atada a jQuery se ejecuta cuando el DOM ha terminado de cargarse. Cuando la función se ejecuta una ventana de alerta con el texto "Hello World!" y el botón OK aparecerá.

Como colocamos el código JavaScript dentro del archivo HTML nos referiremos a él como un script en linea. Una manera alternativa para guardar código JavaScript es colocándolo en un archivo .js externo. Los archivos externos generalmente contienen código que se diseña para usarse en varias páginas. Generalmente los archivos JavaScript externos se almacenan en el directorio APP_DIR/public/js/. Para enlazar un archivo JS a nuestra página HTML agregamos el elemento <script> como se muestra abajo:

<script type="text/javascript" src="/js/yourscript.js"></script>

Cuando el navegador encuentra un elemento <script> lee el archivo JS externo y ejecuta el código.

Generalmente hay dos lugares dentro del archivo HTML donde podemos colocar el script:

El código JavaScript se puede colocar en la sección <head> de una página HTML. Es recomendable usar este método cuando necesitamos que el JavaScript se cargue antes que el contenido de la página. Usamos este método para cargar la extensión de JavaScript Twitter Bootstrap y la biblioteca jQuery.
El script se puede colocar al final de la sección <body> de la paǵina HTML, exactamente antes de cerrar la etiqueta </body>. Esta manera es mejor cuando si necesitamos que todo el DOM se cargue antes de que el script pueda comenzar a ejecutarse.

¹⁴⁾ El DOM (Modelo de Objetos del Documento) es una conveniente representación de la estructura de un documento HTML en forma de un árbol de documentos.

Si un determinado archivo JavaScript se necesita usar en todos (o en la mayoría) de las páginas web es mejor colocarlo en una plantilla de vista. Pero cuando un script se usa en sola una página, colocarlo en la plantilla no es la mejor idea. Si colocamos un script en una plantilla el script se cargará en todas las páginas lo que puede producir un trafico innecesario y un incremento del tiempo de carga de la página y de todo el sitio. Para evitarlo podemos agregar un script para determinadas páginas solamente.

Para agregar un script especifico de página que colocaremos en la sección <head> de nuestra página usamos el ayudante de vista HeadScript. Los métodos de este ayudante se resumen abajo en la tabla 6.1:

Tabla 6.1. Métodos que provee el ayudate de vista HeadScript

Método	Descripción
`appendFile()`	Coloca un enlace a un archivo JS externo después de todos los otros.
`offsetSetFile()`	Inserta un enlace a un archivo JS externo en una posición determinada dentro de la lista.
`prependFile()`	Coloca un enlace a un archivo JS externo antes que todos los otros.
`setFile()`	Limpia la lista de scripts y coloca solo el archivo JS externo que se indicó.
`appendScript()`	Coloca un script en línea después de todos los otros.
`offsetSetScript()`	Inserta un script en línea en una posición dada de la lista.
`prependScript()`	Coloca un script en línea antes de todos los otros scripts.
`setScript()`	Limpia la lista de scripts en línea y coloca solo el script en línea dado.

Para agregar un enlace a un archivo JS externo en la sección <head> de la página agregamos el siguiente código PHP al comienzo de nuestro archivo de plantilla de vista (.phtml):

<?php
$this->headScript()->appendFile('/js/yourscript.js', 'text/javascript');
?>

En el código de arriba llamamos al método appendFile() del ayudante de vista HeadScript. Este método toma dos argumentos. El primero de ellos es la ruta al archivo JS externo (si el archivo se guarda dentro del directorio APP_DIR/public/js o una URL a un archivo JS que está ubicado en otro servidor web). El segundo argumento es el tipo de script (generalmente este valor es igual "text/javascript").

Otros métodos que provee el ayudante de vista HeadScript; como prependFile(), offsetSetFile() y setFile(); se diferencian solo por la posición en la lista de scripts donde el nuevo script se insertará.

Los métodos prependScript(), appendScript(), offsetSetScript() y setScript() se diseñan para insertar código JavaScript en línea. Ellas se usan raramente porque generalmente insertamos scripts JS externos en la sección head del documento.

Para insertar un script al final de la sección <body> del documento podemos usar el ayudante de vista InlineScript ¹⁵. Este provee exactamente los mismos métodos que el ayudante HeadScript. Abajo presentamos un ejemplo de como se puede agregar código JavaScript en línea al final del cuerpo del documento.

¹⁵⁾ El nombre InlineScript no refleja con exactitud las capacidades de este ayudante de vista. Este, en realidad, puede insertar tanto script en línea como externos. La mejor forma de nombrar a este script debería ser BodyScript porque él está destinado para insertar scripts en el cuerpo del documento.

<?php
$script = <<<EOT
  $(document).ready(function() {
    alert('Hello World!');
  });
EOT;
$this->inlineScript()->appendScript($script);

En el ejemplo de arriba usamos la sintaxis Heredoc ¹⁶ de PHP para llenar la variable $script con el código JavaScript en línea. Luego llamamos a la función appendScript() del ayudante de vista InlineScript y le pasamos el código como argumento.

¹⁶⁾ Heredoc es un método alternativo provisto por PHP que permite definir cadenas de caracteres. Este método trabaja bien con cadenas de caracteres de multiples líneas.

Sin embargo usar el ayudante de vista InlineScript puedo no se conveniente si pensamos en la legibilidad. Además, el corrector de sintaxis de editores de texto como NetBeans fallan al detectar la notación Heredoc y no reconocerán el código JavaScript. Para reparar este problema simplemente podemos colocar el elemento <script> al final de nuestra plantilla de vista como se muestra en el ejemplo de abajo:

<!-- Page content goes first -->

<!-- Inline script goes last -->
<script type="text/javascript">
  $(document).ready(function() {
    // Show a simple alert window with the "Hello World!" text.
    alert("Hello World!");
  });
</script>

Con esto logramos el mismo efecto que con el ayudante de vista InlineScript pero esta manera mejora la legibilidad del script y la sintaxis es automáticamente revisada por NetBeans.

Es necesario que el contenido se imprima en la plantilla de vista para que los ayudantes de vista HeadScript y InlineScript funcionen (como se muestra en las líneas 23 y 62 del archivo layout.phtml). Si quitamos estas líneas de la plantilla de maqueta los scripts no se insertaran in la página web.

6.7.1. Ejemplo

A manera de ejemplo realista insertaremos un pedazo de código JavaScript en nuestra página web que nos permitirá agregar la característica de autocompletado. Con esta característica el navegador web predirá una palabra o frase a partir de las primeras letras que el usuario escriba evitando que él escriba el texto completo. Podemos usar la biblioteca de JavaScript Twitter Typeahead. Análogamente a Twitter Bootstrap la biblioteca Typeahead fue desarrollada por Twitter Inc. para satisfacer sus necesidades pero se distribuye libremente.

Descargamos el archivo typeahead.min.js (la versión miniaturizada de la biblioteca Typeahead) desde la página oficial del proyecto. Cuando la descarga termina colocamos el archivo en la carpeta APP_DIR/public/js.

Luego agregamos el archivo typeahead.phtml a la subcarpeta application/index/static que esta dentro de la carpeta view del módulo. El tipo de ruta StaticRoute, que creamos y configuramos antes en el capítulo Routing, usa esa carpeta y hace que todas las páginas "estáticas" que se colocan allí estén automáticamente disponibles para todos los usuarios del sitio,

En el archivo de plantilla de vista typeahead.phtml colocamos el siguiente código:

<?php
$this->headTitle('Typeahead');
// Add a JavaScript file
$this->headScript()->appendFile('/js/typeahead.min.js', 'text/javascript');
?>

<h1>Typeahead</h1>
<p>Type a continent name (e.g. Africa) in the text field below:</p>
<input type="text" class="typeahead" title="Type here"/>

<script type="text/javascript">
  $(document).ready(function() {
    $('input.typeahead').typeahead({
       name: 'continents',
       local: [
            'Africa',
            'Antarctica',
            'Asia',
            'Europe',
            'South America',
            'North America'
        ]
    });
  });
</script>

En el código de arriba colocamos el título de la página (línea 2) luego agregamos el archivo typeahead.min.js a la sección <head> de la página con el ayudante de vista HeadScript (línea 4).

En la línea 9 creamos un campo de texto de entrada donde los usuarios serán capaces de escribir algún texto. Marcamos el campo de entrada con la clase CSS typeahead.

Las líneas 11-25 contienen código JavaScript en línea colocado al final de la plantilla de vista (no usamos el ayudante de vista InlineScript en procura de mejorar la legibilidad).

En la línea 12 tenemos el administrador de eventos de jQuery asociado al evento "document is ready". Este evento se lanzá cuando el árbol DOM se ha cargado.

En la línea 13 tenemos el selector jQuery ("input.typeahead") que selecciona todos los campos input marcados con la clase CSS typeahead y ejecuta la función typeahead() en ellos.

La función typeahead() vincula al administrador de eventos con algún cambio en el campo de texto input. Una vez que el usuario ingresa un carácter en el campo el administrador se ejecuta y revisa las letras introducidas. Luego se muestra un menú desplegable con las variantes sugeridas por el autocompletado.

La función typeahead() toma dos argumentos: el argumento name identifica el conjunto de datos y el argumento local es un arreglo JSON que contiene las variables disponibles para la autocompletación.

Para dar al campo de autocompletación y a su menú desplegable una apariencia visual agradable agregamos las siguientes reglas CSS a nuestro archivo style.css.

.typeahead,
.tt-query,
.tt-hint {
  width: 396px;
  height: 30px;
  padding: 0px 12px;
  font-size: 1.1em;
  border: 2px solid #ccc;
  border-radius: 4px;
  outline: none;
}

.tt-dropdown-menu {
  width: 422px;
  margin-top: 12px;
  padding: 8px 0;
  background-color: #fff;
  border: 1px solid #ccc;
  border: 1px solid rgba(0, 0, 0, 0.2);
  border-radius: 4px;
}

.tt-suggestion {
  padding: 3px 20px;
  font-size: 1.1em;
  line-height: 24px;
}

.tt-suggestion.tt-is-under-cursor {
  color: #fff;
  background-color: #0097cf;
}

.tt-suggestion p {
  margin: 0;
}

Para ver la característica de autocompletación trabajando escribimos la URL "http://localhost/typeahead" en nuestro navegador web y presionamos Enter. La página Typeahead aparecerá con el cursor en el campo dispuesto para ingresar un nombre. Por ejemplo, al escribir a letra a veremos como Typeahead sugiere las variables disponibles (figura 6.7).

Figura 6.7. Característica Auto-complete

Podemos ver el ejemplo trabajando en la aplicación Hello World que se añade a este libro escribiendo la URL "http://localhost/typeahead" en el navegador web.