Desarrollo Framework ProyectoA PHP
Versión desarrollo 1.0.1
Fecha desarrollo 25-10-2017
Autor ProyectoA (www.proyectoa.com, www.ajpdsoft.com)
Revisión documento 1.0
Fecha documento 25-10-2017
Título documento Documentación para aplicación de Framework ProyectoA PHP

 

Tras analizar diferentes framework para PHP como Symfony, Aura, Slim, CakePHP, Zend Framework, Yii, Laravel y otros. Casi todos muy potentes y con grandes prestaciones, pero la inmensa mayoría requieren de unos conocimientos previos y, además, si decidimos usarlos nos hacen ser casi totalmente dependientes de ellos.

Framework ProyectoA PHP nace precisamente de ese análisis de los framework actuales, decidimos hacer nuestro propio Framework, buscando, ante todo, la sencillez y el pragmatismo.

Ventana de detalle de Framework ProyectoA PHP

Framework ProyectoA PHP es algo más que un framework, dado que permite crear una WebApp adaptativa y responsiva en unos segundos, sin apenas conocimientos de programación y con la interfaz gráfica incluida.

A continuación detallaremos la documentación de Framework ProyectoA PHP. Explicaremos cómo implementar este framework en cualquier organización, empresa o particular. Indicaremos para qué sirve, cómo fue desarrollado y todo lo necesario para aplicarlo a cualquier desarrollo web con PHP.

Aplicabilidad, uso de Framework ProyectoA PHP

Framework ProyectoA PHP servirá para crear una Web/Intranet/WebApp de gestión interna para nuestro negocio, organización o para uso particular. Sin apenas conocimientos de programación en PHP podremos crear una aplicación web adaptativa y responsiva, con sólo tener una base de datos y un fichero XML de configuración.

El núcleo del framework será el encargado de generar las distintas ventanas y pantallas de la App, que serán adaptativas y responsivas para visualización en cualquier dispositivo. Permitirá generar de forma automática ventanas de listado de registros (con búsqueda y ordenación), de detalle (con información del registro seleccionado), de alta de nuevos registros y de modificación de registros existentes.

WebApp con Framework ProyectoA PHP

Todas las ventanas (módulos o tablas) podrán ser personalizadas completamente (columnas a mostrar tanto en la lista como en las ventanas de detalle, nuevo registro y modificación).

Toda la configuración y personalización se realizará desde un único fichero XML, desde el que se indicarán todos los módulos y tablas a mostrar en nuestra App, de forma sencilla, mediante atributos de campos.

Requisitos para usar Framework ProyectoA PHP

Todo lo necesario para el funcionamiento de este framework se encuentra en esta descarga (completamente gratuita y sin ningún tipo de publicidad):

  • Framework ProyectoA PHP.

A continuación indicamos lo que contiene el fichero comprimido:

  • bower_components: carpeta que contiene todos los elementos de BoopStrap 3.3. Librería en CSS, HTML5 y JS para la interfaz gráfica del Framework.
  • css: carpeta de hoja de estilos CSS.
  • fonts: algunas fuentes e iconos para usar en el Framework.
  • img: carpeta de imágenes, para el logotipo y el favicon de la aplicación.
  • jquery: jquery 1.8.3.
  • js: carpeta con ficheros JavaScript necesarios para el funcionamiento de BoopStrap.
  • cabecera.php: fichero PHP que muestra la cabecera y los menús de la App.
  • cerrar.php: fichero PHP para cerrar la sesión.
  • config.xml: fichero XML de configuración inicial del framework (acceso a la base de datos, establecimiento del tipo de seguridad, clave de encriptación para los GET y POST).
  • modulos.xml: fichero más importante del framework, en el que se introducen los módulos y las tablas de la App, con todos sus atributos. Será el fichero que usará el núcleo del framework para mostrar las distintas ventanas de la aplicación web.
  • de_detalle.php, de_ventana_modal.php: ficheros PHP para mostrar la ventana de detalle de cada registro, usando AJAX para la conexión a la base de datos. Los campos a mostrar se personalizan en el fichero modulos.xml.
  • funciones.php: fichero PHP donde reside todo el núcleo de programación.
  • in_std.php: fichero PHP que siempre es llamado inicialmente para cargar el resto de módulos.
  • ac_std.php: fichero PHP para actualizar un registro.
  • li_std.php: fichero PHP para mostrar listado de registros.
  • nu_std.php: fichero PHP para añadir un nuevo registro.
  • pie.php: parte inferior de la WebApp.
  • val.php: fichero PHP que es llamado por el resto para validar acceso, seguridad, sesión iniciada, módulo a cargar, etc.

En cuanto a los requisitos para el funcionamiento de Framework ProyectoA PHP son los siguientes:

  • Disponer de un servidor (sea Windows o Linux) con Apache y PHP 7.0 ó superior. En nuestra web tenemos numerosos artículos para crear un servidor web con Apache y PHP.
  • Disponer de un servidor de base de datos MySQL o MariaDB. Con unas mínimas adaptaciones podría funcionar con cualquier otro motor de base de datos. De momento está verificado con MySQL 5.5 y con MariaDB.
  • Si queremos usar la validación LDAP necesitaremos tener activado este módulo en la configuración de PHP.

