viernes, 7 de octubre de 2011

Jugando con KumbiaPHP


Aunque ya he trabajado con KumbiaPHP en este blog, me tomaré unas 2 o 3 entradas, a manera de tutorial para explicar algunos aspectos del framework.

KumbiaPHP es un framework sumamente sencillo de usar y sobre todo práctico, implementa el patrón MVC y es además muy liviano, comparado con otros frameworks populares.

Otras razones para utilizar KumbiaPHP: está escrito en español, por hispanohablantes y se caracteriza por ser muy muy rápido. Aquí un benchmarking para comparar rendimiento con algunos frameworks.

Lo primero que debemos hacer es descargar la librería. Al momento de escribir este tutorial, la última versión oficial es la v1.0 Spirit, que se puede descargar desde la web. Sin embargo, mi recomendación es uitlizar la versión de desarrollo, que se encuentra en una fase estable y contiene muchas mejoras con respecto a la v1.0. Esta última, podemos descargarla del repositorio en launchpad. Es con esta versión que trabajaré en lo sucesivo.

Bien, luego de descargar, descomprimimos el archivo en nuestro directorio web y obtendremos la siguiente estructura:

kumbiaphp/
|--core
|--default
|--.htaccess

Para verificar que todo vaya bien, en un navegador vamos a la url de nuestro site, y debería mostrarse la página de bienvenida de kumbia.

Ahora detallemos un poco los directorios que vienen por omisión.

En core encontraremos todos los archivos del framework. En core/vendors están todas las bibliotecas externas que utiliza kumbia (es aquí donde debemos colocar cualquier biblioteca que necesitemos), y en core/libs están las bibliotecas desarrolladas/mantenidas por kumbia.

Con la descarga, viene un directorio default, el cual contiene una aplicación que sería la aplicación por omisión. Al mismo nivel de default podemos crear todas las aplicaciones que querramos.

En lo sucesivo trabajaré con default, pero repito, podemos crear otros directorios si queremos. Dentro de default, encontramos 2 subdirectorios: default/app y default/public. En el primero irá el core de nuestra aplicación, mientras que en el segundo almacenaremos todos los recursos (imágenes, scripts, hojas de estilo, archivos flash, etc) que se utilizarán en las páginas webs de nuestra aplicación.

En default/app/config están los archivos de configuración de nuestra aplicación. En default/app/models, default/app/views y default/app/controllers estarán los modelos, vistas y controladores.

Dentro de views/_shared/templates, está la plantilla por defecto: default.phtml (se usará en todas las vistas en las cuales no especifiquemos otra plantilla). En view/_shared/templates podemos guardar todas las plantillas que queramos y utilizarlas cuando sea necesario.


Un poco sobre MVC

No se trata de un tutorial del patrón MVC, así que daré sólo los detalles necesarios. Cada controlador está implementado como un archivo con nombre nombre_controller.php en el subdirectorio app/controllers. Por ejemplo, si queremos un cotrolador "principal", crearemos un archivo principal_controller.php. Este archivo es básicamente una clase, de nombre nombreController, heredada de AppController, con una serie de métodos públicos, que serían las acciones de nuestro controlador.

Por cada controlador, debe existir un subdirectorio en app/views con el mismo nombre de nuestro controlador. Por cada acción debe existir un archivo con extensión .phtml en este subdirectorio. Por ejemplo, si nuestro controlador principal tiene las acciones bienvenida y despedida, en app/views crearemos un directorio principal, que debe contener los archivos bienvenida.phtml y despedida.phtml.

La siguiente imagen, tomada del wiki de kumbia muestra cual es la relación entre controladores/acciones y URLs:



Esto si core y default están en el directorio raiz del directorio web del servidor. En nuestro caso, no es así, sino que están dentro de otro directorio que creamos dentro del directorio web del servidor y que hemos llamado kumbiaphp, por lo que nuestras rutas serían del tipo http://dominio/kumbiaphp/controller/action.

Sin mayor preámbulo, creamos nuestro primer controlador (principal_controller.php):

<?php 
class PrincipalController extends AppController {
    public function bienvenida() 
    {
        $this->bienvenida = "Bienvenido a KumbiaPHP";
    }

    public function despedida() 
    {
        $this->despedida = "Vuelve pronto";
    }
}
?>

Nuestra primera vista (bienvenida.phtml):

<h1>KumbiaPHP</h1> 
<p><?php echo $bienvenida ?></p>

Y nuestra segunda vista (despedida.phtml):

<h1>KumbiaPHP</h1> 
<p><?php echo $despedida ?></p>

