Componentes JSON&JS (Parte 7 de 12)

properties

Éste grupo es obligatorio. Contiene el conjunto de propiedades específicas del control. Cada uno de sus miembros es una propiedad y es en sí mismo un objeto que a su vez contiene los elementos que la describen. El nombre de cada miembro constituye el nombre de la propiedad, sin el prefijo "$".

Los miembros válidos para cada propiedad son los siguientes:

• id

Es el identificador de la propiedad. Un entero positivo. Es obligatorio y es un campo crítico ya que Omnis usa éste dato para identificar la propiedad. Lo cual significa que no deberá cambiar estos valores de ID una vez que se ha comenzado a hacer uso del control. Id, debe ser único para todas las propiedades del control. Cuando "jsControls" carga el control, validará su unicidad. Normalmente se comenzar a numerar las propiedades desde 1. 

• desc

Es la descripción de la propiedad. Un texto obligatorio, utilizado por el IDE, por ejemplo, como "tooltip" de la propiedad en el "Property Manager". 

• tab

Es opcional y es el texto que identifica la ficha a la que pertenece en el "Property Manager". "custom" será la ficha predeterminada, si se omite. De lo contrario, deberá usarse uno de los siguientes valores: "custom", "general", "data", "appearance", "action", "prefs", "text", "pane", "sections", "java" o "column".

• type

Es obligatorio. Identifica el tipo de la propiedad. Puede ser uno de los básicos (integer, character, boolean o list) o uno específico como (color, dataname, font, icon, pattern, fontstyle, linestyle, multiline, set, o remotemenu). 

• runtimeonly

Es opcional y booleano, si es "true" indica que la propiedad es "runtime only". Su valor predeterminado si es omitido es "false". 

• findandreplace

Es opcional y booleano, si es "true" indica que la propiedad puede ser localizada mediante "find and replace". Su valor predeterminado es "false". 

• extconstant

Es opcional y booleano, si es "true" indica que la propiedad está restringida a un rango de constantes predefinidas para este control. Esto afectará al menú emergente en el "Property Manager". Puede usarse tanto con propiedades de tipo "integer" como con las de tipo "set"; En este último caso, el primer miembro del rango deberá ser una constante con valor cero, para representar al "set" vacío. 

• intconstant

Es opcional y booleano, si es "true" indica que la propiedad está restringida a un rango de constantes predefinidas desde el núcleo de Omnis. Esto afectará al menú emergente en el "Property Manager". Puede usarse tanto con propiedades de tipo "integer" como con las de tipo "set"; En este último caso, el primer miembro del rango deberá ser una constante con valor cero, para representar al "set" vacío. "extconstant" y "intcontant" no deben ser "true" al mismo tiempo. 

• constrangestart y constrangeend

Ambos deben existir si "extconstant" o "intconstant" son "true". En el caso de "intconstant", son "idents" (identificadores) de constantes que conformarán el rango de constantes a usar (podrá saber cuales son los "idents" de las constantes de núcleo Omnis, consultando el grupo "$constants" mediante el "Notation inspector"). En el caso de "extconstant", serán los nombres de las constantes definidas para el control; El conjunto estará entre "constrangestart" y "constrangeend" y en el orden en que figuren en el fichero "control.json". Tenga en cuenta que cuando se utiliza con un "set", los valores de las constantes deberán corresponderse con el "bit mask" (máscara) usada para representar el "set". 

• min  y 

--> max

Son opcionales y solo se aplican cuando el tipo es "integer". Especifican los valores mínimos y máximos de la propiedad. 

• initial

Es opcional y puede ser utilizado para indicar el valor inicial de la propiedad. Para los tipos "character", deberá ser un texto. Para tipos "integer", deberá ser un número entero. Para tipos "boolean" deberá ser un valor booleano.

Ejemplo:

"properties": { 

     "headercolor": {

          "id": 1, 

          "desc": "The header color of the control", 

          "type": "color",

          "tab": “appearance”,

          "initial": 255

     },

     "headericon": { 

          "id": 2,

          "desc": "The header icon of the control", 

          "popuptype": "icon",

          "tab": "appearance"

     },

     "rangeofexternalconstants": { 

       "id": 3,

       "desc": "Range of external constants", 

       "type": "integer",

       "extconstant": true,

       "constrangestart": "kNetOmnisControl1Range1",

       "constrangeend": "kNetOmnisControl1Range3",

     }

}

Componentes JSON&JS (Parte 6 de 12)

JSON Control Object

