Configuration (Magic) Data

Los Datos Magic son un mecanismo para manejar datos dinámicos de congifuracion a nivel del sitio. Es la base de mucha de la funcionalidad que brinda el Intrahealth Informatics Core Engine (I2CE) incluyendo como se sirven las páginas y como se realizan los informes personalizados.

Advertencia: El API para los datos Magic se ha actualizado de manera significativa de la version 3.1 a la versión 4.0. Aunque este artículo aplica a la versión API 4.0, mucho de esta es relevante para la version 3.1. Vea algunos de los Cambios

¿Qué son los Datos Magic?

Los Datos Magic son una estructura de arbol con raíz con beneficios. Si usted lo desea, puede pensar en ellos como el análogo del Registro de Windows para su aplicación en la red. También los puede ver como un arreglo anidado.

Los datos magic tienen dos partes. La clase del nodo de magic data, definido en I2CE/lib/I2CE_MagicDataNode y los mecanismos de almacenamiento para los datos magic. Usted puede utilizar los datos magic sin utilizar un mecanismo de almacenamiento, en tal caso los datos magic guardados no persisten a lo largo de todas las sesiones. Por defecto utiliza los siguientes mecanismos de almacenamiento para los datos Magic:

• Base de datos: Los datos se guardan en una table en la base de datos. En I2CE, esta se establece como la table config .
• APC: Los datos se almacenan en un caché de memoria proporcionado por http://pecl.php.net/package/APC apc] que persiste a lo largo de las sesiones apache.

Dado que APC es más rápido, las lecturas se realizan primero desde APC. Si los datos no se encuentran ahí, se lee desde la base de datos. Los datos se escriben primero en la base de datos y después en APC.

Escalar y No-Escalar

Hay dos tipos principals de nodos escalares y un nodo primario

Un nodo escalar no tiene nodos secundarios. Tiene un valor que es posiblemente una cadena vaciía. Un nodo escalar uede marcarse como localizado. En tal caso el valor que regresa depende de las preferencias de localización del usuario.

Un nod primario puede tener tantos nodos secundarios como quiera. Cada nodo secundario de un primario debe tener names diferentes, no tiene un valor y no es localozable.

Nombres y Rutas

Con la exepción del nodo raíz, cada nodo de datos magic tiene un nombre. Para el nombre se permite cualquier valor numeric. Cualquier cadena que no esté vacía es válida siempre y cuando no empiece con '=' no contenga una '/' y no sea '.' o '..'. Sin embargo, es mejor si se limita a que las cadenas contengan solamente los siguientes caractéres:

_-+.0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ

Rutas absolutas

Los nodos de los Datos Magic pueden referenciarse por su ruta, la que es una concatenación de sus nombres por '/.'

El nodo raíz tiene la ruta '/'.

Si el nodo raíz tiene un secundario con el nombre 'alguna', se referencia por la ruta '/alguna'

Si alguna es un nodo primario con un secundario de nombre 'cosa', entonces ese secundario se referencia por la ruta '/alguna/cosa'

Rutas Relativas

Las rutas también pueden ser relativas. en el ejemplo anterior, si estuviera en el nodo '/alguna' entonces podría referenciar a los otros nodos con:

• './' referencia '/alguna'
• '../' referencia '/'
• './cosa' referencia al nodo '/alguna/cosa'

Definición de Datos Magic en los Archivos de Configuración

Una forma conveniente de cargar datos magic en el sistema es hacerlo a través de un module configuration file especificando un nodo de <configurationGroup> después del nodo de <metadata>. Esta sección tiene un doble propósito. Le permite especificar datos magic asi como proporcionar una manera de editar los datos del módulo.

El nodo de <configurationGroup> es opcional. Si está presente debe tener el nombre del atributo que tiene el mismo valor que el nombre del modulo, que es el nombre del atributo en la etiqueta que contiene <I2CEConfiguration>.

Todos los datos magic son relativos a la ruta definida por este configurationGroup. Hay tres opciones:

• La ruta del atributo no esta presente. en el siguiente ejempli,los datos magic se guardan bajo /modules/mercury_javascript_path.

Ejemplo:
 <configurationGroup name='mercury_javascript_popup'>
   SOME STUFF GOES HERE
</configurationGroup>

• La ruta del atributo está pressente. En el siguiente ejemplo, los datos magic se guardan en /algun/otro/lugar.

Ejemplo:
<configurationGroup name='mercury_javascript_popup' path='/algun/otro/lugar'>
  SOME STUFF GOES HERE
</configurationGroup> 

• El módulo es 'I2CE'. Los datos magic se guardan relativos a /I2CE

En el resto de esta sección decribiremos WHAT STUFF GOES THERE que son <configurationGroup> y <configurations> etiquetas.