Ahora si en el navegador vamos a http://localhost/kumbiaphp/principal/bienvenidahttp://localhost/kumbiaphp/principal/despedida, veremos los mensajes correspondientes a cada vista.

Debemos notar que aunque en las vistas sólo hay un par de líneas, en el navegador se ve nuestro contenido, enmarcado en la plantilla por omisión (default.phtml). Podemos modificar o sustituir esta plantilla por una nuestra. Sólo debemos tener presente 2 cosas:
  • No debemos eliminar la línea <?php View::content(); ?>, pues esa es la instrucción que le dice al framework que muestre el contenido propio de la vista (y en qué lugar dentro de la plantilla hacerlo).
  • La sintaxis para la inserción de contenido, que explicaré a continuación.


Incluyendo contenido en una plantilla

Bien sea que sustituyamos default.phtml, o que creemos una nueva plantilla, tenemos que saber como se incluyen ciertos elementos en nuestras vistas, a través de los numerosos helpers que provee el framework.

Para incluir correctamente archivos css:

<?php Tag::css('wide-blue/style') ?>
<?php echo Html::includeCss() ?>

Esto supone que tenemos un archivo style.css, y está ubicado en el subdirectorio app/public/css/wide-blue.

Para incluir imágenes:

<?php echo Html::img("lvbp.jpg"); ?>

Para incluir enlaces:

<?php echo Html::linkAction("enlace", 'Titulo') ?>

Para que estos helpers funcionen, debemos recordar que debemos guardar las imágenes, css y javascripts en los directorios correspondientes dentro de app/public.

En la próxima entrega...

De momento, con esto es suficiente para que elaboremos una o más plantillas y dejemos el entorno a punto para trabajar. Ya sabemos que para enviar información del controlador a la vista, basta con definir en el último, una variables $this->nombre_variable y luego en la vista podremos accederla como $nombre_variable. No hemos hablado de modelos porque no ha sido necesario, lo haremos en la siguiente entrega, al igual que el pase de datos desde las vistas hacia los controladores.




miércoles, 5 de octubre de 2011

martes, 4 de octubre de 2011

Bloquear interfaz con jQuery

Sigo en la onda de jQuery, esta vez con un plugin muy útil cuando trabajamos con ajax.

Es una práctica muy común hoy en día, realizar solicitudes POST o GET mediante ajax, de esta forma no tenemos que recargar la página completa cada vez, sino una pequeña parte de la misma.


Seguramente hemos visto en algun sitio que cuando subimos una foto a un servidor o realizamos alguna consulta, toda la interfaz se bloquea y aparece en medio un mensaje que nos informa que la página está realizando alguna tarea, que esperemos.

Esto se hace por 2 motivos. El primero es informarle al usuario que ya se está procesando su solicitud; el segundo, que viene a ser consecuencia del primero, es evitar el doble envío de data. Si por ejemplo lo que el usuario está realizando es una búsqueda compleja y no se le informa que ya se está procesando, al pasar unos segundos, el usuario puede pensar que el navegador no "agarró" la orden y volver a presionar el botón de envío, e inclusive hacerlo varias veces al no ver respuesta. Peor aún, si se trata de una inserción en base de datos, la data podría estar insertándose varias veces, lo cual sería fatal.

Bloqueando la interfaz, resolvemos los 2 problemas: le informamos al usuario que su solicitud se está procesando y a la vez protejemos nuestra aplicación de múltiples envíos de data. Esto le da además un comportamiento síncrono a nuestras aplicaciones asíncronas.

¿Cómo lo hacemos? Bien, con un poco de manejo del DOM y CSS podemos lograr el efecto, sin embargo, para jQuery ya existen varios plugins para hacerlo de forma realmente simple. Uno de ellos, se llama BlockUI, y su uso es tan sencillo como incluir el plugin, por supuesto, y luego lo usamos de la siguiente forma.

Para bloquear la pantalla:

$.blockUI({ message: '<h1><img src="busy.gif" /> Por favor espere...</h1>' });

Para desbloquear la pantalla:

$.unblockUI();

Si queremos que la interfaz se bloquee, cada vez que hacemos una solicitud ajax y se desbloquee al terminarla:

$(document).ajaxStart($.blockUI).ajaxStop($.unblockUI);

Supongamos que tenemos un formulario para buscar datos de clientes y mostrarlos en una tabla. Con jQuery ponemos un manejador al submit del formulario, para que realice la búsqueda por POST via ajax e incruste el código HTML de la tabla en un DIV que tengamos destinado para tal fin, podemos bloquear/desbloquear la interfaz de la siguiente manera:

<script type="text/javascript">
$(function() {
	$('#formulario').submit(function() {
		var url = $(location).attr('href');
		var key = $('#keyword').val();

		$.blockUI({ message: '<h1><img src="busy.gif" /> Por favor espere...</h1>' });

		$.post( url,
		{ search_key: key },
			function(data){
			var datos = $('#divdatos');
			datos.html(data);
			$.unblockUI();
		});
		return false;
	});
});
^lt;/script>

Si queremos que la interfaz se desbloquee después de cierto tiempo, podemos hacerlo con la función setTimeout:

setTimeout($.unblockUI, 2000);


Como siempre, recomiendo ir directamente a la fuente y revisar todos los demos, que se pueden hacer muchas más cosas.

Formato de números en PHP

Trabajar con números y fechas es una de las cosas más fastidiosas que se le presentan a todo programador. El formato de los datos, la compatibilidad de formatos con manejadores de base de datos, etc. Sin embargo, casi en toda aplicación, toca.

Dependiendo del ambiente/plataforma en que trabajemos se pueden tener soluciones más o menos eficientes. Sin embargo, muchas veces se da el caso en que no podemos hacer mucho a nivel de archivos de configuración porque no tenemos acceso a ellos, o que simplemente la aplicación no requiere mayor trabajo.

En PHP, si lo que queremos es presentar algunos números que sacamos de base de datos o producto de ciertas operaciones matemáticas, por ejemplo, podemos utilizar la función number_format(), cuyo prototipo es el siguiente:

string number_format ( float $number [, int $decimals = 0 ] )
string number_format ( float $number , int $decimals = 0 , string $dec_point = '.' , string $thousands_sep = ',' )


Muy simple. Podemos simplemente decirle el número (o variable que contiene el número) y cuantos decimales queremos que muestre, y además podemos decirle qué separador decimal y de miles utilizar.

<?php

$number = 1234.56;

// notación inglesa (por defecto)
$english_format_number = number_format($number);
// 1,235

// notación inglesa con 3 decimales
$english_format_number2 = number_format($number, 3);
// 1,235.560

// notación francesa
$french_format_number = number_format($number, 2, ',', ' ');
// 1 234,56

// notación inglesa sin separador de miles
$english_format_number3 = number_format($number, 2, '.', '');
// 1234.57

?>

lunes, 3 de octubre de 2011

jQueryUI datepicker

En entradas anteriores he trabajado un poco con jQuery, una de las mejores bibliotecas JavaScript (y de las más fáciles de usar) que existen hoy en día. Todo el mundo debería utilizarla.

Todo el mundo debería utilizar también jQueryUI, una biblioteca de componentes gráficos/visuales para jQuery. Uno de los aspectos más destacables de jQuery/jQueryUI es el de la compatibilidad; cuantos dolores de cabeza te quita de entrada, al saber que cualquier componente que utilices, será compatible con los grandes navegadores.

En esta entrada, abordo uno de los widgets de jQueryUI: el datepicker. Muy elegante, funcional y sencillo de manipular. Incluir uno, es tan sencillo como colocar este código:

<script>
  $(function(){
    $("#datepicker").datepicker();
  });
</script>

<div class="demo">
<p>Date: </p>
</div>

Es sólo colocar un input de tipo texto, y con un sencillo script datepickficarlo. Lógicamente, nos gustaría especificar ciertas opciones, como poner los nombres en español, seleccionar alguna fecha por defecto, especificar el formato de la fecha, etc. Bien, todo esto (y más) es posible, gracias a la gran cantidad de opciones y métodos que provee el widget. Veamos un ejemplo más completo:

<script>
	$(function(){
		$("#datepicker").datepicker({
			autoSize: true,
			dayNames: ['Domingo', 'Lunes', 'Martes', 'Miércoles', 'Jueves', 'Viernes', 'Sábado'],
			dayNamesMin: ['Dom', 'Lu', 'Ma', 'Mi', 'Je', 'Vi', 'Sa'],
			firstDay: 1,
			monthNames: ['Enero','Febrero','Marzo','Abril','Mayo','Junio','Julio','Agosto','Septiembre','Octubre','Noviembre','Diciembre'],
			monthNamesShort: 'Ene','Feb','Mar','Abr','May','Jun','Jul','Ago','Sep','Oct','Nov','Dic'],
			dateFormat: 'dd/mm/yy',
			changeMonth: true,
			changeYear: true});
 		                
	});