Cada control posee un archivo JSON denominado "control.json" conteniendo su definición. A continuación describiremos en detalle cada uno de los miembros de este objeto según sus secciones:

name

El nombre es obligatorio; Determina el nombre del control como componente externo y también el nombre de la clase JavaScript en la forma "ctrl_≤nombre≥", por ejemplo para...

 "name": “net_omnis_control1"

...la clase JavaScript sería ctrl_net_omnis_control1. 

 flags

El grupo "flags" es obligatorio. Permite configurar ciertas características del control. Cada miembro de éste grupo es opcional y si son omitidos su valor por defecto será "false", siendo sus miembros válidos los siguientes:

• beforeafterevents y beforeevents  (excluyentes mutuamente) 

Indica si el control admite el uso de "evAfter" y "evBefore", o sólamente "evBefore", respectivamente. Si ambos son omitidos, indicará que el control no soporta ninguno de éstos eventos (véase "events")

•  backcolorandalpha

Indica si el control admite las propiedades "backcolor" y "backalfa". 

•  noenabled

Indica si el control puede no tener habilitada la propiedad. 

•  transparentbackground

Indica que el control posee fondo transparente y que no hace uso de las propiedades "backcolor" y "backalfa". No puede ser usado con "backcolorandalpha" a "true". 

•  hasdefaultborder

Indica si la propiedad "$effect" del control, puede contener el valor "kJSborderDefault". 

•  hasdisplayformat

Indica si el control contiene propiedades en formato de fecha y número. 

•  hasdragevents

Indica si el control permite eventos de arrastrar y soltar (véase "events"). 

Ejemplo:

"flags": {

    "beforeafterevents": true, 

    "backcolorandalpha": true, 

    "noenabled": true, 

    "hasdefaultborder": false, 

    "hasdisplayformat": true, 

    "hasdragevents": true

}, 

 standardproperties

El grupo "standardproperties" es opcional. Contiene las propiedades estándar soportadas por el control; La inclusión de cualquiera de sus miembros significa que el control admitirá la propiedad. Se trata de propiedades básicas aplicables a todos los controles.

Miembros válidos del grupo son: "“dataname", “effect", “bordercolor", “borderradius", “linestyle", “font", "textcolor", "align", “fontstyle", “fontsize", “horzscroll", “vertscroll", "autoscroll" y “dragmode”.

Ejemplo:

"standardproperties": [

     "dataname", 

     "effect", 

     "bordercolor", 

     "borderradius", 

     "linestyle",

],

  

Componentes JSON&JS (Parte 5 de 12)

JSON Control Definition

En esta entrada describiremos las diferentes propiedades que pueden ser definidas en el archivo JCD, todas ellas editables mediante el "JSON Control Editor" (recuerde que también pueden ser editadas mediante cualquier otro editor de textos externo).

La nueva carpeta "html/controls", contiene a su vez una subcarpeta por cada control JSON ya definido. Los nombres de estas subcarpetas no son críticos, pero tiene sentido usar el mismo nombre que el usado para el control.

El "JSON Control Editor" creará la carpeta "html/controls" tras construir su primer control, de lo contrario (si está usando un control ya existente) necesitará crear esta carpeta manualmente. (IMPORTANTE: No confundirse con la carpeta "htmlcontrols" la cual contiene los controles definidos para su uso con el objeto oBrowser)

Cada carpeta de control, contendrá un archivo denominado "control.json". Además, podrá contener archivos PNG, con cualquier nombre pero siempre incluyendo los archivos PNG: "16x16", "16x16_2x", "48x48" y "48x48_2x", ya que serán los usados como icono representativo del control, en el "Component Store" y en los formularios remotos. Los archivos PNG deberán tener la extensión ".png".

Un nuevo componente externo denominado "jsControls", (situado sobre la carpeta "jscomp") es el encargado de gestionar todos los controles JSON, éste realiza la carga y validación de cada uno de los controles durante el arranque. Todos los que pasan la validación son mostrados en el "Component Store". Si un control no pasa la validación, "jsControls" abre el registro de seguimiento (log) y agrega un mensaje para indicar que existe un problema con el control. El problema exacto se podrá consultar en un archivo denominado "control_errors.txt" situado sobre propia carpeta del control.

Cada control deberá tener un nombre único y estar indicado dentro del fichero "control.json" (ver más adelante), podrá usarse una convención similar a Java, excepto que Omnis utiliza el carácter de subrayado en lugar del punto, por ejemplo. "net_omnis_control1", ya que el uso de puntos causaría problemas de incompatibilidad con la sintaxis de notación usada en Omnis.