Desarrollo interno de Framework ProyectoA PHP

A continuación explicamos detalladamente cómo ha sido desarrollado Framework ProyectoA PHP, esto servirá para entender mejor su funcionamiento y para, el que quiera, poder hacer modificaciones y personalizaciones adaptándolo a su organización.

Se trata de un framework totalmente personalizable, desde la interfaz gráfica que podría cambiarse por otra con pocas modificaciones, hasta el código del núcleo PHP. Este framework nació precisamente con la idea de que fuera un punto de partida para desarrollos de cualquier tipo de WebApp para gestión interna: desde recursos humanos, almacén, facturación, control de stock, helpdesk y otros muchos usos.

La base del núcleo de Framework ProyectoA PHP es PHP y XML. Los ficheros PHP que conforman el núcleo (funciones.php, in_std.php, ac_std.php, li_std.php, nu_std.php, …) leen todos los datos del fichero XML modulos.xml para mostrar los formularios según la personalización indicada en este fichero.

Para entenderlo mejor pondremos un sencillo ejemplo: si queremos ocultar una columna en el grid/rejilla de datos y mostrarlo en la ventana de detalle usaremos estos dos atributos:

  • visible_grid=”no”.
  • visible_deta=”sí”.

Como se puede observar los nombres de los atributos son bastante intuitivos y sus valores también “sí”, “no”. Además, Framework ProyectoA PHP funciona por omisión, por ejemplo, si no incluimos el atributo visible_grid el campo en cuestión no se mostrará en el listado.

En la parte de la base de datos, Framework ProyectoA PHP accederá a las tablas indicadas en el fichero XML, con los nombres de tablas, nombres de campos y tipos de datos para formatear la entrada y salida de datos, todo ello se indica en el fichero modulos.xml.

Framework ProyectoA PHP permite dos modos de seguridad de acceso a la aplicación, para establecer los permisos de los usuarios a los distintos módulos:

  • Mediante XML: se indicarán los permisos en el propio fichero XML modulos.xml por cada tabla.
  • Mediante base de datos: se establecerán los permisos en una tabla de la base de datos y el núcleo del framework los comprobará en dicha tabla.

Framework ProyectoA  PHP también permite dos modos de validación de los usuarios:

  • Mediante usuario y contraseña (en MD5) de una tabla de la base de datos, indicada en el fichero XML modulos.xml.
  • Mediante validación LDAP (admite Active Directory de Windows).

 El fichero config.xml

En el fichero config.xml se establecerán los parámetros iniciales para el funcionamiento de la aplicación web:

  • servidor: nombre de red (DNS) o IP del servidor donde esté alojada la base de datos (MySQL, MariaDB, etc.).
  • puerto: puerto de comunicación, para MySQL el de defecto es 3306.
  • usuario: nombre del usuario de acceso a la base de datos.
  • contrasena: contraseña del usuario anterior. Debe indicarse en base64 (para que no quede visible directamente).
  • base_datos: nombre de la base de datos o catálogo en el que reside la aplicación.
  • clave_get: secuencia de caracteres, números y letras para cifrar los valores GET y POST en la URL.
  • seguridad_tipo_acceso: tipo de acceso a la aplicación, soporta actualmente los siguientes métodos:
    • ldap;;dominio: acceso validando contra un servidor de LDAP, en este caso deberemos indicar dos valores: ldap y el nombre del dominio o servidor de LDAP al que conectarse, separados por ;; (punto y coma y punto y coma).
    • wordpress;;fichero.php: acceso usando fichero PHP de WordPress para validar con su propia base de datos de usuarios. Se deberán introducir dos valores: wordpress y el nombre del fichero PHP con las clases y funciones de acceso a la validación de WordPress: PasswordHash, CheckPassword que suelen residir en el fichero class-phpass.php.
    • bd: acceso usando nuestra propia tabla de usuarios de la base de datos. En este caso se indicarán los valores de conexión mediante atributos del fichero XML en la tabla de usuarios. Se indica más abajo.

Ejemplo de contenido de fichero config.xml:

Si hemos elegido el método de validación mediante tabla de la base de datos (seguridad_tipo_acceso=”bd”), necesitaremos disponer de una tabla en nuestra base de datos con, al menos, los siguientes campos:

  • codigo [int]: clave primaria de la tabla.
  • administrador [varchar(1)]: campo que indicará si el usuario es administrador (con valor “S”) o si no lo es (con valor “N”). El usuario administrador tendrá acceso a todas las opciones de la App.
  • modificacion [varchar(1)]: si no es establecen los permisos desde la tabla de permisos de la aplicación, este campo indicará si el usuario puede modificar datos (añadir, eliminar y modificar registros). Si la aplicación cuenta con la tabla de permisos (que explicaremos más adelante) este campo no se tendrá en cuenta.
  • nick [varchar(50)]: nombre de inicio de sesión (login). Este valor debe coincidir con el que introduzca el usuario para iniciar sesión, con cualquier método de validación (ldap, wordpress o bd).
  • contrasena [varchar(100)]: contraseña del usuario para inicio de sesión, se utilizará si se ha indicado el método seguridad_tipo_acceso=”bd”.
  • nombre [varchar(200)]: nombre completo del usuario.
  • acceso_web [varchar(1)]: indicaremos si el usuario tendrá acceso a la App web, si el valor es distinto de “S” no tendrá acceso.
  • activo [varchar(1)]: si el usuario no está activo (valor distinto de “S”) no tendrá acceso a la web.
  • codigo_asociado [int]: se usa para enlazar la tabla de usuarios de acceso con otra tabla, por ejemplo de técnicos asociados al usuario o de personal asociado al usuario.
  • tipo [varchar(50)]: tipo de usuario que inicia sesión en la aplicación. De momento no tiene un uso concreto, podría servir para indicar si es un usuario técnico o un usuario normal.