</script>

En este segundo ejemplo hemos agregado algunas opciones. Por ejemplo, hemos especificado los nombres de los días de la semana con dayNames y dayNamesShort, también hemos especificado los nombres de los meses con monthNames y monthNamesShort y hemos dicho que tanto los meses como los años se podrán cambiar a partir de listas desplegables, con changeMonth y changeYear.

Así podemos especificar muchas otras opciones. Es bueno ver la lista completa en la documentación oficial del widget aquí.

Cuando se despliega el calendario, vemos que por omisión aparece seleccionada la fecha actual (de la máquina en la que estamos). Esta es una opción que podemos cambiar, con la opción defaultDate. Por ejemplo, podríamos agregar algo como defaultDate: '03/10/2011' (debe ser consistente con el formato de fecha dateFormat) y siempre aparecerá seleccionada la fecha 3 de octubre de 2011. También, podemos especificar alguna otra fecha que obtengamos dinámicamente.

Sólo hay que estar claro en que con defaultDate especificamos la fecha que aparece por omisión al levantar el calendario, de ninguna manera esto significa que si no se selecciona alguna, esta opción nos dará la fecha por defecto.

Si lo que queremos es modificar la fecha actual, esto debemos hacerlo a través del método setDate, que podemos utilizar en cualquier momento, como cualquier otro elemento de jQuery. Agreguemos un evento setDate al script anterior:

<script>
	$(function(){
		$("#datepicker").datepicker({
			autoSize: true,
			dayNames: ['Domingo', 'Lunes', 'Martes', 'Miércoles', 'Jueves', 'Viernes', 'Sábado'],
			dayNamesMin: ['Dom', 'Lu', 'Ma', 'Mi', 'Je', 'Vi', 'Sa'],
			firstDay: 1,
			monthNames: ['Enero','Febrero','Marzo','Abril','Mayo','Junio','Julio','Agosto','Septiembre','Octubre','Noviembre','Diciembre'],
			monthNamesShort: 'Ene','Feb','Mar','Abr','May','Jun','Jul','Ago','Sep','Oct','Nov','Dic'],
			dateFormat: 'dd/mm/yy',
			changeYear: true});

		var myDate = "'"+ <?php echo $_SESSION['fecha_hoy'] ?>+"'";
		$("#datepicker").datepicker('setDate', myDate);
 		                
	});
</script>

En este ejemplo, asumimos que estamos trabajando en PHP y que tenemos en sesión una variable 'fecha_hoy' y esa es la fecha que le asignamos al datepicker, justo después de su creación. Podemos utilizar el mismo método en cualquier otra parte del documento, por supuesto.

Otra opción interesante es disabled, la cual dice si el widget estará deshabilitado (true) o habilitado (false).

Si queremos que nuestro datepicker tenga una fecha por defecto y además esté bloqueado, debemos deshabilitar el widget posterior a que hemos asignado la fecha. Cierro la entrada, precisamente con este ejemplo:

<script>
	$(function(){
		$("#datepicker").datepicker({
			autoSize: true,
			dayNames: ['Domingo', 'Lunes', 'Martes', 'Miércoles', 'Jueves', 'Viernes', 'Sábado'],
			dayNamesMin: ['Dom', 'Lu', 'Ma', 'Mi', 'Je', 'Vi', 'Sa'],
			firstDay: 1,
			monthNames: ['Enero','Febrero','Marzo','Abril','Mayo','Junio','Julio','Agosto','Septiembre','Octubre','Noviembre','Diciembre'],
			monthNamesShort: 'Ene','Feb','Mar','Abr','May','Jun','Jul','Ago','Sep','Oct','Nov','Dic'],
			dateFormat: 'dd/mm/yy',
			changeYear: true});

		var myDate = "'"+ <?php echo $_SESSION['fecha_hoy'] ?>+"'";
		$(\"#" . $field . "\").datepicker('setDate', myDate);
		$(\"#" . $field . "\").datepicker( 'option', 'disabled', true);
 		                
	});
</script>

Sólo agregamos una línea de código al final, que dice que la opción disabled a partir de ese momento, comienza a tener el valor true, por lo que no se podrá seleccionar ninguna otra fecha. Posteriormente, por supuesto, podemos habilitar el widget, volver a deshabilitarlo, volver a habilitarlo, etc. Eso sí, si esto es parte de un formulario y al momento de enviarlo, el widget está deshabilitado, también lo estará el input, y por tanto NO se enviará el campo, así que pendiente.

Espero la entrada haya sido de utilidad.