Documentos de Académico
Documentos de Profesional
Documentos de Cultura
Manual para Desarrolladores-Elastix PDF
Manual para Desarrolladores-Elastix PDF
VERSIONAMIENTO
Versin Versin de
Elastix
1
2.3.0
Fecha
Elaborado por
Detalles
16-Ene-2012
Documentacin Inicial
Introduccin
El presente manual es una gua para desarrolladores en la utilizacin del Framework
Elastix para la creacin de nuevos mdulos.
En este manual se explicar como se puede crear un mdulo Elastix, Fundamentos
Bsicos del Framework Elastix, y cmo llegar a convertir nuestro nuevo mdulo en
un Addon de Elastix.
Imagen 1.- Identificacin del addon Developer.
Luego de esto se inicia el proceso de instalacin del addon, por lo que se debe
esperar unos minutos hasta que finalice la instalacin.
Imagen 2.- Finalizacin de la instalacin del addon Developer.
Pantallas prototipo. Estas pantallas pueden ser de tres tipos: formulario, reporte
y enmarcado.
Informacin General.
Localizacin.
Descripcin del mdulo.
Informacin General
Esta seccin nos permite definir el nombre e identificador nico del mdulo, as
como tambin los datos de la persona que crea el modulo para comentarlas en las
cabeceras de cada archivo de programacin en PHP. Tambin nos permite
configurar el nivel de accesibilidad que tendr el mdulo a travs del parmetro
Permisos de Grupo.
Localizacin
En esta seccin se configura el lugar, dentro del men general, donde vamos a
ubicar el nuevo mdulo. Por omisin esta seccin luce como la siguiente figura.
Imagen 5.- Seccin donde se configura la ubicacin del mdulo
Imagen 6.- Aparecen nuevos campos si se dice que el mdulo ser de nivel 3
Descripcin
Con los botones ">>", "<<" podemos aadir o quitar los campos a insertar en nuestro
formulario.
Al guardar los datos establecidos para el nuevo mdulo se crear el siguiente rbol
de directorios (exceptuando para los mdulos tipo enmarcado, en cuyo caso el
mdulo ser simplemente un link al URL proporcionado) en la ruta
documentRoot/modules donde documentRoot es /var/www/html para Elastix.
Como se puede notar, un modulo tiene la misma arquitectura
general del framework, arquitectura web MVC2. Por ende se define
a esto como un MVC2 dentro de otro MVC2, una definicin de
recursividad de grado 2.
Esto nos permite de forma inmediata hacer una similitud entre las
carpetas que tienen las siguientes relaciones:
themes es la capa vista.
index.php es la capa control.
libs es la capa modelo.
1.3 Breve descripcin de cada carpeta que se crea dentro del mdulo
configs
Por default esta carpeta se crea con un archivo denominado default.conf.php, este
archivo debe contener las configuraciones bsicas del mdulo.
Almacena dentro de este archivo variables de configuracin que sern muy usadas
a lo largo del mdulo, por ejemplo DSN
Sqlite3: sqlite3:///$arrConf[elastix_dbdir]/base.db
Mysql: se puede usar la funcin generarDSNSistema la cual ya nos devuelve
el string de conexin. A continuacin se detallar un poco esta funcin que la
podemos encontrar en /var/www/html/libs/misc.lib.php
/**
* Funcin para construir un DSN para conectarse a varias bases de datos
* frecuentemente utilizadas en Elastix. Para cada base de datos reconocida, se
* busca la clave en /etc/elastix.conf o en /etc/amportal.conf segn corresponda.
*
* @param string $sNombreUsuario Nombre de usuario para interrogar
* @param string $sNombreDB
Nombre de base de datos para DSN
* @param string $ruta_base
Ruta base para inclusin de libreras
*
* @return mixed NULL si no se reconoce usuario, o el DSN con clave resuelta
*/
function generarDSNSistema($sNombreUsuario, $sNombreDB, $ruta_base='')
help
Dentro de esta carpeta encontraremos un archivo llamado id_modulo.hlp. Este es
el archivo que se encarga de mostrar la ayuda embebida del mdulo.
Es recomendable que una vez que hayas terminado tu mdulo por completo,
elabores la ayuda embebida que no es otra cosa que una especie de manual
de usuario, indicando las diferentes opciones que ofrece este mdulo. Es
recomendable que sea escrita en ingls.
<h1>{$node_name}</h1>
<p align="Justify">This is the embedded help for my module.</p>
<div><img src="../modules/{$node_id}/images/image.png" border="0"></div>
<div>Figure 1</div><br/>
</body>
</html>
images
Dentro de esta carpeta se guardarn todas las imgenes propias del mdulo, por
ejemplo cono, imgenes usadas para la ayuda embebida, etc.
lang
Como ya sabemos el Framework Elastix soporta traduccin de idiomas!! Pues bien,
como es de suponer dentro de esta carpeta se almacenan las traducciones para
nuestro mdulo. Cada traduccin para cada idioma se almacena en un archivo
diferente, de acuerdo a la siguiente tabla:
Archivo
bg.lang
br.lang
ca.lang
cn.lang
da.lang
de.lang
en.lang
Idioma
Blgaro
Portugus
Cataln
Chino Simplificado
Dans
Alemn
Ingls
el.lang
es.lang
fa.lang
fr.lang
it.lang
hu.lang
hr.lang
pl.lang
ro.lang
ru.lang
sl.lang
sv.lang
ko.lang
ja.lang
sr.lang
Griego
Espaol
Persa
Francs
Italiano
Hngaro
Croata
Polaco
Rumano
Ruso
Esloveno
Sueco
Coreano
Japons
Serbio
Se recomienda que se creen al menos dos archivos de traducciones, uno con el
idioma nativo del desarrollador y otro en ingls
libs
Como ya se mencion anteriormente esta es nuestra capa de modelo. Dentro de
esta carpeta habr una librera que es la que se encargar de hacer consultas a
bases de datos, modificar archivos, etc.
Todos los querys que se realicen deben de ser parametrizados, esto evitar la
inyeccin de cdigo SQL arbitrario a nuestra base. Ms adelante se explicar
con mayor detalle como hacerlo.
Recuerda que nuestro servicio de apache corre usando el usuario asterisk, por
ende slo tendremos acceso a archivos y carpetas a los cuales asterisk tenga
acceso. No podrs leer o escribir sobre un archivo o carpeta por ejemplo que tenga
solo permisos para root.
No hagas uso de comandos de consola que necesitan de privilegios root. Esto
puede conllevar a que nuestro script o librera se convierta en un potencial hueco
de seguridad.
Pero y que pasa si nuestro script o librera necesita obligadamente usar comandos
que requieren privilegios de root? Es ah donde entra en accin nuestro script
elastix-helper.
1.4 Uso de elastix-helper
elastix-helper es un script ubicado en /usr/bin el cual permite ejecutar scripts
privilegiados que se encuentran dentro de la carpeta:
/usr/share/elastix/privileged.
Es aqu donde ubicaremos al script que realizar tareas que necesiten privilegios de
root, este script debe ser propietario root y pertenecer al grupo root adems
tener permisos 755. Para poder usarlo debemos ejecutar el siguiente cdigo en la
funcin que deseemos de nuestra librera.
exec("/usr/bin/elastix-helper script_privileged parameter", $output, $ret);
themes
Esta carpeta es la capa de vista. Al interior de esta carpeta encontraremos otra
carpeta llamada default la cual contendr todas las vistas que podr tener el
mdulo.
Por ejemplo, un mdulo puede contener como vista principal una grilla, por lo que se
necesitar una vista (un archivo tpl) que contendr los filtros para la grilla (en caso
de haberlos, caso contrario no se necesitara un archivo tpl), y tambin podra ser
que al presionar un botn se muestre un formulario, por lo que necesitaramos otro
archivo tpl que contendr los campos del formulario.
A continuacin mostraremos una plantilla tpica de una vista para tpl y otra para un
formulario.
Plantilla tpica de un mdulo con vista grilla
<table width="99%" border="0" cellspacing="0" cellpadding="0" align="center">
<tr class="letra12">
<td width="12%" align="left"><input class="button" type="submit"
name="new" value="{$New}"></td>
<td width="10%" align="left"> </td>
<td width="10%" align="right">
{$filter_type.LABEL}: {$filter_type.INPUT}
{$filter_txt.INPUT}
<input class="button" type="submit" name="show" value="{$SHOW}" />
</td>
</tr>
</table>
Como se puede observar en este mdulo de grilla se consta con un botn New y
con un filtrado.
Plantilla tpica de un mdulo con vista formulario
<table width="99%" border="0" cellspacing="0" cellpadding="4" align="center">
<tr class="letra12">
<td align="left"><input class="button" type="submit" name="save"
value="{$SAVE}"></td>
</tr>
</table>
<br />
<div class="tabForm" style="font-size: 16px; height: auto;" width="100%">
<table style="font-size: 16px;" width="100%" cellspacing="0" cellpadding="8">
<tr class="letra12">
<td align="left" width="130px"><b>{$manufacturer.LABEL}: </b></td>
<td align="left">{$manufacturer.INPUT}</td>
</tr>
</table>
</div>
Para este formulario se consta con un botn Save y con un campo al cual se le
denomin manufacturer.
Estas son plantillas bsicas, en realidad uno lo puede hacer tan complejo como uno
quiera.
Si queremos incluir javascripts en nuetro mdulo, simplemente debemos crear una
carpeta llamada js dentro de themes/default y colocar ahi los javascripts que
queramos (deben tener extensin .js), as mismo si queremos incluir css hay que
crear una carpeta llamada css dentro de themes/default y colocar ahi los css que
queramos (deben tener extensin .css), el framework se encargar de incluir estos
archivos automticamente.
index.php
El archivo index.php del mdulo representa la capa de control, el framework se
encarga de redirigir la peticin a este archivo llamando a la funcin
_moduleContent. Este archivo es el que se encarga de comunicar con la capa de
vista y de modelo.
Si hemos usado el developer para la creacin del mdulo, podremos observar que
este archivo ya viene escrito con una plantilla por default, y sobre esta plantilla
podemos hacer las modificaciones que queramos de acuerdo a la necesidad de
nuestro mdulo.
function _tr($s)
Esta es la funcin que utilizamos para realizar la traduccin de algn texto. Recibe
como parmetro un string que es el texto a traducir.
La funcin trabaja de la siguiente manera:
Busca el string pasado como parmetro en las claves del arreglo de lenguajes del
framework y del mdulo (archivo .lang dentro de la carpeta lang del mdulo,
escoger el archivo correspondiente al lenguaje que este configurado en el servidor
Elastix), en caso de encontrarla la funcin devuelve el valor del arreglo para esa
clave, caso contrario devuelve el mismo string pasado como parmetro.
Ejemplo:
Si tenemos seleccionado espaol como lenguaje y queremos la traduccin de Hi
this is my first module (definida previamente en el archivo es.lang), simplemente
hacemos lo siguiente:
$translate = _tr(Hi this is my first module);
function getParameter($parameter)
function obtenerClaveCyrusAdmin($ruta_base='')
function obtenerClaveAMIAdmin($ruta_base='')
Esta funcin retorna la clave para AMI (Asterisk Manager Interface) del usuario
admin. El parmetro $ruta_base debe ser pasado como /var/www/html/ si
llamamos a esta funcin fuera de esa ruta.
Esta funcin busca la clave en el archivo /etc/elastix.conf, si se encuentra la
palabra clave amiadminpwd se retorna el valor de esa clave, caso contrario se
retorna elastix456 que es la clave AMI por default en Elastix.
Ya nos habamos topado antes en este manual con esta funcin. Pero afianzaremos
ms lo que se dijo acerca de esta til funcin. Como ya lo habamos mencionado
antes esta funcin retorna el DSN (Data Source Name) para una conexin con el
motor de bases de datos mysql.
El parmetro $ruta_base debe ser pasado como /var/www/html/ si llamamos a
esta funcin fuera de esa ruta.
El parmetro $sNombreUsuario es el usuario con el cual nos conectaremos a mysql,
puede ser root o asteriskuser.
El parmetro $sNombreDB es el nombre de la base de datos mysql a la cual nos
vamos a conectar.
crear archivos ah sin inconvenientes.
Ejemplo:
Si queremos escribir Ha ingresado al mdulo de prueba en un log llamado
miModulo.log tendramos que hacer lo siguiente:
writeLOG(miModulo.log,Ha ingresado al mdulo de prueba);
Una vez instanciada esta clase recuerda pasarla por referencia a las funciones
requeridas, esto ser muy importante sobre todo cuando trabajemos con
transacciones.
A continuacin se detallarn algunas de sus funciones.
Es el procedimiento que recupera todas las filas resultado de una peticin SQL que
devuelve una o ms filas.
Los parmetros $query y $param tienen los mismos propsitos que los descritos en
la funcin anterior.
El parmetro $arr_colnames ser FALSE si deseamos que cada tupla tenga como
ndice un nmero incremental, si es TRUE cada tupla tendr como ndice el nombre
de la columna.
Ejemplo:
Supongamos que deseamos imprimir en pantalla los valores de la columna
campo1 de la tabla miTabla cuando el campo2 tiene como valor $value2, as
mismo asumamos que ya contamos con el objeto $pDB.
$query = SELECT campo1 FROM miTabla WHERE campo2=?;
$arrParam = array($value2);
$result = $pDB->fetchTable($query,TRUE,$arrParam);
if($result === FALSE)
echo _tr(Query Error). .$pDB->errMsg;
else{
if(count($result) > 0){
foreach($result as $value){
echo $value[campo1].<br />;
}
}
else
echo _tr(There is no data for the criteria search);
}
Procedimiento para recuperar una sola fila del query que devuelve una o ms filas.
Devuelve una fila con campos si el query devuelve al menos una fila, caso contrario
devuelve un arreglo vaco o FALSE en caso de error.
Los parmetros $query, $arr_colnames y $param tienen los mismos propsitos que
los descritos en la funcin fetchTable.
Ejemplo:
Supongamos que queremos imprimir en pantalla la cantidad de registros en la tabla
miTabla cuyo campo1 tiene como valor $value1
$query = SELECT COUNT(*) FROM miTabla WHERE campo1=?;
$arrParam = array($value1);
$result = $pDB-> getFirstRowQuery($query,FALSE,$arrParam);
if($result === FALSE)
echo _tr(Query Error). .$pDB->errMsg;
else
echo $result[0];
function beginTransaction()
function rollBack()
function commit()
function insertRegister($value1, $value2, &$pDB, &$errMsg)
{
$pDB->beginTransaction();
$query1 = INSERT INTO miTabla1 (campo1,campo2) VALUES (?,?);
$arrParam1 = array($value1, $value2);
$result1 = $pDB->genQuery($query1,$arrParam1);
if($result1 == FALSE){
$pDB-> rollBack();
$errMsg = $pDB->errMsg;
return FALSE;
}
else{
$query2 = INSERT INTO miTabla2 (id_miTabla1,fecha)
VALUES((SELECT id FROM miTabla1 WHERE
campo1=? AND campo2=?),?);
}
else{
$pDB->commit();
return TRUE;
}
}
}
Observemos que el objeto $pDB fue pasado por referencia a la funcin, lo cual es
necesario para que la transaccin tenga el comportamiento deseado.
NOTA: Ten en cuenta que existen motores de bases de datos que no soportan
transacciones como es el caso del motor MyISAM de mysql, en estos casos se debe
asegurar que la tabla que queremos que funcione con transacciones tenga un motor
compatible con transacciones como InnoDB o BDB.
Para instanciar la clase se debe pasar el string DSN para la conexin a la base de
datos acl.db o tambin se le puede pasar un objeto que sea una instancia de la
clase paloDB que se le haya pasado el DSN para acl.db.
La variable $arrConf['elastix_dsn']['acl'] contiene ya el DSN para acl.db, esta
variable es creada por el framework. Por lo tanto si queremos instanciar a esta clase
dentro de nuestro mdulo haramos lo siguiente:
global $arrConf;
$pACL = new paloACL($arrConf['elastix_dsn']['acl']);
function getUserExtension($username)
Ejemplo:
Supongamos que queremos obtener la extensin asociada al usuario logoneado.
//El
usuario
logoneado
se
almacena
en
la
$_SESSION[elastix_user]
$username = $_SESSION[elastix_user];
$extension = $pACL->getUserExtension($username);
variable
de
sesin
function isUserAdministratorGroup($username)
Si deseamos que nuestro mdulo haga ciertas tareas si el usuario logoneado es del
grupo administrador y otras si no, podramos hacer lo siguiente:
$username = $_SESSION[elastix_user];
if($pACL->isUserAdministratorGroup($username)){
//Do some task for administrators
}
else{
//Do some task for non administrators
}
$pConfig = new paloConfig(/etc,miModulo.conf, = ,\s*=\s*);
function leer_configuracion($bComentarios=true)
function escribir_configuracion($arr_reemplazos,
$overwrite=FALSE)
Procedimiento que devuelve el valor de una palabra clave del archivo. El parmetro
$lista es el arreglo que contiene el archivo de configuracin. El parmetro $clave es
la palabra clave a buscar en el archivo.
Ejemplo:
Supongamos que tenemos el archivo /etc/miModulo.conf con la misma
informacin que ya se describi ms arriba, y queremos hacer lo siguiente: si
password es igual a 12345 entonces la cambiamos a new12345.
include_once libs/paloSantoConfig.class.php;
$pConfig = new paloConfig(/etc,miModulo.conf, = ,\s*=\s*);
$content = $pConfig->leer_configuracion(FALSE);
$password = $pConfig->privado_get_valor($content,password);
if($password == 12345){
$arrReplaces = array(password => new12345);
$pConfig->escribir_configuracion($arrReplaces);
}
TEXTAREA
Ejemplo:
Se desea un textarea cuyo label sea descripcin y que tenga 6 columnas y 4 filas.
$arrFormElements = array(
"description" => array(
"LABEL"
"REQUIRED"
"INPUT_TYPE"
"INPUT_EXTRA_PARAM"
"VALIDATION_TYPE"
=>
=>
=>
=>
=>
_tr("Description"),
"yes",
"TEXTAREA",
array("style" => width:400px"),
"text",
"VALIDATION_EXTRA_PARAM"
"ROWS"
"COLS"
),
=> "",
=> "4",
=> "6"
);
TEXT
Ejemplo:
Se desea un input para ingresar el nombre de un cliente.
$arrFormElements = array(
"name"
=> array(
"LABEL"
"REQUIRED"
"INPUT_TYPE"
"INPUT_EXTRA_PARAM"
"VALIDATION_TYPE"
"VALIDATION_EXTRA_PARAM"
),
);
=>
=>
=>
=>
=>
=>
_tr("Name"),
"yes",
"TEXT",
array("style" => width:200px"),
"text",
""
=>
=>
=>
=>
=>
=>
_tr("Enable"),
"yes",
"CHECKBOX",
" ",
"text",
""
CHECKBOX
Ejemplo:
Se desea un checkbox que diga Enable.
$arrFormElements = array(
"enable"
=> array( "LABEL"
"REQUIRED"
"INPUT_TYPE"
"INPUT_EXTRA_PARAM"
"VALIDATION_TYPE"
"VALIDATION_EXTRA_PARAM"
),
);
tanto si en nuestro mdulo queremos saber si el checkbox fue activado o no,
tendramos que hacer lo siguiente:
$enable = getParameter(enable);
if($enable == on){
//Do something
}
else{
//Do something
}
PASSWORD
Ejemplo:
Se desea un campo para que el usuario ingrese una contrasea.
$arrFormElements = array(
"password"
=> array( "LABEL"
"REQUIRED"
"INPUT_TYPE"
"INPUT_EXTRA_PARAM"
"VALIDATION_TYPE"
"VALIDATION_EXTRA_PARAM"
),
);
=> _tr("Password"),
=> "yes",
=> "PASSWORD",
=>array("style" => width:200px"),
=> "text",
=> ""
HIDDEN
Ejemplo:
Se desea tener un campo oculto para almacenar el id de un usuario.
$arrFormElements = array(
"id"
=> array( "LABEL"
"REQUIRED"
"INPUT_TYPE"
"INPUT_EXTRA_PARAM"
"VALIDATION_TYPE"
"VALIDATION_EXTRA_PARAM"
),
);
=>
=>
=>
=>
=>
=>
" ",
"yes",
"HIDDEN",
" ",
"text",
""
FILE
Ejemplo:
Se desea un campo para poder pasar la ruta de un archivo.
$arrFormElements = array(
"file"
=> array(
"LABEL"
"REQUIRED"
"INPUT_TYPE"
"INPUT_EXTRA_PARAM"
"VALIDATION_TYPE"
"VALIDATION_EXTRA_PARAM"
),
);
=>
=>
=>
=>
=>
=>
_tr("File"),
"yes",
"FILE",
" ",
"filename",
""
RADIO
Ejemplo:
Se desea 2 radio buttons para indicar el gnero de una persona.
$gender = array(m => _tr(Male), f
$arrFormElements = array(
"gender"
=> array( "LABEL" =>
"REQUIRED"
=>
"INPUT_TYPE"
=>
"INPUT_EXTRA_PARAM"
=>
"VALIDATION_TYPE"
=>
"VALIDATION_EXTRA_PARAM" =>
),
);
=> _tr(Female));
_tr("Gender"),
"yes",
"RADIO",
$gender,
"text",
""
SELECT
Ejemplo:
Se desea un combo para seleccionar el mtodo de pago que va a realizar un cliente,
siendo las opciones efectivo, tarjeta de crdito, cheque, transferencia bancaria.
$paymentMethod = array(cash => _tr(Cash), credit_card => _tr(Credit
Card), check => _tr(Check),bank_transfer => _tr(Bank Transfer));
$arrFormElements = array(
"paymentMethod" => array("LABEL" => _tr("Payment Method"),
"REQUIRED"
=> "yes",
"INPUT_TYPE"
=> "SELECT",
"INPUT_EXTRA_PARAM"
=> $paymentMethod,
"VALIDATION_TYPE"
=> "text",
"VALIDATION_EXTRA_PARAM"
),
=> ""
);
DATE
Ejemplo:
Se desea un campo para ingresar la fecha en la cual se realiz un pago.
$arrFormElements = array(
"paymentDate"
=> array( "LABEL"
"REQUIRED"
=>
"INPUT_TYPE"
=>
"INPUT_EXTRA_PARAM"
=>
"VALIDATION_TYPE"
=>
"VALIDATION_EXTRA_PARAM" =>
),
);
El formato por default de la fecha es el da en dos dgitos, luego espacio seguido del
mes en formato de tres letras, luego espacio y el ao en cuatro dgitos. Si se desea
cambiar este formato simplemente habra que colocar en INPUT_EXTRA_PARAM
el nuevo formato, y si deseamos tambin poder ingresar la hora colocamos TIME
=> true.
Como se pudo observar en los ejemplos anteriores existen ndices que coincidan en
todos y otros que simplemente eran propios del tipo de elemento, como por ejemplo
el ndice COLS en el TEXTAREA. Ahora explicaremos sobre los ndices comunes
u obligatorios.
LABEL: El valor de este ndice, como su nombre lo indica, ser la etiqueta
descriptiva que se muestra junto al elemento.
REQUIRED: El valor de este ndice puede ser yes o no, si es yes entonces este
campo es obligatorio para poder guardar el formulario, caso contrario este puede
quedar en blanco.
INPUT_TYPE: Tipo de elemento, ya descrito previamente.
INPUT_EXTRA_PARAM: Parmetros adicionales al input, pueden ser estilos o
atributos extras. Estos deben pasarse como arreglo, caso contrario debe ser un
string vaco.
VALIDATION_TYPE: Indica el tipo de validacin que se le va a aplicar al valor
ingresado por el usuario. Los valores pueden ser los siguientes:
text - El usuario puede ingresar cualquier cosa.
ereg - Se debe pasar en VALIDATION_EXTRA_PARAM una expresin
regular, y se le permitir ingresar al usuario slo un texto que coincida con
le expresin regular ingresada.
filename - Se valida que lo que se ingrese en ese campo sea el nombre
de un archivo.
domain - Se valida que lo que se ingrese en ese campo se el nombre de
un dominio.
filepath - Se valida que lo que se ingrese en ese campo sea una ruta a un
archivo.
ip - Se valida que lo que se ingrese en ese campo sea una direccin ip.
mask - Se valida que lo que se ingrese en ese campo sea una mscara
de red.
ip/mask - Se valida que lo que se ingrese en ese campo sea una
direccin ip seguido de / y la mscara de red en formato decimal.
numeric - Se valida que lo que se ingrese en ese campo sea un nmero.
float - Se valida que lo que se ingresa en ese campo sea un nmero
flotante (decimal con el punto como separador).
numeric_array - Se valida que lo que se ingresa en ese campo sea un
arreglo cuyos elementos sean nmeros.
ereg_array - Se valida que lo que se ingresa en ese campo sea un
arreglo con valores que deben coincidir con la expresin regular pasada
en VALIDATION_EXTRA_PARAM.
email - Se valida que lo que se ingresa en ese campo sea una direccin
de correo electrnico.
A continuacin se describirn las funciones que ofrece esta clase.
Esta funcin genera una cadena que contiene un formulario HTML. Para hacer esto,
toma una plantilla de formulario (que es la pasada en el parmetro $templateName)
e inserta en ella los elementos de formulario. El parmetro $title es el ttulo que
tendr el formulario y el parmetro $arrPreFilledValues es un arreglo que contiene
valores por defecto para el formulario, donde el ndice es el id del elemento y el valor
es el (valga la redundancia) valor que tendra ese campo por defecto.
function validateForm($arrCollectedVars)
Esta funcin devuelve TRUE en caso de que los datos ingresados en el formulario
fueron correctos, caso contrario FALSE. El parmetro $arrCollectedVars contiene
los valores ingresados en el formulario.
Ejemplo:
Supongamos que deseamos un mdulo tipo formulario, el cual tenga los campos:
Nombre que es una caja de texto, Apellido que es una caja de texto, Gnero
que es un radio button que puede ser masculino o femenino, Email que es una caja
de texto y Estado Civil que puede ser Soltero, Viudo, Casado, Divorciado o Unin
Libre. Todos estos campos son requeridos. Tambin hay un botn Save que al
presionar se validan los datos ingresados, en caso de haber un error se mantiene
persistencia en los datos y se indica el error, caso contrario se muestra un mensaje
indicando los datos ingresados.
File themes/default/form.tpl
<table width="100%" border="0" cellspacing="0" cellpadding="4"
align="center">
<tr class="letra12">
<td align="left">
<input class="button" type="submit" name="save"
value="{$SAVE}">
</td>
<td align="right" nowrap><span class="letra12"><span
class="required">*</span> {$REQUIRED_FIELD}</span></td>
</tr>
</table>
<table class="tabForm" style="font-size: 16px;" width="100%" >
<tr class="letra12">
<td align="left" width="130px"><b>{$name.LABEL}: <span
class="required">*</span></b></td>
<td align="left">{$name.INPUT}</td>
</tr>
<tr class="letra12">
<td align="left"><b>{$last_name.LABEL}: <span
class="required">*</span></b></td>
<td align="left">{$last_name.INPUT}</td>
</tr>
<tr class="letra12">
<td align="left"><b>{$gender.LABEL}: <span
class="required">*</span></b></td>
<td align="left">{$gender.INPUT}</td>
</tr>
<tr class="letra12">
<td align="left"><b>{$email.LABEL}: <span
class="required">*</span></b></td>
<td align="left">{$email.INPUT}</td>
</tr>
<tr class="letra12">
<td align="left"><b>{$marital_status.LABEL}: <span
class="required">*</span></b></td>
<td align="left">{$marital_status.INPUT}</td>
</tr>
</table>
File index.php
<?php
include_once "libs/paloSantoForm.class.php";
function _moduleContent(&$smarty, $module_name)
{
//include module files
include_once "modules/$module_name/configs/default.conf.php";
//include file language agree to elastix configuration
//if file language not exists, then include language by default (en)
$lang=get_language();
$base_dir=dirname($_SERVER['SCRIPT_FILENAME']);
$lang_file="modules/$module_name/lang/$lang.lang";
if (file_exists("$base_dir/$lang_file")) include_once "$lang_file";
else include_once "modules/$module_name/lang/en.lang";
//global variables
global $arrConf;
global $arrConfModule;
global $arrLang;
global $arrLangModule;
$arrConf = array_merge($arrConf,$arrConfModule);
$arrLang = array_merge($arrLang,$arrLangModule);
//folder path for custom templates
$templates_dir=(isset($arrConf['templates_dir']))?
$arrConf['templates_dir']:'themes';
$local_templates_dir="$base_dir/modules/$module_name/".$templates_dir.'/'.
$arrConf['theme'];
//conexion resource
//$pDB = new paloDB($arrConf['dsn_conn_database']);
$pDB = ""; //In this case we do not use a database
//actions
$action = getAction();
$content = "";
switch($action){
case "save":
$content = saveTestModule($smarty, $module_name,
$local_templates_dir);
break;
default: // view_form
$content = viewFormTestModule($smarty, $module_name,
$local_templates_dir);
break;
}
return $content;
}
function viewFormTestModule($smarty, $module_name, $local_templates_dir)
{
$arrFormTestModule = createFieldForm();
$oForm = new paloForm($smarty,$arrFormTestModule);
//begin, Form data persistence to errors and other events.
$_DATA = $_POST;
$smarty->assign("SAVE", _tr("Save"));
$smarty->assign("REQUIRED_FIELD", _tr("Required field"));
$smarty->assign("icon", "images/list.png");
$htmlForm = $oForm->fetchForm("$local_templates_dir/form.tpl",_tr("Test
Module"), $_DATA);
$content = "<form method='POST' style='margin-bottom:0;'
action='?menu=$module_name'>".$htmlForm."</form>";
return $content;
}
function saveTestModule($smarty, $module_name, $local_templates_dir)
{
$arrFormTestModule = createFieldForm();
$oForm = new paloForm($smarty,$arrFormTestModule);
if(!$oForm->validateForm($_POST)){
// Validation basic, not empty and VALIDATION_TYPE
$smarty->assign("mb_title", _tr("Validation Error"));
$arrErrores = $oForm->arrErroresValidacion;
$strErrorMsg = "<b>"._tr("The following fields contain
errors").":</b><br/>";
if(is_array($arrErrores) && count($arrErrores) > 0){
foreach($arrErrores as $k=>$v)
$strErrorMsg .= "$k, ";
}
$smarty->assign("mb_message", $strErrorMsg);
return viewFormTestModule($smarty, $module_name,
$local_templates_dir);
}
else{
//Here are extra validations
$name = getParameter("name");
$last_name = getParameter("last_name");
$gender = getParameter("gender");
$email = getParameter("email");
$marital_status = getParameter("marital_status");
if(!in_array($gender,array("male","female"))){
$smarty->assign("mb_title", _tr("Validation Error"));
$smarty->assign("mb_message", _tr("The gender can only be
\"male\" or \"female\""));
return viewFormTestModule($smarty, $module_name,
$local_templates_dir);
}
elseif(!in_array($marital_status,array("single","widowed","marr
ied","divorced","cohabiting"))){
$smarty->assign("mb_title", _tr("Validation Error"));
$smarty->assign("mb_message", _tr("The marital status can
only be \"single\", \"widowed\", \"married\", \"divorced\" or
\"cohabiting\""));
return viewFormTestModule($smarty, $module_name,
$local_templates_dir);
}
else{
$smarty->assign("mb_title", _tr("Message"));
$message = _tr("The following data was entered").":<br />";
$message .= "<b>"._tr("Name").":</b>
".htmlentities($name)."<br /><b>"._tr("Last Name").":</b>
".htmlentities($last_name)."<br /><b>"._tr("Gender").":</b>
".htmlentities($gender)."<br /><b>"._tr("Email").":</b>
".htmlentities($email)."<br /><b>"._tr("Marital Status").":</b>
".htmlentities($marital_status);
$smarty->assign("mb_message",$message);
}
}
return viewFormTestModule($smarty, $module_name, $local_templates_dir);
}
function createFieldForm()
{
$gender = array("male" => _tr("Male"), "female" => _tr("Female"));
$marital_status = array("single" => _tr("Single"), "widowed" =>
_tr("Widowed"), "married" => _tr("Married"), "divorced" => _tr("Divorced"),
"cohabiting" => _tr("Cohabiting"));
$arrFields = array(
"name"
=> array("LABEL"
"REQUIRED"
"INPUT_TYPE"
"INPUT_EXTRA_PARAM"
"VALIDATION_TYPE"
"VALIDATION_EXTRA_PARAM"
),
"last_name"
=> array("LABEL"
"REQUIRED"
"INPUT_TYPE"
"INPUT_EXTRA_PARAM"
"VALIDATION_TYPE"
"VALIDATION_EXTRA_PARAM"
),
"gender"
=> array("LABEL"
"REQUIRED"
"INPUT_TYPE"
"INPUT_EXTRA_PARAM"
"VALIDATION_TYPE"
"VALIDATION_EXTRA_PARAM"
),
"email"
=> array("LABEL"
"REQUIRED"
"INPUT_TYPE"
"INPUT_EXTRA_PARAM"
=>
=>
=>
=>
=>
=>
_tr("Name"),
"yes",
"TEXT",
"",
"text",
""
=>
=>
=>
=>
=>
=>
_tr("Last Name"),
"yes",
"TEXT",
"",
"text",
""
=>
=>
=>
=>
=>
=>
_tr("Gender"),
"yes",
"RADIO",
$gender,
"text",
""
=>
=>
=>
=>
_tr("Email"),
"yes",
"TEXT",
"",
"VALIDATION_TYPE"
"VALIDATION_EXTRA_PARAM"
),
"marital_status" => array("LABEL"
"REQUIRED"
"INPUT_TYPE"
"INPUT_EXTRA_PARAM"
"VALIDATION_TYPE"
"VALIDATION_EXTRA_PARAM"
=> "email",
=> ""
=>
=>
=>
=>
=>
_tr("Marital Status"),
"yes",
"SELECT",
$marital_status,
"text",
=> ""
),
);
return $arrFields;
}
function getAction()
{
if(getParameter("save"))
return "save";
else
return "report";
}
?>
Imagen 8.- Vista del mdulo tipo formulario segn el cdigo descrito anteriormente
function paloSantoGrid($smarty)
Esta funcin permite agregar un elemento a la grilla tipo link. El parmetro $href es
hacia dnde apunta el link, el parmetro $alt es el label que se mostrar para el
elemento, el parmetro $icon es la ruta a una imagen que ser el cono
representativo del elemento y el parmetro $onclick es el evento que se va a vincular
al hacer click en dicho link (opcional).
Esta funcin permite agregar un elemento a la grilla tipo submit. El parmetro $task
es el atributo name del elemento, el parmetro $alt es el label que se mostrar
para el elemento, el parmetro $icon es la ruta a una imagen que ser el cono
representativo del elemento y el parmetro $onclick es el evento que se va a vincular
al hacer click en dicho elemento (opcional).
Esta funcin permite agregar un elemento a la grilla tipo botn. El parmetro $name
es el atributo name del elemento, el parmetro $alt es el label que se mostrar
para el elemento, el parmetro $icon es la ruta a una imagen que ser el cono
representativo del elemento y el parmetro $onclick es el evento que se va a vincular
al hacer click en dicho elemento (opcional).
Esta funcin permite agregar un elemento a la grilla tipo input text. El parmetro
$name_input es el atributo name del elemento, el parmetro $label es el label que
se mostrar para el elemento, el parmetro $value_input es el valor por default del
input, el parmetro $task es la accin que se enva al servidor al presionar el botn
asociado a la caja de texto y el parmetro $onkeypress_text es el evento que se
asociar a la caja de texto cada vez que se presiona una tecla.
Esta funcin permite agregar un elemento a la grilla tipo combo box. El parmetro
$name_select es el atributo name del elemento, el parmetro $label es el label
que se mostrar para el elemento, el parmetro $data es un arreglo con los datos
del combo, el parmetro $selected es el elemento seleccionado por default, el
parmetro $task es la accin que se enva al servidor al presionar el botn
asociado al combo y el parmetro $onchange_select es el evento que se asociar al
combo cada vez que se cambia el valor del combo.
function addHTMLAction($html)
Esta funcin permite agregar un nuevo elemento tipo html a la grilla. El parmetro
$html es el cdigo html a aadir.
function PaloSantoJSON()
function createJSON()
Codifica la respuesta en JSON con el formato mencionado anteriormente.
function set_error($error)
Setea el valor del ndice error por lo que tenga el parmetro $error.
function set_status($status)
Setea el valor del ndice statusResponse por lo que tenga el parmetro $status.
function set_message($message)
Setea el valor del ndice message por lo que tenga el parmetro $message.
3. AJAX en Elastix
El framework Elastix tambin cuenta con una funcin javascript para realizar
peticiones AJAX!!. Esta funcin es la siguiente:
function getTextTranslate(text)
{
var arrAction
= new Array();
arrAction["menu"]
= "testModule";
arrAction["action"]
= "translate";
arrAction["text"]
= text;
arrAction["rawmode"]
= "yes"; //Remember, this is necessary
because in this way the server will only response the content of the module
that will be a JSON.
request("index.php",arrAction,false,
function(arrData,statusResponse,error)
{
//The variable statusResponse contains the value assigned to
statusResponse in the JSON response.
//The variable error contains tha value assigned to error in the
JSON response.
//The variable arrData contains the value assigned to message in
the JSON response.
alert(arrData);
}
);
}
Archivo testModule/index.php
<?php
include_once "libs/paloSantoForm.class.php";
include_once "libs/paloSantoJSON.class.php";
function _moduleContent(&$smarty, $module_name)
{
/* Typical headers of the module like the last example.
.....
.....
.....
*/
$action = getAction();
$content = "";
switch($action){
case "save":
$content = saveTestModule($smarty, $module_name,
$local_templates_dir);
break;
case "translate":
$content = translateText();
break;
default: // view_form
$content = viewFormTestModule($smarty, $module_name,
$local_templates_dir);
break;
}
return $content;
}
/* Here goes the functions
last example
....
....
....
*/
function translateText()
{
$jsonObject = new PaloSantoJSON();
$text
= getParameter("text");
$translated = _tr($text);
$jsonObject->set_message($translated);
return $jsonObject->createJSON();
}
function getAction()
{
if(getParameter("save"))
return "save";
elseif(getParameter("action") == "translate")
return "translate";
else
return "report";
}
componentes de software, escritos en cualquier lenguaje soportado por Elastix. La
instalacin de un addon se realiza de manera sencilla e intuitiva a travs del men
Addons desde la interfaz Web de Elastix.
Dicho lo anterior es importante aclarar que un mdulo de Elastix s se puede
convertir en un addon. Para hacer esto es necesario empaquetar el mdulo en
formato RPM e iniciar un proceso de certificacin de software interoperable con
Elastix.
4.1 Esqueleto del fuente para el empaquetado
Usualmente el fuente contendr un archivo XML y dos carpetas principales. El
archivo y carpetas respectivamente son: menu.xml, modules y setup.
El archivo menu.xml es un XML que contiene los mdulos que sern integrados
a Elastix, indicando la ubicacin, nombre, tipo, permisos,etc.
Ejemplo:
Se desea crear un archivo menu.xml, para un mdulo padre llamado Parent
Module con id parent_module ubicado debajo del mdulo PBX en la posicin 6.
Adems habrn dos mdulos ms el primero ser Test Module con id
test_module ubicado dentro de parent_module en la primera posicin. Y el
mdulo Link Module con id link_module el cual es un mdulo tipo link para
acceder al servidor en el puerto 8080. A estos mdulos slo pueden ingresar por
default los usuarios del grupo administrador.
<?xml version="1.0" encoding="UTF-8"?>
<module>
<menulist>
<menuitem menuid="parent_module" desc="Parent Module"
parent="pbxconfig" module="no" link="" order="6">
<permissions>
<group id="1" name="administrator" desc="total access"></group>
</permissions>
</menuitem>
<menuitem menuid="test_module" desc="Test Module"
parent="parent_module" module="yes" link="" order="61">
<permissions>
<group id="1" name="administrator" desc="total access"></group>
</permissions>
</menuitem>
<menuitem menuid="link_module" desc="Link Module"
parent="parent_module" module="no" link="http://{NAME_SERVER}:8080"
order="62">
<permissions>
<group id="1" name="administrator" desc="total access"></group>
</permissions>
</menuitem>
</menulist>
</module>
Como se puede observar, dentro de la etiqueta menulist van todos los mdulos y
cada mdulo se describe mediante la etiqueta menuitem donde el atributo menuid
es el id del mdulo, el atributo desc es la etiqueta que se mostrar en la interfaz
web, el atributo parent es el id del mdulo que lo contendr, el atributo module
puede ser yes si es un mdulo propiamente dicho o no si es un mdulo padre o si
es un mdulo tipo link, el atributo link es el link al cual apuntar el mdulo y el
mdulo order es el orden que ocupar el mdulo.
En la etiqueta permissions se detallan los grupos de usuarios que tendrn acceso
por default al mdulo.
Ahora lo nico que hay que hacer es usar el script elastix-menumerge pasndole el
archivo XML para que quede realizada la integracin con Elastix. As mismo si
deseamos remover algn men, se ejecuta el script elastix-menuremove pasndole
el id del mismo. Esto se lo debe realizar en el archivo spec.
este campo en yes no significa que la base se eliminar automticamente al
desinstalar el paquete, simplemente abre esa posibilidad y lo que se deber hacer
es colocar un script de eliminacin de la base en la carpeta delete).
Ejemplo:
Construir un archivo db.info para un addon que tendr que una base de datos sqlite3
llamada myDBSqlite la cual se debe hacer un backup en caso de existir y no debe
poder ser eliminable, y una base de datos mysql llamada myDBMysql con las
mismas caracersticas.
[myDBSqlite]
ignore_backup = no
engine = sqlite3
path = /var/www/db
deletable = no
[myDBMysql]
ignore_backup = no
engine = mysql
path = /var/lib/mysql
deletable = no
Dentro de la carpeta install habr una carpeta para cada base de datos con el
mismo nombre de la base. Dentro de esta carpeta habr scripts sql que slo se
ejecutarn en la instalacin del paquete (y se aplicarn sobre la base de datos
correspondiente al nombre de la carpeta). Estos scripts tendrn los nombres
1_schema.sql, 2_schema.sql, 3_schema.sql, etc (usualmente slo se necesitar
de uno), el nmero de prefijo es importante porque indica el orden de ejecucin.
Para bases de datos sqlite3 simplemente se crean tablas y se aaden registros por
default (de ser necesarios) pero para bases mysql tambin es necesario la creacin
de la base (CREATE DATABASE dbname;) seguido de un USE dbname; para de
ah si proseguir con la creacin de las tablas y dems.
En la carpeta update as mismo habr una carpeta para cada base de datos con el
mismo nombre de la base. Dentro de cada una de estas carpetas habr otra
carpeta llamada version_sql que contendrn los scripts sql de actualizacin. El
nombre de estos scripts es sumamente importante, deben tener la siguiente
estructura:
#number_#lastVersion_#newVersion.sql
Donde:
#number es el orden de ejecucin del script.
#lastVersion es la ltima versin existente.
#newVersion es la nueva versin a lanzar, este script slo se ejecutar para
versiones menores a #newVersion.
Ejemplo:
Cul ser el nombre de scripts sql de actualizacin para:
1.
2.
4.2 Archivo spec
Una vez armado el fuente ahora es cuestin de crear el archivo spec, para terminar
con el proceso de construccin del RPM o empaquetado.
A continuacin se mostrar un pequeo ejemplo de un archivo spec sin entrar en
mayores detalles, ya que se asume que el desarrollador tiene claros conocimientos
en cuanto a la construccin de paquetes RPM.
%define modname example
Summary: Elastix Module Example
Name:
elastix-%{modname}
Version: 2.2.0
Release: 1
License: GPL
Group:
Applications/System
Source0: %{modname}_%{version}-%{release}.tgz
BuildRoot: %{_tmppath}/%{name}-%{version}-root
BuildArch: noarch
Prereq: elastix-framework >= 2.2.0-25
%description
Elastix Module Example
%prep
%setup -n %{modname}
%install
rm -rf $RPM_BUILD_ROOT
# Files provided by all Elastix modules
mkdir -p
$RPM_BUILD_ROOT/var/www/html/
mv modules/ $RPM_BUILD_ROOT/var/www/html/
# The following folder should contain all the data that is required by the
installer,
# that cannot be handled by RPM.
mkdir -p
$RPM_BUILD_ROOT/usr/share/elastix/module_installer/%{name}%{version}-%{release}/
mv setup/
$RPM_BUILD_ROOT/usr/share/elastix/module_installer/%{name}%{version}-%{release}/
mv menu.xml $RPM_BUILD_ROOT/usr/share/elastix/module_installer/%{name}%{version}-%{release}/
%pre
mkdir -p /usr/share/elastix/module_installer/%{name}-%{version}-%{release}/
touch /usr/share/elastix/module_installer/%{name}-%{version}%{release}/preversion_%{modname}.info
if [ $1 -eq 2 ]; then
rpm -q --queryformat='%{VERSION}-%{RELEASE}' %{name} >
/usr/share/elastix/module_installer/%{name}-%{version}%{release}/preversion_%{modname}.info
fi
%post
pathModule="/usr/share/elastix/module_installer/%{name}-%{version}%{release}"
# Run installer script to fix up ACLs and add module to Elastix menus.
elastix-menumerge $pathModule/menu.xml
pathSQLiteDB="/var/www/db"
mkdir -p $pathSQLiteDB
preversion=`cat $pathModule/preversion_%{modname}.info`
if [ $1 -eq 1 ]; then #install
# The installer database
elastix-dbprocess "install" "$pathModule/setup/db"
elif [ $1 -eq 2 ]; then #update
elastix-dbprocess "update" "$pathModule/setup/db" "$preversion"
fi
%clean
rm -rf $RPM_BUILD_ROOT
%preun
if [ $1 -eq 0 ] ; then # Validation for desinstall this rpm
echo "Delete example menus"
elastix-menuremove "%{modname}"
# Here you should call to elastix-dbprocess for deleting, the same way
that it was for install, just that instead of word install goes word
delete. But this is not often used due to the databases usually are not
deleted
fi
%files
%defattr(-, asterisk, asterisk)
%{_localstatedir}/www/html/*
/usr/share/elastix/module_installer/*
%changelog
* Mon Jan 30 2012 Alberto Santos <asantos@palosanto.com> 2.2.0-1
Initial version.
4.3 Finalizacin del proceso de certificacin.
Una vez elaborado el RPM, se procede a firmar el contrato y enviar el empaquetado
a PaloSanto Solutions a la direccin de correo certification@palosanto.com con
copia a asantos@palosanto.com, junto con un manual de usuario, para proceder con
la revisin del mismo. Una vez este sea aprobado pasar a formar parte de los
repositorios de Elastix y se convertir en un Addon de Elastix.