Los nombres de los campos anteriores, así cómo su tipo de datos es una recomendación pero no son de cumplimiento obligatorio. En la tabla del fichero modulos.xml que incluya el atributo acceso_app=”sí” indicaremos cuáles serán los campos anteriores con los atributos:

  • clave=”sí”
  • campo_acceso_nick=”sí”
  • campo_acceso_pass=”sí”
  • campo_acceso_nombre_completo=”sí”
  • campo_acceso_tipo=”sí”
  • campo_acceso_codigo_asociado=”sí”
  • campo_acceso_activo=”sí”
  • campo_acceso_administrador=”sí”
  • campo_acceso_modificacion=”sí”
  • campo_acceso_web=”sí”

Explicamos estos atributos en la sección de más abajo: El fichero XML modulos.xml, los atributos y su funcionamiento.

Un ejemplo de SQL para creación de la tabla de usuarios de la aplicación:

 

Parámetros de la base de datos para personalizar el Framework y la aplicación web resultante

Framework ProyectoA permite establecer una serie de parámetros para personalizar la aplicación web resultante. Estos parámetros deben existir en una tabla en la base de datos. A continuación mostramos el SQL necesario para crear esta tabla:

 

El nombre de la tabla puede ser cualquiera, en el ejemplo es “parametro”, pero habrá que indicar que se trata de la tabla de parámetros de la aplicación en el módulo XML correspondiente, como indicaremos más abajo.

Los parámetros para iniciar la aplicación (debe existir un registro en esta tabla con el parámetro correspondiente):

  • web_empresa_nombre: nombre de la organización, será el que se muestre en el inicio y en la pestaña de título “Área privada – XXX”.
  • web_empresa_siglas: se mostrarán el el nombre abreviado de la aplicación web.

Sin estos parámetros la aplicación funcionará, por lo que podremos establecerlos posteriormente, incluso creándolos desde la propia aplicación una vez introducido el módulo y tabla de parámetros en el XML (como indicamos a continuación).

El fichero XML modulos.xml, los atributos y su funcionamiento

Como ya hemos comentado Framework ProyectoA PHP se basa en el fichero modulos.xml, en él estableceremos todas las tablas, campos y atributos de la aplicación. A continuación explicamos en profundidad el funcinamiento de este fichero XML.

El fichero se estructura en módulos de la aplicación y, dentro de cada módulo las tablas que contenga. A su vez, cada tabla contendrá los campos oportunos. En cada tabla estableceremos también los botones de acción (eliminar, modificar, ver detalle) que queramos mostrar al usuario en la ventana de lista (rejilla o grid). Un ejemplo de esta estructura:

Como podemos observar en el ejemplo se indican los módulos de la aplicación y, cada módulo, contiene una serie de tablas. Lo más habitual es que un módulo contenga una única tabla. Por ejemplo, si tenemos una aplicación de facturación tendremos una tabla de terceros (clientes y proveedores). Para el mantenimiento de esta tabla crearíamos un módulo llamado “Terceros”, dentro de este módulo una tabla llamada “tercero” (o el nombre que tenga en la base de datos) y los campos y botones oportunos. Ejemplo:

Definición de los atributos para cada módulo de la aplicación

  • nombre: nombre identificativo del módulo, deber ser único y no coincidir con ningún otro nombre de módulo del fichero XML. Será el identificador interno para el uso del módulo.
  • label: etiqueta del módulo, será el título. Cuando haya que mostrar el nombre del módulo al usuario en la App se usará el valor de este atributo.
  • label_singular: el mismo uso que el atributo anterior, label, pero para los casos del uso del singular en lugar del plural.
  • tipo: establecerá el tipo de módulo, las posibilidades son:
    • acceso_app: módulo para acceso de los usuarios a la App, será el módulo y tabla que se use para la validación del usuario en la aplicación.
    • parametros: módulo para la tabla de parámetros de configuración de la aplicación. Será el que se use para almacenar y consultar los parámetros de configuración de la aplicación.
    • estándar: es el tipo de módulo habitual, para el resto de tablas que no sean de parámetros ni de acceso a la aplicación.
  • fi_in: fichero PHP para gestionar el módulo, por defecto in_std.php.
  • fi_li: fichero PHP para gestionar el módulo, por defecto li_std.php.
  • fi_nu: fichero PHP para gestionar el módulo, por defecto nu_std.php.
  • fi_ac: fichero PHP para gestionar el módulo, por defecto ac_std.php.
  • mostrar_menu: para mostrar u ocultar el módulo en el menú de la aplicación. Valores posibles:
    • : se mostrará el módulo en el menú, siempre y cuando el usuario tenga permisos para verlo, al menos.
    • no: no se mostrará el módulo en el menú.
  • label_menu: nombre que se mostrará al usuario en el menú.

