Manual de usuario



Apiweb Framework v0.0

Control de Versións

1 Introdución

Podemos entender Apiweb Framework coma un conxunto de módulos software que colaboran para realizar tarefas comúns a calquera aplicación en contorno web como:

• Recoller os datos remitidos dende un cliente.

• Escribir a saída.

Usando Apiweb Framework tamén se resolven problemas clásicos na programación web:

• Primitivas interfaces de usuario.

• Pouco e difícil control da navegación.

• Pouca reutilización de software.

Apiweb Framework resolve estes problemas simplemente establecendo unha orde e marcando unhas pautas que axudan á construción de aplicacións en contorno web:

• Definido un marco de traballo que facilite a comunicación entre os diferentes roles involucrados no ciclo de vida dun proxecto informático, pex, analistas, programadores, deseñadores gráficos, usuarios, ... etc.

• Definindo un conxunto de módulos comúns a calquera aplicación web, con interfaces e comportamento ben definidos, co obxectivo de fomentar así, a reutilización de software.

• En definitiva, facilitando o desenvolvemento de aplicacións web con garantía de calidade.

1.1 Obxectivos de este manual

Este manual describe como podemos construír aplicacións web empregando Apiweb Framework.

Comeza explicando as características xerais de Apiweb Framework, para despois poñelas en práctica nos seguintes capítulos.

1.2 A quen vai dirixido este manual

A aquelas persoas interesadas no desenvolvemento de aplicacións en contorno web.

• Necesario, coñecementos elementais sobre a POO.

• Desexable, aínda que esta guía tamén pode servir para aprender PHP5.

• Interesante, estar familiarizado con tecnoloxías web como HTML, CSS, JavaScript.

2 Características de Apiweb Framework

Apiweb Framework permite construír aplicacións web Modelo-Vista-Controlador, dirixidas por eventos, e que actúan segundo unha máquina de estados determinada, empregando técnicas de especialización (herencia) e composición de software.

2.1 Eventos de usuario e máquina de estados

Os diagramas de estado utilízanse para representar o comportamento dunha aplicación. Son moi intuitivos e poden ser empregados como unha ferramenta eficaz para a captura de requirimentos de usuario.

A continuación vemos un diagrama de estado característico de sitios web que dispoñen dunha zona privada.

Observando o diagrama anterior podemos ver unha aplicación:

• Composta por 4 estados: login, usuario rexeitado, rexistro usuario e zona privada.

• Os eventos de usuario que provocan as transicións entre os diferentes estados.

• Eventos iguais en diferentes estados, provocan accións diferentes.

• Suponse que cada estado debe proporcionar unha interface que permita realizar a usuarios as operacións esperadas.

• Podemos supoñer que no modelo de esta aplicación puidera haber unha entidade usuario.

Apiweb Framework está deseñada para que os creadores de software conciban ao estado como a unidade básica de construción. Esta idea permitirá definir o comportamento das aplicacións segundo unha máquina de estados determinada.

Ao longo de este manual, veremos como poderemos definir estados, capturar eventos de usuario e manexar as transicións de estado dunha forma sinxela e intuitiva.

2.2 Deseño Modelo-Vista-Controlador

Apiweb framework está deseñada seguindo o patrón de arquitectura de software Modelo-Vista-Controlador. A continuación darase unha breve explicación sobre como Apiweb Framework implementa esta arquitectura, describindo os módulos software que atoparemos en cada unha das tres capas: modelo, vista e controlador.

2.2.1 A capa 'Controlador'

Pode que a capa controlador sexa a capa máis sinxela, e ao mesmo tempo a máis importante, porque caracteriza o comportamento básico de calquera aplicación Apiweb Framework.

A capa modelo de Apiweb Framework está composta polos seguintes módulos software: os scripts index.php, basico.js, ajax.js e as clases Apiweb, EstadoHTTP, EventoHTTP.

2.2.1.1 O script index.php

Este script atópase na raíz de toda aplicación Apiweb Framework e a súa función é a de por en marcha a máquina de estados Apiweb.

É o único punto de acceso dende os clientes ou navegadores web a unha aplicación Apiweb Framework estándar.

No script index.php atoparemos nas primeiras liñas tres parámetros que deben ser establecidos. Estes parámetros son clave para o correcto funcionamento dunha aplicación Apiweb Framework.

1. nome_sesion. Identificador único dunha aplicación web nun servidor web concreto.

2. apiweb_home. Ruta relativa á unha instancia concreta de Apiweb Framaework.

3. ehttp_inicio. Nome do estado inicial ou predeterminado da aplicación.

2.2.1.2 Os scripts basico.js e ajax.js

Encárganse de capturar e catalogar as características de aqueles eventos que se producen na interface de usuario e que xerarán unha petición ao servidor, que consecuentemente, provocarán unha transición, ou auto-transición, do estado da aplicación.

