OpenDomo Seguridad y domótica libre

Los scripts OpenDomo son los principales elementos de ejecución de nuestro sistema, y (en condiciones normales) serán lanzados por el odcgi, como interfaz. Es por ello que la sintaxis a emplear debe ajustarse a los parámetros esperados. A continuación detallaremos los pasos a seguir para preparar un script con la sintaxis válida.

1.Preliminares

Antes de empezar a desarrollar las funcionalidades del script, deberemos tener clara su función y sus características. Cuando el diseño está claro, deberemos elegir un nombre único (en inglés, y siguiendo las especificaciones) y su clase (config, control, tools, etc), y procederemos a crear el archivo en la ubicación pertinente, por ejemplo:

# touch /usr/local/opendomo/services/control/nombreScript.sh
# chmod +x /usr/local/opendomo/services/control/nombreScript.sh

A continuación, abriremos el archivo para editarlo. Como todo script que se precie, la primera línea deberá indicar su intérprete, en nuestro caso "#!/bin/sh". Las siguientes líneas deberán indicar algunos parámetros más, necesarios para el correcto funcionamiento del sistema. Veamos un ejemplo:

#!/bin/sh
#desc:Add a new function (en inglés, un nombre descriptivo para el script)
#type:local
#package:packagename
#author:(optional)

2. Bloques de salida

Los scripts estándar emplearán dos bloques de salida principales: el formulario ("form:") y el listado ("list:"), pudiendo ser ambos complementados con un bloque de comandos ("cmds:" o "actions:"). El primero consiste en una explicación de los campos que espera recibir, de acuerdo con el formato siguiente:

form: nombreScript.sh(nl)
(tab)campo1(tab)Campo 1(tab)tipo(tab)valor(nl)
(tab)campo2(tab)Campo 2(tab)tipo(tab)valor(nl)
...
(tab)campoN(tab)Campo N(tab)tipo(tab)valor(nl)
(nl)

NOTA: Los caracteres no imprimibles tabulador y nueva línea son muy importantes en el formato; es por esta razón que han sido mostrados en el ejemplo.

El formulario quedará delimitado por una línea de texto que empiece por "form" hasta la siguiente línea vacía que se encuentre. La representación de este bloque a través de la interfaz web se corresponderá a un formulario con los campos especificados, que serán recibidos por el script (cuando el usuario haga el "submit") en el mismo orden que han sido enumerados. Los tipos de campo se analizan detalladamente en el Manual de Referencia.

El segundo tipo de salida es el listado; básicamente el formato esperado es similar, aunque con la cadena "list:" prefijando la primera línea. Otra diferencia es que la columna correspondiente al valor por defecto de cada fila se convierte en texto complementario. Este tipo de salida mostrará una lista de elementos con casillas de selección (checkboxes) que permiten seleccionar individualmente los elementos.

Adicionalmente a los listados y formularios podemos incorporar el bloque de comandos. Este bloque debe encontrarse inmediatamente después del anterior (un listado o un formulario), sin dejar ninguna línea en blanco. El formato empleado es el siguiente:

actions:(nl)
(tab)scriptName.sh(tab)Texto descriptivo de la acción(nl)
(tab)script2.sh(tab)Texto de la segunda opción(nl)
(nl)

Actualización: El bloque "actions:" también puede indicarse con la versión abreviada rápida "cmds:".

El funcionamiento de este bloque dependerà del tipo de bloque al que sucede; si se trata de un formulario, los datos introducidos en él serán enviados al script correspondiente al botón pulsado. Si se trata de un listado, se enviará al script un argumento por cada uno de los elementos seleccionados en tal listado.

3.Textos literales

Las líneas precedidas por "#" serán interpretadas como texto literal, que será mostrado a través de la interfaz. Algunos casos especiales son:

• #ERR: el texto será formateado como mensaje de error o de aviso, normalmente en color rojo o naranja (dependiendo del estilo aplicado)
• #WARN: el texto será formateado como mensaje de aviso, realzado respecto el texto normal pero más discreto que el mensaje de error
• #URL: el texto será convertido en un hiper-enlace
• #-----  (sin texto): se generará una línea de división horizontal
• #> Título visible del formulario (debe estar antes de la línea de "form") Nota: el soporte para esta opción será abandonada en futuras versiones del CGI

Soporte Internacional

Tal como se explica en el manual del módulo odcgi, éste es el encargado de ofrecer soporte multi-idioma. Las rutinas de traducción solamente afectarán a los siguientes fragmentos de la salida:

• Nombre descriptivo del campo: tanto en salidas autodescriptivas como en listados, se corresponde al segundo campo
• Texto descriptivo de los "actions"
• Textos literales

Múltiples formularios

La interfaz permite emplear múltiples formularios en una sola salida. Esto debería facilitar el desarrollo de nuevas funcionalidades y reducir el número de llamadas HTTP. Asimismo, será muy útil para el sistema distribuido ofrecido por oddiscovery.

Para crear una script multi-formulario bastará con emplear distintas secciones sucesivas (formularios y listados, con o sin sus respectivas secciones "actions"). El resultado será una página HTML con diversos formularios, agrupando los campos que se enviarán.

Un script multi-formulario será, a menudo, un envoltorio que simplemente llamará a otros scripts específicos. En este caso es importante hacer una llamada completa y no una inclusión de los sub-scripts:

Correcto:
...
/usr/local/opendomo/miScript.sh
...

Incorrecto:
...
. /usr/local/opendomo/miScript.sh
...

Subcomandos

En ocasiones un mismo script concentrará muchas funcionalidades simples, de modo que podremos emplear los subcomandos para la interfaz. El funcionamiento es algo complejo, por lo que será más práctico emplear un ejemplo:

form: exampleScript.sh
(tab)command1(tab)Command 1(tab)subcommand[start,stop](nl)
...
(nl)

El script anterior responderá a los comandos "exampleScript.sh command1 start" y "exampleScript.sh command1 stop". El mismo script podrá emplear distintos comandos al mismo tiempo, aunque serán enviados uno cada vez.

Esta funcionalidad, aunque salga un poco de la línea del resto de comandos, abre un nuevo abanico de funcionalidades para la interfaz de OpenDomo.

Los scripts deberán cumplir adecuadamente los requisitos especificados.