Definición de los atributos para cada tabla de la aplicación

  • nombre: nombre identificativo de la tabla, que debe coincidir con el nombre que la tabla tenga en la base de datos. Deber ser único y no coincidir con ningún otro nombre de tabla del fichero XML. Será el identificador interno para el uso de la tabla.
  • tipo: al igual que para el caso del módulo, deberemos indicar el tipo de tabla, las posibilidades son las mismas que para los módulos:
    • acceso_app: tabla para acceso de los usuarios a la App, será la tabla que se use para la validación del usuario en la aplicación. Sólo puede haber una tabla con este tipo “acceso_app”. Si hay varias se usará la primera establecida en el XML.
    • parámetros: tabla de parámetros de configuración de la aplicación. Será la que se use para almacenar y consultar los parámetros de configuración de la aplicación. Sólo puede haber una tabla con este tipo “parámetros”. Si hay varias se usará la primera establecida en el XML.
    • estándar: es el tipo de tabla habitual, para el resto que no sean de parámetros ni de acceso a la aplicación.
  • principal: aún no tiene uso, se define para permitir mostrar en futuras nuevas versiones del framework tablas en maestro detalle (uno a muchos).
  • grid: tipo de tabla (rejilla) a mostrar en la ventana de listado de registros. Las opciones son:
    • simple: muestra un grid o tabla sin paginación ni ordenación ni búsqueda, útil para casos en los que queramos mostrar unos pocos registros.
    • completo: muestra un grid o tabla con paginación, con ordenación por columna y con búsqueda. Puede resultar de carga lenta en casos de muchos registros, dado que los carga todos en la tabla y luego los pagina.
    • personalizado: podemos establecer una tabla personalizada que permita el modo gráfico usado.
  • sql_select: SQL que se usará para ejecutar las consultas de selección de registros de la tabla. El valor ##tabla## se reemplazará por el nombre de la tabla. Es recomendable usar siempre el alias zz para sustituir al nombre de la tabla.
  • sql_insert: aún no se usa, los insert de SQL de generan de forma automática.
  • sql_update: aún no se usa, los update de SQL de generan de forma automática.
  • sql_delete: aún no se usa, los delete de SQL de generan de forma automática.
  • mostrar_solo_usuario_alta: en la ventana de listado de registros (li_std.php), si este atributo tiene valor “sí”, al usuario (si no es administrador) se le mostrarán sólo los registros que él mismo haya dado de alta. Los campos de filtro serán los que tengan el atributo campo_filtrar_solo_alta=”sí”.
    • : se mostrarán al usuario sólo los registros dados de alta por él mismo, usando como filtro el campo cuyo atributo sea campo_filtrar_solo_alta=”sí” y el código del usuario que inició sesión. Puede haber varios campos con atributo campo_filtrar_solo_alta=”sí”, en este caso se filtrarán con un or lógico.
    • no: valor por defecto, no es necesario indicarlo.

Atención: si la tabla tiene muchos registros puede producirse el error Maximum execution time of 30 seconds exceeded, debido a que la consulta tarda más en cargarse que el tiempo máximo permitido por PHP. En este caso o bien usamos un grid que pagine los resultados y los cargue conforme nos vayamos moviendo por las distintas páginas, o bien debemos aplicar algún filtro que limite el número de registros a mostrar.

 Campos especiales para definir el color fondo de cada fila de la tabla

Si queremos mostrar con un color diferente el fondo de una fila de la tabla/grid (rejilla de datos) podremos usar el siguiente atributo especial: color_fondo_fila_xxx, nos permitirá mostrar una fila como la de la imagen:

Para ello añadiremos en la tabla el siguiente atributo:

  • color_fondo_fila_xxx: este atributo debe incluir la siguiente información, separada con ;; (punto y coma dos veces):
    • Sustituiremos “xxx” por los siguientes valores posibles en el nombre del atributo, quedando, por ejemplo color_fondo_fila_warning:
      • success

      • warning

      • danger

      • info

    • Campo: indicaremos el nombre del campo de la tabla cuyo valor se usará para evaluar la condición. El campo debe elegido debe tener el atributo visible_grid=”sí”, de lo contrario se producirá el error Notice: Undefined index.
    • Condición: indicaremos la condición que debe cumplir para mostrar el fondo del color elegido, las opciones son:
      • =! para distinto, también es válido <> (pero cambiando < por &lt; y > por &gt;).
      • > para mayor que, cambiando > por &gt;
      • < para menor que, cambiando < por &lt;
      • >= para mayor o igual, cambiando > por &gt;, quedando &gt;=
      • <= para menor o igual, cambiando < por &lt;, quedando &lt;=
      • == para igual, importante repetir dos veces el signo de igual.
    • Valor: valor que debe tener el campo que cumple la condición indicada.