• O script basico.js xestiona peticións síncronas, (submit).

• O script ajax.js xestionará as peticións asíncronas, (AJAX) => auto-transición.

2.2.1.3 A clase Apiweb

Modela a máquina de estados de Apiweb Framework.

A súa función consiste en manexar o estado dunha aplicación respecto a unha sesión de usuario concreta.

A clase Apiweb será creada e instanciada polo script index.php. Cada vez que un cliente envía un evento ao servidor, o script index.php chamará ao método Apiweb.transicion(), iniciando así a execución da máquina de estados.

O método transición da clase Apiweb, funciona segundo un sinxelo algoritmo que se resume na seguinte secuencia:

1. Capturar o estado actual da aplicación respecto a unha sesión determinada.

2. Xestión do evento remitido por un usuario => transición do estado actual.

3. Responder ao cliente.

4. Gardar o novo estado da aplicación.

A continuación móstrase o fluxograma de Apiweb.transicion().

2.2.1.4 A clase EstadoHTTP

A clase EstadoHTTP é unha clase abstracta que modela un estado dunha aplicación web.

Calquera aplicación construída con Apiweb Framework, estará definida por un conxunto de clases EstadoHTTP. Este conxunto de clases EstadoHTTP é a máquina de estados da aplicación.

A clase EstadoHTTP encárgase de recibir a información remitida por un usuario, procesala e xerar a resposta ou saída oportuna en cada momento.

Para realizar estas tarefas, a clase EstadoHTTP utiliza dúas estratexias:

1. Implementa o patrón de deseño de software State. Como se verá no capítulo seguinte, en cada nova especialización da clase EstadoHTTP deberemos declarar o método operación(), onde se definirá o comportamento que dará resposta aos eventos de usuario, (proceso).

2. Definición detallada da vista (posibilita)

   1. Automatizar a recepción da información remitida por un usuario.

   2. Manipular a vista en tempo de execución.

   3. Automatizar a saída.

2.2.1.5 A clase EventoHTTP

A clase EventoHTTP modela un evento de usuario.

Durante a operación EstadoHTTP.postHTTP(), Apiweb Framework creará unha instancia da clase EventoHTTP.

Para programar o método EstadoHTTP.operacion(), consultaremos o EventoHTTP que iniciou unha transición concreta, para determinar cal será a operación que debemos realizar.

2.2.2 A capa 'Vista'

Deberiamos entender a capa vista dunha aplicación web, como todos aqueles mensaxes que o servidor web envía a un navegador web.

Apiweb Framework define 3 tipos de vista dependendo do tipo MIME da mensaxe: html, xml (AJAX) e outro.

A clase da capa controlador, EstadoHTTP, decidiría en cada transición cal será a vista que deberá devolver a un cliente, en función do evento de usuario procesado.

Inspirándose no patrón de deseño Composite, Apiweb Framework define un conxunto de clases que modelan elementos comúns no deseño de interfaces gráficas de usuario, como panéis, caixas de texto, selectores, checkers ... etc, que permitirán definir ou compoñer interfaces gráficas de usuario HTML.

Entre as clases dispoñibles para definir interfaces gráficas de usuario HTML, deberemos destacar dúas: Escritor_html e ObxetoFormulario.

• 
  Escritor_html.

  • Saben escribirse en HTML.

  • Poden declarar a relación con arquivos CSS e/ou JS.

  • Sensibles a configuracións rexionais ou de Idioma.

  • Poden declarar a relación cun arquivo plantilla.

Un arquivo 'plantilla' representa a parte da información estática asociada á vista dun obxecto da clase Escritor_html.

Calquera obxecto Escritor_html poderá inxectar a súa información en plantillas, para devolvelas despois como resultado da execución do método html(). Veremos ao longo deste manual como moitos obxectos da clase Escritor_html utilizan esta característica.

• Especializacións directas: Paxina, Formulario, ObxetoFormulario.

• ObxetoFormulario

  • Especialización da clase Escritor_html.

  • Son aquelas entidades HTML que compoñen un formulario HTML.

  • Entenden mensaxes comúns: post(), operacion(), visible(), readonly().

  • Especializacións directas: Param, ObjetoJS, Panel, Componente.

    1. Param.

       • Permite escribir datos de so lectura nunha plantilla.

    2. ObjetoJS.

       • Representan entidades comúns de calquera interface de usuario como: caixas de texto, selectores, botóns ... etc.

       • Teñen a capacidade de desencadear eventos de usuario que iniciarán as transicións de estado,(EventoHTTP).

    3. Panel.

       • Representan unha subdivisión dun formulario.

       • Implementan o patrón de deseño de software Decorator.

    4. Componente.

       • Un Componente é un ObxetoFormulario definido por composición doutros ObxetoFormulario que cooperan seguindo unha lóxica determinada co fin de realizar algunha tarefa.

       • Un Componente permitirá manexar un conxunto de obxectos da clase ObxetoFormulario coma unha entidade con características e operacións propias.

       • Especializacións: Calendario, Alert, Menu, Taboa ...

