Actualizaciones:

Esta documentación era la que inicialmente se creó y sigue respetándose. Pero desde entonces se han agregado nuevas variables, propiedades y métodos. Para ver las actualizaciones consulte el tema introductorio de Formularios emergentes así como los códigos que actualmente se están usando:

Constructor

formEmerge(nombreForm
[,cadenaTitulo
[,conPantalla
[,conBotones
[,moverForm
[,accionEnvio
[,metodoEnvio
[,dondePonerForm]]]]]]])
  • nombreForm: Un string obligatorio para el nombre de formulario que será exactamente igual que la variable declarada. Es un argumento obligatorio.
  • cadenaTitulo: Un string opcional para el título que aparecerá en la cabecera de la ventana emergente. Si no se pasa el argumento se tomará el nombre de la variable anterior como título por defecto.
  • conPantalla: Un booleano opcional. Con true se antepone a la ventana emergente una pantalla con transparencia para que el usuario se vea obligado a actuar con el formulario y no con otras partes de la página. Por defecto el valor será false, sin pantalla.
  • conBotones: Un entero opcional. Con el valor 1 se incluye un botón aceptar, con 2 los botones aceptar y cancelar, con 3 se ponen los botones aceptar, cancelar y aplicar. Con 0 o cualquier otro valor o si no se pasa el argumento, no se incluyen botones.
  • moverForm: Un string opcional. Con el valor "todo" se podrá mover el formulario arrastrándolo con el ratón. Con el valor "marco" aparecerá un rectángulo de igual tamaño que el formulario que nos permite moverlo y, al soltar el botón del ratón, se situará el formulario en ese sitio. Con el valor "nada" el formulario no podrá ser movido. El valor por defecto cuando no se pasa el argumento es "todo".
  • accionEnvio: Un string opcional que representa una URL para incluir en el atributo action del <form> del emergente y que sirva para enviar los datos del formulario al servidor. Si se pasa una cadena vacía "" no se usa el formulario para enviar datos.
  • metodoEnvio: Un string opcional con los valores "get" y "post" para incluir en el atributo method del formulario. Se usará "post" por defecto si no se pasa o es una cadena "" o un valor no válido.
  • dondePonerForm: Un string opcional que supone el identificador id de un elemento de bloque donde se construirá el formulario emergente. Si no se pasa se construye en el body del documento. En principio este es el lugar más adecuado, pues como se configuran en una capa superior con z-index, no interfiere en la presentación.

Globales

  • Constantes globales:
    • PID: Un String que supone un prefijo para los identificadores id de todos los elementos creados dinámicamente. Con ello evitamos que puedan producirse coincidencias con otros elementos externos.
    • PCL: Un string, prefijo en este caso para los nombre de clases, anteponiéndose en el atributo class.
    • MAX_TABS: Un número para impedir crear más pestañas que las indicadas.
  • Variables globales:
    • forms: Un array que almacena referencias a las instancias que se van creando. Con forms[n] obtenemos el objeto enésimo creado, no el elemento <form>, al cual podemos acceder con forms[n].form(), usando el método form() que explicamos más abajo con la exposición de métodos públicos.
    • formsAbiertos: Un entero que indica el número de formularios abiertos.
  • Funciones globales
    • cerrarFormularios(): Permite cerrar todos los formularios abiertos.
    • formRef(nombreForm): Dado un nombre de formulario podemos obtener la referencia al objeto, es decir, a la instancia de formEmerge, no al elemento <form> que, como expusimos antes, se puede acceder con el método form().

Propiedades