Un ejemplo de color_fondo_fila_xxx para mostrar el fondo de una fila en color danger cuando el campo “resultado” de la tabla tenga valor distinto de “S”:

En el ejemplo anterior, básicamente indicamos que queremos mostrar el fondo de la fila actual con formato de color de fondo danger si el campo “realizada” de la tabla tiene el valor distinto de “S”. Como se puede observar las comillas simples (apóstrofes) de ‘S’ las cambiamos por &apos;.

Hay que tener en cuenta que si queremos indicar el valor comillas dobles “, menor que <, mayor que >, apóstrofo ‘ ó & deberemos indicarlo en el XML siguiendo la siguiente tabla de correspondencia:

Carácter Resuelto en XML como
Menor que (<) &lt;
Mayor que (>) &gt;
Comillas dobles (“) &quot;
Apóstrofe (ˋ) &apos;
El signo & (&) &amp;

También es importante saber que si es un número el que se quiere evaluar en la condición NO introduciremos los apóstrofos, si es un texto sí. Por ejemplo, si queremos mostrar el fondo de la fila de color success si el campo importe es mayor de 1000, introduciremos el siguiente atributo:

Los tipos son excluyentes, sólo se puede mostrar el fondo con uno de los formatos posibles, por lo tanto, sin introduciremos varios tipos debemos asegurarnos de que la condición sólo se cumpla en uno de ellos.

 

Definición de los atributos para cada campo de una tabla de la aplicación

  • nombre: nombre interno del campo, debe coincidir con el nombre del campo en la base de datos.
  • tipo_dato: tipo de dato del campo, las posibilidades son:
    • fecha:
    • numero:
    • boolean:
    • texto:
  • numero_decimales: si es tipo_dato=”numero” podremos indicar el número de decimales (si los tiene), nos servirá para formatear la salida y mostrar al usuario el número con los decimales indicados.
  • tipo_campo: indicaremos el tipo de campo, las posibilidades son:
    • url: para las direcciones web, requerirá un tipo_dato=”texto”.
    • mail: para la dirección de correo electrónico, requerirá un tipo_dato=”texto”.
    • teléfono: para establecer un teléfono, requerirá un tipo_dato=”texto”.
    • desplegable_lista: cuando queramos que se muestre un desplegable con una lista para seleccionar. Los valores mostrados se tomarán de otro atributo del XML. Explicamos más adelante el uso.
    • desplegable_bd: cuando queramos que se muestre un desplegable con una lista para seleccionar. Los valores mostrados se tomarán de una tabla de la base de datos. Explicamos más adelante el uso.
    • desplegable_parametro_bd: cuando queramos que se muestre un desplegable con una lista para seleccionar. Los valores mostrados se tomarán de un parámetro de la tabla de parámetros (tipo=”parámetros”) de la base de datos. Explicamos más adelante el uso.
    • contraseña: para establecer campos de tipo contraseña.
    • memo: para campos de tipo texto “grande”, con varias líneas.
  • solo_lectura: para mostrar campos en formularios de solo lectura (no modificables). Las opciones son:
    • “readonly”: mostrarla el campo en el formulario pero sin posibilidad de modificar los valores.
    • “”: este valor vacío mostrará un campo normal, de modificación.
  • clave: indicará si el campo es clave primaria de la tabla. Los valores posibles son:
    • : sí es clave primaria.
    • no: no es clave primaria (no es necesario indicarlo).
  • visible_modi: para mostrar un campo en la ventana de modificación de registro. Los valores posibles son:
    • : se mostrará el campo en la ventana de modificación.
    • no: no se mostrará (no es necesario indicarlo, por defecto no se mostrará).
  • visible_alta: para mostrar un campo en la ventana de nuevo registro. Los valores posibles son:
    • : se mostrará el campo en la ventana de alta de registro.
    • no: no se mostrará (no es necesario indicarlo, por defecto no se mostrará).
  • visible_deta: para mostrar un campo en la ventana de detalle de registro. Los valores posibles son:
    • : se mostrará el campo en la ventana de detalle.
    • no: no se mostrará (no es necesario indicarlo, por defecto no se mostrará).
  • visible_grid: para mostrar un campo en la ventana de listado de registros. Los valores posibles son:
    • : se mostrará el campo en la ventana de grid/rejilla.
    • no: no se mostrará (no es necesario indicarlo, por defecto no se mostrará).
  • ordenable_grid: si el visible_grid=”sí” se permitirá ordenar por este registro en la rejilla. Los valores posibles son:
    • : permitirá ordenación.
    • no: no permitirá ordenación (no es necesario indicarlo, por defecto no permitirá ordenación).
  • oculto_formulario: este atributo se usará para los campos que tendrán valores visible_alta=”sí”, se agregarán al formulario pero de forma oculta al usuario. Este atributo se usará con valor “sí” para los campos de clave primaria clave=”sí”, para modificación y alta de registros. Los valores posibles son:
    • : el campo se añadirá al formulario de modificación de registro pero oculto al usuario.
    • no: no es necesario indicarlo, por defecto este atributo será “no”.
  • label: etiqueta o título del campo para mostrar al usuario en los distintos formularios y ventanas donde se use.
  • requerido: establece si un campo debe tener un valor obligatorio en los formularios de alta y modificación. Los valores posibles son:
    • : será obligatorio, si se pulsa en el botón de guardar o añadir y no tiene un valor se mostrará un aviso al usuario.
    • no: no será obligatorio. No es necesario establecerlo, por defecto será “no”.