<configurationGroup>

Una <configurationGroup> puede tener varias subetiquetas en este orden:

• Un <displayName> opcional. Un nombre mostrado en la configuración del módulo para esta agrupación de datos
• Una <description> opcional. Una descripción de la funcionalidad de la agrupación.
• Una <version> opcional de la etiqueta.
• Cualquier número (incluyendo al cero) de etiquetas de <status>.
• Cualquier número (incluyendo al cero)de <configurationGroup> o etiquetas de <configuration>.

<configuration>

Una <configuration> puede tener varias subetiquetas en este orden:

• Un <displayName> opcional. Un nombre mostrado en la configuración de este modulo para esa agrupación de datos
• Una <description> opcional. Una descripción de la funcionalidad de la agrupación.
• Una etiqueta de [#<version>|<version>]] opcional.
• Cualquier número (incluyendo al cero) de etiquetas de <value>.

Attributos

Hay varios atributos que pueden tener una<configuration> y una <configurationGroup>:

• name: Este es un atributo requerido. Cada <configuration> o <configurationGruop> secundaria de un <configurationGroup> debe tener un nombre distinto. Si la ruta del atributo no se ha establecido, también dice que este nodo de configuración no debe aplicarse al nodo de los datos magic con el nombre dado y que es un nodo secundario de datos magic del nodo primario de configurationGroup.
• path: Esto es opcional Puede ser una ruta absoluta u relative en los datos magic y describe los datos magic en ls cuales se debe guarder este valor. Si esta es una ruta relativa, es relative a la ruta de datos magic de su nodo primario.
• locale: Esto es opcional. Si esta establecido, significa que el valor bajo este nodo debe considerarse como localizable.
• config: Esto es opcional. Si esta establecido, establece el objeto de I2CE_Swiss que se utiliza par mostrar los datos en el menu para configurar los módulos.

Una <configuration> puede también tener los siguientes atributos:

• type: Por defecto es establece como 'string' y describe el tipo de datos establecidos por las etiquetas de <value> de este nodo.
• values: Por defecto se establece como 'single' y describe si los datos establecidos por este nodo Deben ser un arreglo de valores o un único valor establecido en lo que se almacena en el nodo de <values>

<value>

La etiqueta de <value> es ua subetiqueta de una etiqueta de <configuration> . Contiene el o los valores que se almacenan en los datos magic y depende de los attributes de type y values.

Algunos tipos y valores communes son:

• type='string' values='single': El nodo de datos magic es de tipo escalar con valor de los contenidos de la etiqueta de <value> única.
• type='string' values='many': El nodo de datos magic es de tipo primario. Tiene un nodo secundario de tipo escalar para cada etiqueta de <value>.
• type='delimited': El nodo de datos magic es de tipo primario. Se espera que las etiquetas de valor sean de la forma <value>'key':'value'</value> en cual caso se crea un nodo secundario de datos magic de tipo escalar de nombre 'key' y valor 'value'
• type='boolean': Los valores en la etiqueta de <value> se interpretan como booleans: F,f,False,false,0, etc. se guardan en datos magic es 0. De lo contrario, el valor que se guarda es 1.

<version>

Se puede tener accesso a los mismos datos magic desde multiples archivos de configuración. Suponga que un módulo moduleA require un modulo moduleB y que ambos establecen /some/data para tener valores valA y valB respectivamente. Suponga que ambos módulos tienen la version 1.0.

Excerpt from moduleA's configuration file
<configurationGroup name='some' path='/some'>
 <configuration name='data' >
   <value>valA</value>
 </configuration>
 <configuration name='data2'> 
   <value>valA2</value>
 </configuration>
</configurationGroup>
Excerpt from moduleB's configuration file
<configurationGroup name='some' path='/some'>
 <configuration name='data'>
   <value>valB</value>
 </configuration>
 <configuration name='data2'> 
   <value>valB2</value>
 </configuration>
</configurationGroup>

Durante la inicialización del sitio, ya que el moduleA require al moduleB, el valor primero se establece a valB se establece primero por el moduleB. Luego se sobreescribe para que sea el valor valA por el moduleA. De manera similar, después de la inicialización, el valor de '/some/data2' es 'valA2'

Suponga que la version del moduleB se aumenta a la version 1.1 pero no hay otros cambios al archive de configuración. Esto causarà que el archive de configuración se reprocese. El configurator recordará que ya ha procesado todos los datos hasta la version 1.01. Por lo tanto, no volverá a leer la sobrescritura que ya está guardada en los datos magic.

Suponga ahora que moduleB quiere cambiar el valor que guarda en /some/data a newValB, así como crear un Nuevo valor en /some/other_data. Sería necesario aumentar el número de la version del modulo a 1.2 y agregar una etiqueta de <version> para que el configurador sepa que al actualizar el modulo a la version 1.2 debemos leer de Nuevo los datos de configuracióm para todo lo mayor a la version cargada previamente de 3.1:

<configurationGroup name='some' path='/some'>
 <configuration name='data'>
   <version>1.2</version>
   <value>newValB</value>
 </configuration>
 <configuration name='other_data'>
   <version>1.2</version>
   <value>The new stuff</value>
 </configuration>
 <configuration name='data2'> 
   <value>valB2</value>
 </configuration>
</configurationGroup>

Ahora el valor de /some/data se actualizará a 'newValB' y agregaremos en el valor 'The new stuff' en '/some/other_data.' El valor en '/some/data2' se mantiene igual y es 'valA2.'

<status>

Una etiqueta de estado consiste en pares de valores clave:

<status>key:value</status>

Aunque se puede utilizer cualquier cosa para la clave (siempre y cuando no contenga ':'), las claves que tienen significado son:

• version: Funciones como la <version>
• overwrite: El valor puede ser verdadero o falso. Por defecto se establece como falso. Si es verdadero los datos magic se sobreescribirán aún cuando la version no lo haya hecho.
• merge: El valor puede ser verdadero o falso. Por defecto se establece como falso. Si es verdadero los valores leídos se fusionan con los valores existentes utilizando array_merge()
• mergerecursive: El valor puede ser verdadero o falso. Por defecto se establece como falso. Si es verdadero, los valores leídos se fusionan con los valores existentes utilizando I2CE_Util::merge_recursive().
• uniquemerge: El valor puede ser verdadero o falso. Por defecto se establece como falso excepto si un nodo de <configuration> tiene el tipo='string' y los valores='many.' Si es verdadero, los valores leídos se fusionan con los valores existentes utilizando I2CE_Util::merge_recursive() y solamente los valores únicos se mantienen utilizando I2CE_Util::array_unique().
• visible: El valor puede ser verdadero o falso. Por defecto se establece como verdadero. Si es verdadero, este nodo se muestra en el menu de configuración del módulo.
• advanced: El valor puede ser verdadero o falso. Por defecto se establece como falso. Si es verdadero, se considera una opción avanzada para el menu de configuración del módulo
• required: El valor puede ser verdadero o falso. Por defecto se establece como verdadero. Dice qie los valores resultants en el nodo de <configuration> deben establecerse
• showIndex: El valor puede ser verdadero o falso. Por defecto se establece como verdadero. En tal caso mostramos el índice en el menú de configuración del módulo

Los valores de las claves de estado se heredan a medida que se baja de nodo.

Uso de Datos Magic en PHP

Cada nodo de datso magic es una instancia de la clase I2CE_MagicDataNode. Las "variables públicas" de un nodo son sus nodos secundarios que se realiza utilizando el método __get() . El I2CE_MagicDataNode implementa las Interfaces RecusriveIterator, ArrayAccess, SeekableIterator, y Countable.

I2CE tiene una instancia de datos magic de raíz que se pueden recuperar utilizando:

$config=I2CE::getConfig();

Acceso Básico

Suponga que $data es un nodo de datos magic con un nodo secundario llamado 'my_list' y 'amount' que son de tipo primario y escalar respectivamante. Suponga que el nodo secundario 'amount' tien in valor de 10. Suponga que no hay ningún secundario llamado 'bad.' Se puede tenre acceso al secundario de varias maneras:

Access Method	Result	Notes
$data->my_list	I2CE_MagicDataNode	This is the 'my_list' node
$data->amount	10
$data->bad	I2CE_MagicDataNode	El nodo no existía, de modo que se creó. Tiene un tipo indeterminado por el momento.
$data['my_list']	I2CE_MagicDataNode	the 'my_list' node
$data['amount']	10	el valor del nodo 'amount'
$data['bad']	I2CE_MagicDataNode	Creamos el nodo 'bad' que no existía y lo regresamos

Acceso Refinado

Para obtener acceso más refinado a los nodos de datos magic puede utilizer la función traverse($path,$create=false,$return_value=true):

$data->traverse('my_list',false,false)	I2CE_MagicDataNode	Este es el nodo 'my_list'
$data->traverse('bad',false,false)	null	El Segundo argumento dice que no se cree un nodo que no existe
$data->traverse('amount',false,false)	I2CE_MagicDataNode	Este el el nodo 'amount'
$data->traverse('my_list',false,true)	I2CE_MagicDataNode	Este es el nodo 'my_list'
$data->traverse('amount',false,true)	10	The value of the 'amount' node
$data->traverse('bad',false,true)	null	The second argument says not to create a node that doesn't exist
$data->traverse('my_list',true,true)	I2CE_MagicDataNode	This is the 'my_list' node
$data->traverse('amount',true,true)	10	el valor del nodo 'amount'
$data->traverse('bad',true,true)	I2CE_MagicDataNode	Creamos el nodo 'bad' que no existía y lo regresamos

Si un nodo es de tipo escalar, se puede obtener su valor con getValue(). Si llama getAsArray() en el mismo, tambien regresará su valor.

Si un nodo tiene un tipo primario o indeterminado, llamar getValue() regresa el nodo en si. Si llama getAsArray() en el nodo regresará un arreglo anidado. La claves de cada profundidad son los nombres de los nodos secundarios. Los valores pueden ser un arreglo o una cadena, en dependencia de si el secundario es escalar o no.

Revisar la Existencia y el Tipo

Puede utilizer el siguiente método para ver si un nodo de datos magic existe y de que tipo es:

• pathExists($path)
• is_scalar($path=null)
• is_parent($path=null)
• is_indeterminate($path=null)
• is_root($path=null)

Aquí, donde la ruta se establece a null por defecto, el valor que el método se llama en el nodo mismo (esto no sería lo mismo que llamarlo en $path='./').

Podría hacer algo como:

function set_node_to_scalar($node) {
  if (!$node instanceof I2CE_MagicDataNode) {
    echo "Why are you giving me garbage data?\n";
    return false;
  } 
  if ($node->is_scalar()) {
    echo "Este nodo ya es escalar. Tiene un valor " . $node->getValue(). "\nNo necesito hacer nada.\n";
    return true; 
  } else {
    echo "Este nodo es un nodo primario. Aunque puede o no tener nodos secundarios, No lo puedo establecer como escalar.\n";
    return false;
  } else{
    //$node->is_indeterminate() will return true
    echo "Este nodo es indeterminado. Estableciéndolo como escalar\n";
    $node->set_scalar();
    return true;
  }
}

Otras dos funciones útiles son

• getAsArray($path=null) que regresa el nodo y todos sus secundarios(recursivamente) como un arreglo
• setIfIsSet(&$var,$path,$as_array=false) revisará si $path existe. Si no existe, regresa falso. Si existe, regresa verdadero y puede que llame a getValue() o a getAsArray() en el nodo referido por la ruta.

Nombres de nodos secundarios e Iteradores

Para obtener los nombres de los nodos secundarios de un nodo, utilizamos el método getKeys(). Suponga que establecemos lso datos magic de la siguiente manera:

Path	Type	Value
/	parent	NONE
/color	scalar	red
/modules	parent	NONE
/modules/modA	parent	NONE
/modules/modB	parent	NONE
/modules/modA/favorite_clay_animation	scalar	Mr. Bill

Tambien podría hacer algo similar como:

echo "Me gusta el color " . $config->color . "\n";
$keys = $config->getKeys();
foreach ($keys as $key) {
  if ($config->is_parent($key)) {
    echo "El nodo llamado $key bajo " . $config->getPath(false) . " es un nodo primario. Tiene secundarios " . implode(',', $config->$key->getKeys()) . ".\n";
  } else if ($config->is_scalar($key)) {
   echo "El nodo llamado $key bajo " . $config->getPath(false) . " es un escalar con valor " . $config->$key ".\n";
  }
}

lo que resultaría en :

Me gusta el color rojo.
El nodo llamado módulos bajo / es un nod oprimario. tiene secundarios modA,modB.
El nodo llamado color bajo / es un nodo escalar cone el valor rojo.

Ya que un nodo de datos magic es un iterador, podemos hacer cosas como:

foreach ($config as $key=>$node) {
  if ($node instanceof I2CE_MagicDataNode) {
   echo "The node named $key under at " . $config->getPath(false) . " es un nodo primario.  Tiene secundarios " . implode(',', $node->getKeys()) . ".\n";
  } else {
   echo "The node named $key under at " . $config->getPath(false) . " es un escalar con valor " . $node .".\n";
  }
}

lo que resultaría en:

El nodo llmaado modulo bajo / es un nodo primario. tiene secundarios modA,modB.
El nodo llamado color bajo / es un nodo escalar con el valor rojo.

o:

$modules = $config->modules;
foreach ($modules as $module=>$data) {
  if ($data->is_scalar('favorite_clay_animation')) {
     echo "The module $module thinks " . $data->favorite_clay_animation . " is a super star!\n";
  }
}

resultaría en:

 The module modA thinks Mr. Bill is a super star!

Cambios de 3.1

• Eliminamos los __ de los métodos de llamada.
• Relajamos las reglas de los nombres de los nodos de los datos magic.
• Implementamos las varias interfaces
• Agregamos soporte para localización de valores