Saltar al contenido principal
Versión: 20 R6 BETA

Macros del editor de formularios

El editor de formularios 4D soporta macros. Una macro es un conjunto de instrucciones que permiten realizar una acción o una secuencia de acciones. Cuando se llama, la macro ejecutará sus instrucciones y realiza automáticamente la(s) acción(es).

Por ejemplo, si tiene un informe recurrente con un formato específico (por ejemplo, cierto texto debe aparecer en rojo y cierto texto debe aparecer en verde), puede crear una macro para definir automáticamente el color. Puede crear macros para el editor de formularios 4D que pueden:

  • Crear y ejecutar código 4D
  • Mostrar las cajas de diálogo
  • Seleccione los objetos de formulario
  • Añadir / eliminar / modificar los formularios, los objetos de formulario así como sus propiedades
  • Modificar los archivos del proyecto (actualizar, eliminar)

El código de las macros soporta funciones de clase y las propiedades de objeto de formulario en JSON para permitir definir toda funcionalidad personalizada en el editor de formularios.

Las macros pueden definirse para el proyecto local o para componentes dentro del proyecto. Por lo general, se crea una macro y se instala dentro de los componentes que se utilizan para el desarrollo.

Cuando se llama, una macro anula todo comportamiento especificado previamente.

Ejemplo práctico

En este breve ejemplo, verá cómo crear y llamar a una macro que añade un botón de alerta "Hello World" en la esquina superior izquierda de su formulario.

  1. En un archivo formMacros.json dentro de la carpeta Sources de su proyecto, escriba:
{
"macros": {
"Add Hello World button": {
"class": "AddButton"
}
}
}
  1. Cree una clase 4D llamada AddButton.

  2. En la clase AddButton, escriba la siguiente función:

Function onInvoke($editor : Object)->$result : Object

var $btnHello : Object

// Crear un botón "Hello"
$btnHello:=New object("type"; "button"; \
"text"; "Hello World!"; \
"method"; New object("source"; "ALERT(\"Hello World!\")"); \
"events"; New collection("onClick"); \
"width"; 120; \
"height"; 20; \
"top"; 0; \
"left"; 0)

// Añadir botón en la página actual
$editor.editor.currentPage.objects.btnHello:=$btnHello

// Seleccionar el nuevo botón en el editor de formularios
$editor.editor.currentSelection.clear() //unselect elements
$editor.editor.currentSelection.push("btnHello")

// Notificar la modificación al editor de formularios 4D
$result:=New object("currentSelection"; $editor.editor.currentSelection;\
"currentPage"; $editor.editor.currentPage)

Luego puede llamar a la macro:

Llamar a las macros en el editor de formularios

Cuando las macros están definidas en su proyecto 4D, puede llamar una macro utilizando el menú contextual del editor de formularios:

Este menú se crea sobre el archivo de definición de macros formMacros.json. Los elementos de la macro se clasifican en orden alfabético.

Este menú puede ser llamado en un área vacía o en una selección en el formulario. El objeto seleccionado se pasa a $editor.currentSelection o $editor.target en la función onInvoke de la macro.

Una sola macro puede ejecutar varias operaciones. Si se selecciona, la función Deshacer del editor de formularios puede utilizarse para revertir las operaciones de las macros de forma global.

Ubicación del archivo de macro

Todas las macros del editor de formularios 4D se definen en un único archivo JSON por proyecto o componente: FormMacros.json.

Este archivo debe estar ubicado en la carpeta Project > Sources local o del componente:

Declaración de macros

La estructura del archivo formMacros.json es la siguiente:

{
"macros": {
<macroName>: {
"class": <className>,
<customProperty> : <value>
}
}
}

Esta es la descripción del contenido del archivo JSON:

AtributoTipoDescripción
macrosobjectlista de macros definidas
<macroName>objectdefinición de la macro
classstringnombre de clase de la macro
<customProperty>any(opcional) valor personalizado a recuperar en el constructor

Las propiedades personalizadas, cuando se utilizan, se pasan a la función constructor de la macro.

Ejemplo

{
"macros": {
"Open Macros file": {
"class": "OpenMacro"
},
"Align to Right on Target Object": {
"class": "AlignOnTarget",
"myParam": "right"
},
"Align to Left on Target Object": {
"class": "AlignOnTarget",
"myParam": "left"
}
}
}

Instanciar las macros en 4D

Cada macro que quiera instanciar en su proyecto o componente debe ser declarada como una clase 4D.

El nombre de la clase debe coincidir con el nombre definido mediante el atributo class del archivo formMacros.json.

Las macros se instancian al iniciar la aplicación. En consecuencia, si se modifica la estructura de la clase macro (añadir una función, modificar un parámetro...) o el constructor, tendrá que reiniciar la aplicación para aplicar los cambios.

Funciones macro

Cada clase de macro puede contener un Class constructor y dos funciones: onInvoke() y onError().

Class constructor

Class constructor($macro : Object)

ParámetrosTipoDescripción
$macroObjectObjeto de declaración de macros (en el archivo formMacros.json)

Las macros se instancian utilizando una función class constructor, si existe.

El class constructor se llama una vez durante la instanciación de clase, que se produce al inicio de la aplicación.

Las propiedades personalizadas añadidas a la declaración macro se devuelven en el parámetro de la función class contructor.

Ejemplo

En el archivo formMacros.json:

{
"macros": {
"Align to Left on Target Object": {
"class": "AlignOnTarget",
"myParam": "left"
}
}
}

Puede escribir:

// Class "AlignOnTarget"
Class constructor($macro : Object)
This.myParameter:=$macro.myParam //left
...

onInvoke()

onInvoke($editor : Object) -> $result : Object

ParámetrosTipoDescripción
$editorObjectObjeto Form Editor Macro Proxy que contiene las propiedades del formulario
$resultObjectObjeto Form Editor Macro Proxy que devuelve las propiedades modificadas por la macro (opcional)

La función onInvoke se ejecuta automáticamente cada vez que se llama a la macro.

Cuando la función es llamada, recibe en la propiedad $editor.editor una copia de todos los elementos del formulario con sus valores actuales. Luego puede ejecutar cualquier operación en estas propiedades.

Una vez completadas las operaciones, si la macro resulta en la modificación, adición o eliminación de objetos, puede pasar las propiedades editadas resultantes en $result. El procesador de macros analizará las propiedades devueltas y aplicará las operaciones necesarias en el formulario. Obviamente, cuanto menos propiedades devuelva, menos tiempo requerirá el procesamiento.

Estas son las propiedades devueltas en el parámetro $editor:

PropiedadTipoDescripción
$editor.editor.formObjectFormulario completo
$editor.editor.fileFileObjeto File del archivo de formularios
$editor.editor.nameStringNombre del formulario
$editor.editor.tablenumberNúmero de tabla del formulario, 0 para el formulario proyecto
$editor.editor.currentPageNumbernumberEl número de la página actual
$editor.editor.currentPageObjectLa página actual, que contiene todos los objetos de formulario y el orden de entrada de la página
$editor.editor.currentSelectionCollectionColección de nombres de objetos seleccionados
$editor.editor.formPropertiesObjectPropiedades del formulario actual
$editor.editor.targetstringNombre del objeto bajo el ratón cuando se hace clic en una macro

Estas son las propiedades que puede pasar en el objeto $result si quiere que el macro procesador ejecute una modificación. Todas las propiedades son opcionales:

PropiedadTipoDescripción
currentPageObjectcurrentPage incluyendo los objetos modificados por la macro, si los hay
currentSelectionCollectioncurrentSelection si es modificada por la macro
formPropertiesObjectformProperties si es modificado por la macro
editor.groupsObjectinformación de grupo, si los grupos son modificados por la macro
editor.viewsObjectver información, si las vistas son modificadas por la macro
editor.activeViewStringNombres de vistas activos

Por ejemplo, si los objetos de la página actual y de los grupos han sido modificados, puede escribir:

	$result:=New object("currentPage"; $editor.editor.currentPage ; \ 
"editor"; New object("groups"; $editor.editor.form.editor.groups))

atributo method

Cuando se maneja el atributo method de los objetos de formulario, se puede definir el valor del atributo de dos maneras en las macros:

PropiedadTipoDescripción
sourceStringcódigo del método

4D creará un archivo con el nombre del objeto en la carpeta "objectMethods" con el contenido del atributo source. Esta función solo está disponible para el código macro.

Propiedad $4dId en currentPage.objects

La propiedad $4dId define un ID único para cada objeto de la página actual. Esta clave es utilizada por el procesador de macros para controlar los cambios en $result.currentPage:

  • si la llave $4dId falta tanto en el formulario y en un objeto en $result, el objeto se crea.
  • si la llave $4dId existe en el formulario pero falta en $result, el objeto se elimina.
  • si la llave $4dId existe tanto en el formulario y en un objeto en $result, el objeto se modifica.

Ejemplo

Quiere definir una función macro que aplique el color rojo y el estilo de letra itálica a cualquier objeto seleccionado.

Function onInvoke($editor : Object)->$result : Object
var $name : Text

If ($editor.editor.currentSelection.length>0)
// Define el trazo en rojo y el estilo en cursiva para cada objeto seleccionado
For each ($name; $editor.editor.currentSelection)
$editor.editor.currentPage.objects[$name].stroke:="red"
$editor.editor.currentPage.objects[$name].fontStyle:="italic"

End for each

Else
ALERT("Please select a form object.")
End if

// Notificar la modificación a 4D
$result:=New object("currentPage"; $editor.editor.currentPage)

onError()

onError($editor : Object; $resultMacro : Object ; $error : Collection)

ParámetrosTipoDescripción
$editorObjectObjeto enviado a onInvoke
$resultMacroObjectObjeto devuelto por onInvoke
$errorCollectionPila de errores
[].errCodeNumberCódigo de error
[].messageTextDescripción del error
[].componentSignatureTextFirma del componente interno

La función onError se ejecuta cuando el procesador de macros encuentra un error.

Cuando se ejecuta una macro, si 4D encuentra un error que impide la cancelación de la macro, no la ejecuta. Es el caso, por ejemplo, de que la ejecución de una macro resulte en:

  • borrar o modificar un script cuyo archivo es de sólo lectura.
  • crear dos objetos con el mismo ID interno.

Ejemplo

En la definición de una clase macro, se puede escribir el siguiente código de error genérico:

Function onError($editor : Object; $resultMacro : Object; $error : Collection)
var $obj : Object
var $txt : Text
$txt:=""

For each ($obj; $error)
$txt:=$txt+$obj.message+" \n"
End for each

ALERT($txt)