Aviso de campo requerido

  • defecto: valor por defecto para el campo en el caso de formulario de nuevo registro.
  • valor_si_vacio: si introducimos un valor para este atributo en el XML, será el que se asigne al campo si el usuario no ha establecido valor en el formulario para el caso de las altas y las modificaciones. Admite los siguientes valores:
    • Un valor fijo cualquiera (sea numérico, texto o cualquier otro tipo).
    • fecha_actual: la fecha actual del sistema.
    • fecha_hora_actual: la fecha y hora actuales del sistema.
    • codigo_usuario_sesion: código del usuario que ha iniciado sesión en el sistema. Se cogerá del campo de la tabla tipo=”acceso_app” con atributo clave=”sí”.
    • codigo_usuario_asociado:  código de la tabla asociada con la de usuarios, este campo se establece en la tabla con  tipo=”acceso_app”, y con atributo campo_acceso_codigo_asociado=”sí” .
    • parametro_bd;;nombre_parámetro: dos valores separados por ;; indicarán que el valor por defecto se obtendrá de la tabla de parámetros, el primer elemento indicará que se obtenga de la tabla de parámetros, siempre será “parametro_bd”, el segundo será el nombre del parámetro del que se obtendrá el valor.
  • insertable: si establecemos valor “sí” para este atributo el campo actual se usará para el alta de un nuevo registro. Todos los campos con este atributo a “sí” se usarán para generar el SQL de insert de la tabla. Independientemente de si se han mostrado o no en el formulario de alta con visible_alta=”sí”. En el caso de campos en los que queramos que se introduzca un valor automático sin la intervención del usuario, por ejemplo el código del usuario que inicia sesión, estableceremos insertable=”sí”, visible_alta=”no” y el valor que se guardará lo especificaremos en valor_si_vacio.
  • alineacion: tipo de alineación en el grid (rejilla), en la ventana de lista. Las opciones posibles son cualquiera que permita el entorno gráfico:
    • left: izquierda.
    • center: centro.
    • right: derecha.
  • placehorder: texto que aparecerá dentro del campo, a modo explicativo.
  • campo_filtrar_solo_alta: el campo que incluya este atributo con valor “sí” será el que se utilice como filtro si la tabla tiene el atributo mostrar_solo_usuario_alta=”sí”. Al usuario, en la ventana de listado de registros, sólo se le mostrarían los que él mismo haya dado de alta, usando como filtro este campo. Los valores posibles:
    • : se mostrarán al usuario sólo los registros dados de alta por él mismo, usando este campo como filtro y el código del usuario que inició sesión.
    • no: valor por defecto, no es necesario indicarlo.

Algunos atributos especiales para cuando el tipo de tabla es tipo=”parámetro”:

  • campo_parametro_valor1: si la tabla es tipo=”parámetro”, este atributo indicará cuál es el campo “valor1” del que cogerá este dato. Si introducimos campo_parametro_valor1=”sí” el campo que tenga este atributo será tomado como “valor1” a la hora de obtener un valor de un parámetro de la aplicación.
  • campo_parametro_valor2: si la tabla es tipo=”parámetro”, este atributo indicará cuál es el campo “valor2” del que cogerá este dato. Si introducimos campo_parametro_valor2=”sí” el campo que tenga este atributo será tomado como “valor2” a la hora de obtener un valor de un parámetro de la aplicación.
  • campo_parametro_nombre: si la tabla es tipo=”parámetro”, este atributo indicará cuál es el campo “nombre” que se usará para filtra el parámetro con el que trabajaremos. Si introducimos campo_parametro_nombre=”sí” el campo que tenga este atributo será tomado como “nombre” a la hora de obtener un valor de un parámetro de la aplicación.

Algunos atributos especiales para cuando el tipo de tabla es tipo=”acceso_app”:

  • campo_acceso_nick: si la tabla es tipo=”acceso_app”, este atributo indicará cuál es el campo “nick” del que cogerá este dato. Si introducimos campo_acceso_nick=”sí” el campo que tenga este atributo será tomado como “nick” a la hora de obtener los datos del usuario de acceso a la aplicación.
  • campo_acceso_pass: igual que los anteriores, para la contraseña del usuario.
  • campo_acceso_nombre_completo: igual que los anteriores, para el nombre completo, será el que aparezca en el menú desplegable de desconexión y cierre de sesión.
  • campo_acceso_codigo_asociado: igual que los anteriores, para indicar el campo de código asociado, si tenemos una estructura en nuestra base de datos y aplicación de tabla de usuarios y tabla de técnicos (por ejemplo) asociados a usuarios.
  • campo_acceso_activo: igual que los anteriores, será el campo “activo” para indicar si el usuario está activo, sólo se permitirá acceso si el valor es “S”.
  • campo_acceso_administrador: si es usuario administrador tendrá valor “S”.
  • campo_acceso_modificacion: si tiene permisos de modificación tendrá valor “S”.
  • campo_acceso_web: la aplicación sólo permitirá acceso a usuarios con valor de este campo a “S”.

