Actualizado 11 de Junio 2010

En este tutorial explcaré el comportamiento de KumbiaPHP cuando hacemos aplicaciones ricas en JavaScript, me basare en utilizar jQuery como framework de JavaScript y no daré una explicación muy amplia de que son peticiones asíncronas ni como funcionan estas esto porque hay suficiente información en la red para quienes deseen indagar un poco mas, simplemente nos dedicaremos hacer peticiones asíncronas dentro de KumbiaPHP.

Como todo ejemplo lo ideal es basarlo en hechos reales y cotidianos en este sentido haremos un cliente que acorte URL utilizando el API del servicio SigueMiLink el cual fue desarrollado con KumbiaPHP :).

Requisitos

Antes de continuar hay que verificar lo que necesitamos para llevar acabo el tutorial.

• Tener funcionando KumbiaPHP Beta1 (Instalar KumbiaPHP)
• Descargar jQuery y colocarlo en el directorio app/public/javascript/jquery/jquery-1.4.2.min.js.
• Por lo menos haber hecho el ejemplo Hola Mundo de KumbiaPHP para entender este tutorial.
• Leer un poco el API del servicio SigueMiLink
• Ver funcionamiento básico de KumbiaPHP con AJAX

Empezamos

Lo primero es crear el controlador para efecto de este tutorial lo llame api mirar las convenciones de nombres de controladores si se te ocurre otro nombre mejor usalo, pero piensa que a lo largo del tutorial haré mención al controller api.

<?php
/**
 * Controller para utilizar el API de SigueMiLink
 * @author Deivinson Tejeda <deivinsontejeda@kumbiaphp.com>
 */
class ApiController extends ApplicationController
{
    /**
     * URL del API de SigueMiLink
     */
    private $_urlAPI = 'http://www.siguemilink.com/api/%s/?destination=%s';
    /**
     * Callback Before que verifica si la petición es Asíncrona...
     */
    public function before_filter()
    {
        if($this->is_ajax()){
            $this->set_response('view');
        }
    }
    /**
     * Form que se comunica con el API de SigueMiLink
     * para acortar el enlace
     *
     */
    public function acortar()
    {
        if($this->has_post('url')){
            //Reemplazo de valores en la URL del API.
            $this->_urlAPI = sprintf($this->_urlAPI, 'create', $this->post('url'));
            $this->response1 = json_decode(file_get_contents($this->_urlAPI));
            $this->render('response');
        }
    }
}

Ahora se crea la vista app/views/api/acortar.phtml que tiene un formulario que envia la URL al controller que será enviada al API de SigueMiLink.

<div style="margin: auto">
    <?php echo form_tag(array('api/acortar/', 'class'=>'form-remote')) ?>
        <label>Acorte tu enlace</label>
        <?php echo text_field_tag(array('url')) ?>
        <?php echo submit_tag('Enviar') ?>
    <?php echo end_form_tag() ?><br />
    <div id="update" style="margin: auto;"></div>
</div>
 
<?php echo javascript_include_tag('jquery/jquery-1.4.2.min'); ?>
<script type="text/javascript">
    <!--//--><![CDATA[//><!--
        $(function() {
            $(".form-remote").live('submit', function(event){
                event.preventDefault();
			    self = $(this);
			    var button = $('[type=submit]', self);
			    button.attr('disabled', 'disabled');
			    var url = self.attr('action');
			    //var div = self.attr('data-div');
			    $.post(url, self.serialize(), function(data, status){
				    var capa = $('#update');
				    capa.html(data);
				    capa.hide();
				    capa.show('slow');
				    button.attr('disabled', null);
			    });
            });
        });
    //--><!]]>
</script>

Creamos la vista que tiene la respuesta enviado desde el servicio que acorta la URL app/views/api/response.phtml

<?php if($response1->code == 2):?>
    <a href="http://smlk.es/<?php echo $response1->link?>/">http://smlk.es/<?php echo $response1->link?>/</a>
<?php else: ?>
    <strong>No se pudo acortar el enlace</strong>
<?php endif; ?>

Lo genial de este ejemplo es que funciona con o sin javascript para promover la accesibilidad web. Ahora explico un poco lo que hace el controller api, el método before_filter() es un filtro que se ejecuta antes de la acción en este caso verificamos si la petición es asíncrona y de serlo damos respuesta asíncrona, útil para centralizar y si la aplicación es muy rica en javascript no se tendra que tener esta validación en cada action del controller ;).

La action acortar() muestra el form y envia la petición (cuando se hace el submit) al servicio SigueMiLink para acortar la URL, con el método render() cambiamos de vista a renpose y como la petición se ha hecho asíncrona ya saben lo demas :).

En la vista acortar.phtml tenemos el formulario y con un JavaScript para enviar la petición asíncrona, en la documentación de jQuery se explican los métodos usados en este ejemplo en los cuales no me enfocare.

Es importante indicar el elemento del DOM que se actualizará luego de la petición, en este caso es un div con un identificador (id) update.

Es de notar que en la vista response no se analizan todos los códigos de error que devuelve el API de SigueMiLink, como tarea pueden hacer esto y dar respuesta al usuario de acuerdo al error retornado del servicio.

Importante

• Si no indicas que la respuesta será asíncrona KumbiaPHP cargará todo el template y por ende habran elementos de la vista que veras repetidos, así que no olvides el $this->set_response(‘view’).
• Saber que elemento del DOM se va actualizar

A probar lo hecho

Así es, nos queda probar lo que se hizo y mirar que todo ande como lo planeado, es decir un formulario con un campo de texto donde se coloca la URL que deseamos acortar al dar click en el submit si todo estuvo bien nos retorna una URL acortada para compartirla en nuestras redes sociales…

Asumiendo que tienes una instalación local deberías ver el ejemplo pinchando una URL como esta http://localhost/kumbiaphp/api/acortar/ es importante entender las URL de KumbiaPHP

En la Wiki de KumbiaPHP hay un ejemplo mas simple de como integrar jQuery en KumbiaPHP y puede quedar mucho mejor este tutorial por ejemplo tener un modelo que se consuma todo el web service del API de SigueMiLink, pero ya esto es tarea de lo mas curiosos les dejo un post que escribí sobre los modelo dentro del MVC

¿dudas? ¿sugerencias? deja tu comentario y ayuda a mejorar este ejemplo…

1. tinyurl.com
2. eb.cx
3. elfurl.com
4. shorl.com
5. url.fm
6. shurl.org
7. qurl.net
8. notlong.com
9. shortlinks.co.uk
10. url123.com