No es necesario acceder directamente a la mayoría de estas propiedades pues se gestionan con el constructor y los métodos descritos.
  • nombre: Un string con el mismo nombre de la variable con la que se construyó el formulario. Se recoge a partir del argumento nombreForm del constructor.
  • titulo: Un string para poner en la barra superior del formulario. Este título puede ser modificado con el argumento titulo del método abrir().
  • pantalla: Un booleano que con true indica que estamos usando una pantalla o capa de transparencia sobre la cual se abrirá el emergente. Inicialmente tiene el valor false.
  • botones: Un entero de 0 a 3 que recoge el argumento conBotones del constructor, tal como allí se explica. Inicialmente tiene el valor 0.
  • idObjetoRespuesta: Un string que almacena el identificador id del objeto respuesta.
  • respuesta: Un string que representa el valor del objeto respuesta.
  • eventoAbrir: Un string con un evento que se ejecutará al abrir el formulario.
  • eventoAceptar: Un string con un evento que se ejecutará con el botón aceptar.
  • eventoAplicar: Un string con un evento que se ejecutará con el botón aplicar.
  • eventoCancelar: Un string con un evento que se ejecutará con el botón cancelar.
  • eventoCerrar: Un string con un evento que se ejecutará con el botón cerrar.
  • ejecutaEventoAbrir: Un objeto function() que puede ser sobreescrito externamente para que se ejecute al abrir el formulario.
  • ejecutaEventoAceptar: Un objeto function() que puede ser sobreescrito externamente para que se ejecute con el botón aceptar.
  • ejecutaEventoAplicar: Un objeto function() que puede ser sobreescrito externamente para que se ejecute con el botón aplicar.
  • ejecutaEventoCancelar: Un objeto function() que puede ser sobreescrito externamente para que se ejecute con el botón cancelar.
  • ejecutaEventoCerrar: Un objeto function() que puede ser sobreescrito externamente para que se ejecute el botón cerrar.
  • botonPulsado: Un string que almacena "aceptar", "cancelar", "aplicar" o "cerrar" según que alguno de estos botones sea pulsado. Inicialmente o cuando abrimos el formulario o cuando se sale del mismo de forma imprevista, se almacena una cadena vacía.
  • abierto: Un booleano que indica si el formulario está abierto.
  • totalTabs: Un número entero que indica el total de pestañas que tiene la estructura del formulario.
  • mover: Un string que recoge el argumento moverForm del constructor. Puede ser "todo", "marco" o "nada".
  • iniciarMover: Un booleano de uso interno para controlar el movimiento del formulario.
  • xMover: Un entero de uso interno para controlar la posición horizontal al mover el formulario.
  • yMover: Un entero de uso interno para controlar la posición vertical al mover el formulario.
  • paraEnvio: Un booleano para uso interno, inicialmente false y que será true si se pasa el argumento accionEnvio.
  • accionEnvio: Un string que recoge el argumento del mismo nombre del constructor para que el formulario sirva para enviar datos (atributo action del elemento <form>).
  • metodoEnvio: Un string que recoge el argumento del mismo nombre del constructor para el atributo method del formulario.
  • idDondeForm: Un string que recoge el argumento dondePonerForm del constructor. Es el atributo id de un elemento de bloque donde se construirá el formulario. Si no se pasa o es "" se construye en el <body> del documento.

Métodos de uso público