Si no se indica campo_acceso_codigo_asociado la aplicación no tendrá en cuenta este valor y en la asignación de técnicos o usuarios a las tablas tomará el del usuario que haya iniciado sesión. Este campo puede resultar útil, por ejemplo, si tenemos una aplicación con dos tablas, una para los usuarios que inician sesión y otra para el personal laboral. Al personal laboral que queramos darle acceso a la aplicación le crearíamos un usuario en la tabla de usuarios y lo asociaríamos con esta persona por el campo campo_acceso_codigo_asociado.

 

Campo especial separador para formularios de alta y modificación de registro

Existe un tipo de campo especial que no tiene enlace con campo de la tabla de la base de datos, es un campo separador, se usará cuando queramos agrupar varios campos para el formulario de alta y modificación. Por ejemplo, si tenemos varios campos relacionados con los datos postales de un tercero podemos agruparlos mediante un separador.

La ventaja es que este separador (dependiendo del tipo elegido) puede estar plegado en inicio, de forma que será menos engorroso el formulario final mostrado al usuario cuando tengamos muchísimos campos a rellenar:

Separador de campos

Y con una sencilla pulsación se desplegará:

Campo separador de formulario desplegado

Para establecer este separador nos colocaremos antes del primer campo que queramos incluir en el desplegable o grupo y añadiremos el siguiente campo especial, por ejemplo:

Explicamos cada atributo del campo especial del ejemplo anterior:

  • nombre: nombre identificativo del separador, no puede coincidir con otro nombre de otro separador de la misma tabla.
  • tipo_campo: en este atributo indicaremos el tipo de separador que queramos aplicar. Las opciones posibles:
    • separador_acordeon: mostrará un separador tipo acordeon plegable y desplegable.
    • separador_botones: mostrará un separador como el estándar de la aplicación, con botón de minimizar y maximizar.
    • separador_panel: el más simple, mostrará un separador desplegable y peglable.
  • label: título del separador, será muy útil cuando tengamos varios separadores en un mismo formulario, para diferenciarlos.
  • clave: icono que se mostrará para el desplegable, el preestablecido: “glyphicon glyphicon-th“.
  • visible_alta: debe tener valor “sí” para que se muestre el separador.

Tras introducir el campo especial separador añadiremos los campos que queramos que queden dentro y para indicar el fin del separador añadiremos este otro campo:

Con los atributos:

  • nombre: nombre identificativo del separador, debe coincidir con el nombre del separador de inicio.
  • tipo_campo: en este atributo indicaremos el tipo de separador que queramos aplicar, con el sufijo _fin. Las opciones posibles:
    • separador_acordeon_fin: fin del separador de acordeón.
    • separador_botones_fin: fin del separador de botones.
    • separador_panel_fin: fin de separador de panel.
  • visible_alta: debe tener valor “sí” para que se muestre el final del separador.

Campo especial desplegable con datos obtenidos de tabla de la base de datos

Si queremos mostrar un campo desplegable que obtenga los datos de otra tabla de la base de datos, por ejemplo para mostrar un campo de selección de forma de pago de un cliente:

Desplegable de base de datos

Desplegable de base de datos

Usaremos los siguientes atributos:

  • tipo_campo: para que sea desplegable con datos de tabla externa debe tener el valor desplegable_bd.
  • desplegable_nombre: nombre del desplegable, debe ser único en la tabla, es un identificador interno.
  • tabla_externa: nombre de la tabla en el XML de la que cogeremos los datos para el desplegable.
  • tabla_externa_alias: alias que se establecerá a la tabla externa en el join SQL, útil si queremos usar dos o más veces la misma tabla externa, en este caso debemos indicar un alias unívoco, que sea diferente para cada vez que utilicemos la tabla externa en el módulo actual, de lo contrario se producirá un error 1066 Not unique table/alias.
  • clave_externa: campo por el que filtraremos en la tabla externa y valor que guardaremos en el campo de la tabla actual como clave foránea. Este valor no se mostrará al usuario.
  • campo_externo: nombre del campo de la tabla externa del que cogeremos los datos para mostrar en el desplegable al usuario.
  • filtro_externo: si queremos establecer algún filtro (con notación SQL) que se aplicará a los datos a mostrar en la tabla externa.

Campo especial desplegable con datos obtenidos del propio XML

Si queremos mostrar un campo desplegable que obtenga los datos desde un atributo del fichero XML, por ejemplo para mostrar unos cuantos valores fijos, usaremos los siguientes atributos:

  • tipo_campo: para que sea desplegable con datos de un atributo del XML debe tener el valor desplegable_lista.
  • desplegable_elementos: indicaremos en este atributo los valores que queramos mostrar en la lista, separados con ;; (dos puntos y comas). Por ejemplo: desplegable_elementos=”Cliente;;Proveedor;;Otro”.

Desplegable lista con valores de XML

Campo especial desplegable con datos obtenidos de un parámetro de la tabla de parámetros de la base de datos