2.2.2.1 A vista text/html

Consiste nunha páxina HTML. Está páxina será creada en función dos diferentes elementos que compoñen a Paxina asociada a un EstadoHTTP.

É a vista predeterminada para un EstadoHTTP.

2.2.2.2 A vista text/xml (AJAX)

Devolve un arquivo XML como resposta a unha operación AJAX solicitada dende un navegador web.

Poderán ser incluídos na resposta XML aqueles ObxetoFormulario que implementen a interface IAJAX. Así poderemos modificar ObxetosFormulario tras unha petición AJAX, e enviar ao cliente ou navegador web, os 'cambios' realizados codificados en formato XML.

Unha vez o navegador web recibe o arquivo XML, será o script ajax.js quen se encargará de executar as operacións oportunas para reflectir na interface de usuario, os 'cambios' enviados dende o servidor web.

2.2.2.3 ... outro.

Chegados a este punto, debemos esquecernos de todo o aprendido sobre a capa vista, e pensar na resposta a un cliente como unha simple transmisión de datos de servidor a cliente.

Ás veces, pode ser interesante responder a un cliente enviando un arquivo en formatos como PDF, imáxes, odt ... Nestes casos, Apiweb Framework escribirá un paquete HTTP de resposta co arquivo que queremos enviar, indicando na cabeceira o tipo mime específico, e escribindo no corpo o contido.

Cando un navegador web recibe un paquete HTTP, para saber como debe ser interpretada a información recibida, lee o tipo mime na cabeceira do paquete. Cando información está codificada con formatos distintos de text/html, o comportamento habitual dos navegadores web consiste en:

• Buscar o programa ou plugin vinculado a arquivos do tipo mime recibido.

• No caso de non atopar un terceiro programa capaz de interpretar o tipo mime recibido, solicítase permiso ao usuario para descargar o paquete.

2.2.3 A capa 'Modelo'

A capa modelo fai referencia á información que o programa xestiona e que normalmente estará almacenada nun Sistema de Xestión de Bases de Datos.

Apiweb Framework implementa a capa modelo dende 3 puntos de vista:

1. Homoxeneizando a conexión con diferentes SXBD.

2. Facilitando a exportación de información a outros formatos estándar.

3. Permitindo o emprego de técnicas de programación ORM.

2.2.3.1 Clientes

Permiten a comunicación cun SXBD, en concreto MySql, Oracle, Sqlite e Postgre.

• A idea é establecer unha interface de acceso a datos común con independencia do SXBD.

• Para levar a cabo esta idea, Apiweb Framework define dúas clases abstractas, ConexionBBDD, ResultadoBBDD.

Definido novas especializacións das clases ConexionBBDD e ResultadoBBDD, poderemos definir novos clientes para outros SXBD, ou calquera outro tipo de almacenamento persistente de datos.

2.2.3.2 Escritores de Resultados

Unha característica interesante de calquera aplicación é a capacidade de exportar información en formatos estándar como html, xml e csv.

Apiweb Framework define unha clase, EscritorResultado, que establece unha interface común para transformar automaticamente obxectos da clase ResultadoBBDD noutros formatos comúns para a importación ou exportación de datos.

Poderemos definir novos escritores de resultado para outros formatos creando unha nova especialización da clase EscritorResultado.

2.2.3.3 Escritores_SQL, (ORM)

En moitas aplicacións, as entidades que forman parte da capa negocio, están intimamente ligadas á información almacenada nun SXBD.

Para facilitar o traballo con sistemas de xestión de bases de datos, Apiweb Framework define un conxunto de clases que permiten implementar a capa de negocio de cada aplicación, empregando técnicas de programación ORM.

A continuación darase unha breve descrición das clases do paquete EscritoresSQL.

• Mapa_bd.

Permite describir entidades dun modelo E-R, describindo as táboas e relacións Foreign Key, nunha base de datos concreta.

• Obexto_bd.

  • Teñen a obriga de declarar un Mapa_bd.

  • En función do Mapa_bd asociado, crease no Obxecto_bd, unha colección de obxectos Atributo_obd compatibles cos tipos de cada campo das táboas declaradas no Mapa_bd.

  • Un Obxeto_bd saberá escribir instrucións SQL select, update, insert e delete, oportunas para xestionar así a súa propia persistencia.

Ç

• Escritor_sql.

A súa función consiste en escribir instrucións SQL en función dun Obxeto_bd e unha ConexionBBDD concreta.

• Sintaxis_sql

Modelan peculiaridades da linguaxe SQL segundo un sistema de xestión de bases de datos.

3 Apiweb Hello world !!!

Continuará ...