Los denominamos públicos pues deberían ser los que exclusivamente se utilicen para el manejo externo de la clase. Sin embargo con esta implementación de JavaScript no hay diferenciación entre estos y los privados desde el punto de vista del acceso.
  • abrir([interior
    [,titulo
    [,izquierda
    [,arriba
    [,ancho
    [,alto
    [,sobresale
    [,foco]]]]]]]])
    Para abrir un formulario emergente, incorporar un interior, un título, posicionarlo en pantalla y situar el foco.
    • interior: Un string para poner en el interior del formulario. Admite literales HTML pues se usa innerHTML para incorporar esa cadena al formulario. Si no se pasa este argumento no se actualiza nada en el interior del formulario.
    • titulo: String para cambiar el título del formulario.
    • izquierda, arriba: Un entero que indica píxeles de la ubicación izquierda y arriba. Si no se pasan valores se sitúa en el punto (0,0) de la página.
    • ancho, alto: String que será el estilo de las propiedades width y height del interior del formulario, siendo por lo tanto valores como "5em", "100px", etc.
    • sobresale: String para el estilo de la propiedad overflow con sus valores visible, hidden, scroll, auto.
    • foco: Poner el foco en un elemento de control del formulario que sea capaz de recibir el foco. Puede ser un número entero correspondiente al número de orden dentro de la matriz de controles del formulario, una referencia a un elemento HTML o un string del identificador id del elemento.
  • nuevoInterior(html)
    El argumento html es un string para incorpora un literal HTML en el cuerpo interior del emergente sustituyendo todo lo que haya.
  • anexaInterior(html
    [,antesDespues])
    Con html siendo un string para anexar contenido HTML adicional, bien antes o después del contenido interior actual pasando el argumento antesDespues igual a los string "antes" o "despues". El argumento es opcional y por defecto toma el valor "despues".
  • creaTabs(arrayNombres
    ,arrayHtmls
    [,ancho
    [,alto
    [,antesDespues]]])
    Método para crear una estructura de pestañas en el cuerpo interior del formulario emergente.
    • arrayNombres: Un array con cadenas de texto para los nombres de las pestañas. Admite un literal HTML, como veremos en los próximos ejemplos.
    • arrayHtmls: Un array con el mismo número de cadenas de texto para los literales HTML de los correspondientes contenidos.
    • ancho: Un cadena para especificar el estilo CSS del ancho de la tabla que representa toda la estructura interior de pestañas. Inicialmente se dota de width="30em". Si no se especifica argumento, el ancho final viene condicionado por las pestañas, pues si sus título ocupan más de esos 30em, la tabla se alargará. Si el ancho es mayor que la suma de las pestañas, la tabla las redimensionará para adecuarlas al especificado en su propiedad width.
    • alto: De forma similar para dotar el estilo CSS al alto de la tabla. Inicialmente se le da width=5em. Si el contenido interior es más grande se abre la barra de desplazamiento vertical.
    • antesDespues: Un string con los valores "antes" o "despues" para anexar la estructura de pestañas antes o después del contenido interior que pueda existir ya en el emergente. Si no se pasa el argumento se anexa antes.
  • form([idElementoSinPrefijo
    [,omitirPrefijo]])
    Podemos obtener una referencia al elemento <form> del formulario para, entre otras cosas, acceder a sus controles internos. Puede ver ejemplos de este método en aspectos del diseño: acceso a los controles del formulario.
    • idElementoSinPrefijo: Si no se pasa el argumento, se devuelve una referencia al elemento <form>. En otro caso se espera recibir un string que es el identificador id del elemento que vamos a referenciar. Los identificadores de todos los elementos del formulario llevan el prefijo de la constante PID + this.nombre. Por lo tanto aquí hay que pasarlos sin ese prefijo si usamos omitirPrefijo = false o bien no pasamos ese argumento. En otro caso (true) el primer argumento se trata tal cual, sin añadirle ningún prefijo.
    • omitirPrefijo: Booleano opcional, se explica en el argumento anterior.

Métodos de uso privado

Como indicamos antes, estos serían métodos privados desde el punto de vista de que no es necesario usarlos externamente, pues están destinados a uso interno de la clase y es desde ahí donde se manipulan. Por supuesto, nada impide usarlos. Puede ver más información en los enlaces que conducen al código fuente de cada método.
  • activaTab(unTab)
    Visualiza un contenido de una pestaña cuando hacemos click en alguna.
  • aceptar()
    Se produce tras pulsar el botón de aceptar, poniendo la respuesta en objetoRespuesta.value y, en su caso, ejecutando el eventoAceptar. Pone botonPulsado = "aceptar" y cierra el formulario.
  • aplicar()
    Igual que el anterior pero no cierra el formulario y botonPulsado = "aplicar".
  • cancelar()
    Igual que aceptar pero no pone la respuesta en objetoRespuesta.value y botonPulsado = "cancelar".
  • cerrar()
    Actúa exactamente igual que el botón cancelar poniendo botonPulsado = "cerrar"
  • moverTodo(modo,evento)
    Ejecuta el movimiento del formulario moviéndolo completamente.
  • moverMarco(elemento,evento)
    Ejecuta el movimiento del formulario pero moviendo un rectángulo del mismo tamaño.
  • traerAlFrente()
    Trae al frente un formulario actuando sobre la propiedad de estilo z-index del elemento <form>.