Si queremos mostrar un campo desplegable que obtenga los datos desde un parámetro de la base de datos usaremos los siguientes atributos:

  • tipo_campo: para que sea desplegable con datos de un parámetro debe tener el valor desplegable_parametro_bd.
  • tipo_campo_nombre_parametro=: nombre del parámetro que debe existir en la base de datos.

 Campos especiales para definir etiqueta coloreada en el valor del registro en el grid

Si queremos mostrar con un color diferente un valor en un campo de un grid (rejilla de datos) podremos usar el siguiente atributo especial: label_tipo_xxx, nos permitirá mostrar un valor como el de la imagen:

Para ello añadiremos en el campo a modificar el color el siguiente atributo:

  • label_tipo_xxx: este atributo debe incluir la siguiente información, separada con ;; (punto y coma dos veces):
    • Sustituiremos “xxx” por los siguientes valores posibles en el nombre del atributo, quedando, por ejemplo label_tipo_warning:
      • default


      • primary


      • success


      • info


      • warning


      • danger


    • Campo: indicaremos el nombre del campo de la tabla cuyo valor se usará para evaluar la condición. El campo debe elegido debe tener el atributo visible_grid=”sí”.
    • Condición: indicaremos la condición que debe cumplir para mostrar esta etiqueta, las opciones son:
      • =! para distinto, también es válido <> (pero cambiando < por &lt; y > por &gt;).
      • > para mayor que, cambiando > por &gt;
      • < para menor que, cambiando < por &lt;
      • >= para mayor o igual, cambiando > por &gt;, quedando &gt;=
      • <= para menor o igual, cambiando < por &lt;, quedando &lt;=
      • == para igual, importante repetir dos veces el signo de igual.
    • Valor: valor que debe tener el campo que cumple la condición indicada.

Un ejemplo de label_tipo_xxx para mostrar el valor en formato warning cuando el campo “resultado” de la tabla tenga valor distinto de “S”:

En el ejemplo anterior, básicamente indicamos que queremos mostrar el valor del campo actual con formato de etiqueta warning si el campo “realizada” de la tabla tiene el valor distinto de “S”. Como se puede observar las comillas simples (apóstrofes) de ‘S’ las cambiamos por &apos;.

Hay que tener en cuenta que si queremos indicar el valor comillas dobles “, menor que <, mayor que >, apóstrofo ‘ ó & deberemos indicarlo en el XML siguiendo la siguiente tabla de correspondencia:

Carácter Resuelto en XML como
Menor que (<) &lt;
Mayor que (>) &gt;
Comillas dobles (“) &quot;
Apóstrofe (ˋ) &apos;
El signo & (&) &amp;

También es importante saber que si es un número el que se quiere evaluar en la condición NO introduciremos los apóstrofos, si es un texto sí. Por ejemplo, si queremos mostrar un campo con el formato success si el campo importe es mayor de 1000, introduciremos el siguiente atributo:

Los tipos son excluyentes, sólo se puede mostrar el valor del campo con uno de los formatos posibles, por lo tanto, sin introduciremos varios tipos debemos asegurarnos de que la condición sólo se cumpla en uno de ellos.

Botón de acción

Framework ProyectoA PHP permite generar botones de acción asociados con cada registro de un grid/rejilla de datos.

Botón de acción en Framework ProyectoA PHP

Para definir estos botones usaremos el siguiente XML en la tabla donde queramos mostrarlos (siempre en el fichero modulos.xml) y al final de los campos:

Ejemplo para botón de detalle, para mostrar ventana emergente con los datos adicionales del registro actual:

Ejemplo para botón de modificación de registro actual, para mostrar ventana con formulario de modificación del registro actual:

Ejemplo para botón de eliminar registro actual, para eliminar el registro actual de la base de datos:

 

Generar menús en Framework ProyectoA PHP

Framework ProyectoA PHP también permite la generación de menús de forma automática, leyendo los datos de un fichero XML, que puede tener la siguiente estructura de ejemplo:

 

Generando un menú de este estilo:

 

Algunas funciones de PHP para usar en el desarrollo web personalizado

Si queremos personalizar nuestra WebApp partiendo del Framework ProyectoA PHP dispondremos de una serie de funciones y procedimientos ya desarrollados que nos pueden ser muy útiles. A continuación argumentamos algunos de ellos.

mostrarAviso

Si queremos avisar al usuario mediante un mensaje podremos usar la función mostrarAviso:

Dicha función admite varios tipos de aviso que pasaremos mediante el parámetro $tipo:

  • success.
  • warning.
  • info.
  • danger.

Un ejemplo de su uso:

 

Futuras mejoras para nuevas versiones de Framework ProyectoA PHP

  • [PENDIENTE] Posibilidad de mostrar tablas relacionadas en una misma ventana (en maestro/detalle), con selección de registro de tabla detalle.
  • [RESUELTO] Desplegable dependiente de otro desplegable. Según el valor elegido en otro desplegable mostrar los elementos del secundario con un filtro dado.
  • [PENDIENTE] Mejorar grid (rejilla de datos) con filtros, tarda mucho en cargar cuando son muchos registros en la tabla, dado que los carga todos (sin limit).
  • [PENDIENTE] Campos autogenerados que obtengan el valor por defecto de una función de otro fichero.