Ofrece una ventana modal, creando una capa emergente que recubre parcialmente al documento activo y se apodera del control para mostrar información, de lectura obligatoria, que interpola una respuesta mínima de usuario antes de continuar el proceso normal. Incorpora un mecanismo de cierre, que puede adicionalmente responder a la tecla [escape]. Es útil para presentar información de errores, trámites, etc., al usuario y para recoger confirmación a acciones, o pequeños grupos de datos auxiliares. Siempre que no sea necesario o no haya posibilidad de requerir la presentación de un segundo dialogo mientras se encuentre visible.
Se debe tener presente que debe contar con un mecanismo disparador a no ser que sólo se vaya a mostrar cuando la página es cargada; y que luego de ser cerrado no se necesite.
Según la documentación en la página oficial de Twitter-Bootstrap no está soportado el uso de múltiples instancias del dialogo modal y en caso de desearlo requiere de escritura de código adicional complejo. Para resolver este tema, la biblioteca "Php - BiblioTools" ofrece el objeto "Ventana emergente" que si las admite.
Esta clase usa el array de definición del elemento como único parámetro de su constructor. No obstante, el acento de la definición está puesto en el subarray bajo la clave 'buildVars' que debe contener la mayoría de los valores de inicialización.
Los elementos del Api "Foliate/FormAPI" ofrecidos por el sistema extensor de módulos incorporan
un mecanismo de autocarga, instanciación e invocación del dialogo modal, que se activa
estableciendo a TRUE su atributo "#requiere_dialogo_modal" de modo que para invocarlo en
cualquier parte del código basta con escribir el llamado javaScript
MostrarDialogoModal(tit, msg, '', '', '', '', '0')
Importante: En caso de que se desee usarlo creando instancias que van a ser llamadas desde objetos específicos, no debe ser creado usando ComponentFactory pues es fundamental atrapar su ID para pasarlo a otros elementos antes de servir la página. Podría olvidarse leer el id, pues ComponentFactory puede entregar el objeto renderizado y su id no estaría disponible. Los scripts usados en la página deberían buscarlo, identificar el dialogo y servirlo haciendose más difíciles.
'buildVars' => [
'title' => 'título_del_dialogo' | <ninguno>,
// El constructor le asigna el id ID_DEL_DIALOGO-title para facilitar la escritura
// de selectores en JavaScript, en caso de necesitar modificarlo.
'efecto' => 'nombre_del_efecto' | '' /* para ninguno */ | default = 'fade',
// Se debe pasar una cadena nula para anular el efecto por defecto. Otros efectos
// pueden ser consultados en la documentación de jQuery.
'body' => htmlString,
// Cualquier cadena HTML válida que se desee mostrar como mensaje o contenido
// del dialogo.
'buttons' => ['btnKey1' => (array) btnDef1,..., ] | no asignar para ninguno,
// Es un array de pares de la forma: Clave del botón => Definición del botón.
// Si se piensa usar un botón de tipo cancel, que cierre el dialogo, su clave
// debe ser 'cancel'.
// Se puede especificar etiquetas explícitas para los botones usando la clave
// 'label' en sus arrays de definición.
// Como el dialogo incluye por defecto un botón de cierre en la esquina superior
// derecha puede no necesitarse ninguno. Los botones se muestran en el footer.
'size' => 'lg' | 'sm' | 'xs' | default es 'md' (medium)
// Constante literal de BS que define el ajuste del dialogo en la ventana.
]; El dialogo modal mostrado al desplegar la página corresponde a una prueba automática de autocarga que se lanza cuando ha sido asignada la variable de entorno: 'lgq_modal_selftest' mediante el llamado: \Biblio2ls\Library\Js2l::addSetting('lgq_modal_selftest', 1);
La activación de dialogos modales depende de que se pueda ejecutar JavaScript
en el navegador. Pero, Twitter-Bootstrap ofrece una variante que hace posible
usarlos sin escribir código JS explícito.
Hay dos mecanismos para activar los dialogos modales:
En el primer caso, el control debe tener asignadas dos propiedades: data-toggle y data-target que lo ligan al dialogo ejemplo:
tiene la siguiente definición:
<button class="btn btn-primary" type="button" data-toggle="modal" data-target="#dialogomodal1">Abrir dialogo</button>
y como enlace (para abrir el dialogo) Ver buildVars se define así:
<a data-toggle="modal" href="#" data-target="#dialogomodal1">Ver buildVars</a>
El dialogo, se generó con el siguiente juego de instrucciones:
// Usa la entidad BsHtmEntity para evitar escribir toda la definición
$defPad = new \TwBs2l\Entity\BsHtmEntity();
// Asigna los parámetros específicos del dialogo (son sólo 3 en este caso)
$defPad->buildVars = [
'title' => 'Dialogo modal 1',
'size' => 'lg',
'body' => $builvarsCmt, // texto de presentación de buildVars
];
$dialogoDef = $defPad->toArray(); // prepara la definición a usar
// crea la instancia del dialogo
$dialogo = new \TwBs2l\Component\BsModal($dialogoDef);
// toma el Id para pasarlo a los controles activadores
$dialogoID = $dialogo->getId();
// Inserta el dialogo en la página
echo $dialogo->toString();
En el segundo caso: es necesario insertar en la página el script:
// llamado usando selectores jQuery
$('#dialogoId').modal('show');
// abre el dialogo. Este llamado debe estar localizado en algún procedimiento
// de evento
Hay una documentación exígua del asunto en la página
oficial de Twitter-Bootstrap.Como extensión de la clase BsModal se ofrece un dialogo modal estándar, con código javascript asociado para mostrar ventanas de confirmación y mensajes típicos pequeños, completamente configurado y listo para operar. Se puede invocar usando ComponentFactory con un parámetro simple:
echo \TwBs2l\Factory\TwBsFactory::getBsElement(['tipoDeElemento' => 'dialogo-modal']);La clase controladora se encarga de todo, incluso de agregar los scripts y hojas de estilo css necesarios.
= '<button class="btn btn-success" type="button" data-show="modal" data-toggle="modal" data-target="#dialogo-modal">Abrir dialogo modal</button>'
$formsamplebuttons_keylabel = [
'samplebtnaceptar' => 'Aceptar',
'samplebtncancelar' => 'Cancelar',
'samplebtnaceptcancel' => 'Aceptar o cancelar',
'samplebtnsiono' => 'Si o no',
'samplebtnsinocancel' => 'Si, no, cancelar',
'samplebtnsitodosno' => 'Si a todo, si, no',
];
$btnentity = new \TwBs2l\Entity\BsHtmEntity(); $btnentity->tagName='button'; $btnentity->tipoDeElemento = 'btn'; $btnentity->clases = ['btn', 'btn-default', 'formsample-button'];
$samplebutonsarray = []
foreach($formsamplebuttons_keylabel as $btnkey => $labeltxt){
// Iteración asignando propiedades específicas
$btnentity->id = $btnkey;
$btnentity->attributes = ['id' => $btnkey];
$btnentity->innerHtm = $labeltxt;
// Extrae el array de definición de la entidad
$newbttndef = $btnentity->toArray();
// instancia el botón
$newbutton = new \TwBs2l\Component\BsButton($labeltxt, $btnkey, '', 0, '', $newbttndef);
$newbutton->rebuildFromDef();
// y lo agrega al array de button para construir el grupo
$samplebutonsarray[] = $newbutton;
}
// Crea el grupo de botones:
// definición de grupo, no necesita nada más
$gbdef = [ 'clases' => ['btn-group-sm'], ]; //para que sean botones pequeños
// creación de instancia
$samplebutonsgroup = new \TwBs2l\Component\Group('btn-group', $samplebutonsarray, $gbdef);
// lo agrega (envía) a la página a servir
echo $samplebutonsgroup->toString();campo de encabezado
<input type="text" class="form-control"
placeholder="Encabezado" aria-describedby="sample-head-label"
id="edit-sample-head" name="sample-head"/>
área del mensaje
<textarea id="edit-sample-body" name="sample-body"
placeholder="Escriba el contenido que desea mostrar como mensaje"
rows="3" aria-labelledby="sample-body-label" style="width :100%;"
value=""></textarea>// FILE: js/biblio2ls/samples/bsmodalformsample.js
$(document).ready(function(){
var iddlg = {
samplebtnaceptar : '0',
samplebtncancelar : '5',
samplebtnaceptcancel : '1',
samplebtnsiono : '3',
samplebtnsinocancel : '2',
samplebtnsitodosno : '4',
};
$('.formsample-button').bind('click', function(event){
event.preventDefault();
event.stopPropagation();
var key = '' + $(this).attr('id');
var optn = iddlg[key];
var tit = '' + $('#edit-sample-head').val();
var txt = '' + $('#edit-sample-body').val();
$('.formsample-button').removeClass('btn-primary');
$(this).addClass('btn-primary');
MostrarDialogoModal(tit, '' + txt, '', '', '', '', optn);
return 0;
});
});\Biblio2ls\Library\Js2l::addFile('js/biblio2ls/samples/bsmodalformsample.js', 10);