Componentes de UI del SDK de Conector Básico

Descripción general

Estos componentes básicos de UI están disponibles:

• Entrada de cadena con valor predeterminado
• Entrada de cadena sin valor predeterminado
• Entrada de cadena con entrada oscurecida ("Contraseña")
• Entrada de cadena con entrada oculta (Sin elemento de UI visible)
• Área de texto
• Entrada numérica
• Entrada booleana (Casilla de verificación)
• Opción de radio
• Menú desplegable

Están disponibles componentes de UI más sofisticados, que se describen como Componentes Complejos.

Componentes básicos de UI

Este ejemplo muestra los componentes básicos disponibles, con fragmentos de código detallados en los ejemplos que siguen:

Características comunes

Todos los componentes de UI pueden tener un defaultValue y validators; consulte el primer campo de cadena para un ejemplo de ambos. Los validadores se describen en Validadores.

Los campos que muestran un ícono variable son ejemplos de componentes de UI que admiten la sustitución de variables. Cuando un usuario ingresa un corchete cuadrado de apertura ([), se mostrará una lista de posibles completaciones de variables (variables de Jitterbit, del proyecto y globales). Actualmente, solo un componente de UI de Entrada de Cadena admite la sustitución de variables.

Recuperar valores

Los valores se recuperan de las propiedades según su nombre. Esto significa que los nombres deben ser únicos para cada conexión y actividad.

El método de fábrica de conexión recibe una instancia de las propiedades (props) que se pueden usar para recuperar valores:

@Override
public Connection createConnection(Map<String, String> props) {
  String accessToken = props.get(ACCESS_TOKEN);
  String appKey = props.get(APP_KEY);
  String locale = !props.containsKey(LOCALE) ? Locale.getDefault().toString() : "EN_US";
  if (accessToken == null || accessToken.length() == 0) {
    throw new RuntimeException("Access Token property cannot be empty. " +
      "Specify the access token associated with the registered Dropbox application.");
  }
  if (appKey == null || appKey.length() == 0) {
    throw new RuntimeException("App Key property cannot be empty. " +
      "Specify the app key associated with the registered Dropbox application.");
  }
  return new DropboxConnection(appKey, accessToken, locale);
}

En el ejemplo anterior, los valores de accessToken y appKey se recuperan de las propiedades utilizando las palabras clave apropiadas (ACCESS_TOKEN, establecido en "access-token" y APP_KEY, establecido en "app-key").

Entrada de cadena con valor predeterminado

{
  "name": "example_string_with_default",
  "type": "string",
  "defaultValue": "/",
  "displayName": "Example string...required validator",
  "validators": [
    {
      "name": "required"
    }
  ]
}

Entrada de cadena sin valor predeterminado

{
  "name": "example_string_without_default",
  "type": "string",
  "displayName": "Example string without a default value"
}

Entrada de cadena con entrada oscurecida ("Contraseña")

{
  "name": "example_password_string",
  "type": "string",
  "displayName": "Example password string",
  "multiple": false,
  "widgetHint": "password"
}

Entrada de cadena con entrada oculta (Sin elemento de UI visible)

En este caso, no se muestra ningún elemento de UI visible. Hay un valor disponible para establecer, ya sea como un valor predeterminado o programáticamente por otros componentes.

{
  "name": "example_hidden_string",
  "type": "string",
  "displayName": "Example hidden string",
  "defaultValue": "hidden_value",
  "hidden": true,
  "multiple": false
}

Área de texto

Diseñada para múltiples líneas de texto.

{
  "name": "example_textarea",
  "type": "textarea",
  "displayName": "Example text area",
  "location": "last",
  "multiple": false,
  "widgetHint": "textarea"
}

Entrada numérica

Para ingresar números, con flechas de incremento/decremento (visibles ya sea al pasar el mouse o cuando el campo está en foco) y activación de flechas del teclado (las teclas de flecha arriba y abajo aumentan y disminuyen el valor).

{
  "name": "example_number",
  "type": "number",
  "displayName": "Example number",
  "multiple": false
}

Entrada booleano (Casilla de verificación)

{
  "name": "example_boolean",
  "type": "boolean",
  "displayName": "Example boolean",
  "defaultValue": true,
  "multiple": false
}

Opción de radio

Se utiliza para crear grupos de botones de opción. El realValue es el valor que se devolverá cuando se recupere de las propiedades en el conector. El enumValue se muestra al usuario.

{
  "type": "string",
  "multiple": false,
  "name": "radio_choice_example",
  "widgetHint": "radio-choice",
  "displayName": "Example radio choice",
  "enumValues": [
    {
      "enumValue": "Binary",
      "realValue": "1"
    },
    {
      "enumValue": "ASCII",
      "realValue": "2"
    },
    {
      "enumValue": "Other",
      "realValue": "3"
    }
  ],
  "defaultValue": "2"
}

Menú desplegable

Se utiliza para crear grupos de menús desplegables. El realValue es el valor que se devolverá cuando se recupere de las propiedades en el conector. El enumValue se muestra al usuario.

{
  "name": "enum_example",
  "displayName": "Example menu using enum of values",
  "enumValues": [
    {
      "enumValue": "First Item",
      "realValue": "0"
    },
    {
      "enumValue": "Second Item (default)",
      "realValue": "1"
    },
    {
      "enumValue": "Third Item",
      "realValue": "2"
    }
  ],
  "defaultValue": "1"
}

Los menús desplegables admiten edición y búsqueda. Esto se especifica configurando una propiedad adicional, enumOptions, que admite editable y searchable:

• editable: Si es true, un usuario puede agregar una nueva opción al menú desplegable y seleccionar esa nueva opción. El valor predeterminado es false.
• searchable: Si es true, un usuario puede escribir en el menú desplegable para filtrar las opciones existentes en el menú desplegable. El valor predeterminado es false.

Las dos opciones se pueden combinar si se desea. La presencia de una no implica la otra. Por ejemplo, una selección de versión podría ser:

{
    "name": "version",
    "displayName": "Version",
    "enumValues": [
        {
            "enumValue": "v33.0",
            "realValue": "v33.0"
        },
        {
            "enumValue": "v33.1",
            "realValue": "v33.1"
        }
    ],
    "enumOptions": {
        "editable": true
    },
    "defaultValue": "v33.1"
}

Ejemplo de menú desplegable de región de AWS

Este es un ejemplo más largo que muestra cómo las propiedades que un usuario necesitará proporcionar al configurar una conexión o actividad pueden estar codificadas para selección. En este ejemplo, la región de AWS para conectarse al punto final de Amazon S3 es algo que el usuario necesitará proporcionar. El realValue es el valor que se devolverá cuando se recupere de las propiedades en el conector. El enumValue se muestra al usuario.

Para especificarlo en el adapter.json y en la interfaz de usuario, se podría proporcionar una selección de menú desplegable para especificar esto:

Este fragmento de código define el menú desplegable:

{
    "name": "region",
    "displayName": "AWS Region",
    "type": "string",
    "defaultValue": "us-east-1",
    "enumValues": [
        {"realValue": "us-gov-west-1",  "enumValue": "AWS GovCloud (US)"},
        {"realValue": "us-east-1",      "enumValue": "US East (N. Virginia)"},
        {"realValue": "us-east-2",      "enumValue": "US East (Ohio)"},
        {"realValue": "us-west-1",      "enumValue": "US West (N. California)"},
        {"realValue": "us-west-2",      "enumValue": "US West (Oregon)"},
        {"realValue": "eu-west-1",      "enumValue": "EU (Ireland)"},
        {"realValue": "eu-west-2",      "enumValue": "EU (London)"},
        {"realValue": "eu-west-3",      "enumValue": "EU (Paris)"},
        {"realValue": "eu-central-1",   "enumValue": "EU (Frankfurt)"},
        {"realValue": "eu-north-1",     "enumValue": "EU (Stockholm)"},
        {"realValue": "ap-south-1",     "enumValue": "Asia Pacific (Mumbai)"},
        {"realValue": "ap-southeast-1", "enumValue": "Asia Pacific (Singapore)"},
        {"realValue": "ap-southeast-2", "enumValue": "Asia Pacific (Sydney)"},
        {"realValue": "ap-northeast-1", "enumValue": "Asia Pacific (Tokyo)"},
        {"realValue": "ap-northeast-2", "enumValue": "Asia Pacific (Seoul)"},
        {"realValue": "cn-north-1",     "enumValue": "China (Beijing)"},
        {"realValue": "cn-northwest-1", "enumValue": "China (Ningxia)"},
        {"realValue": "ca-central-1",   "enumValue": "Canada (Central)"}
    ],
    "validators": [{
        "name": "required"
    }]
}

Agrupación

Los elementos se pueden agrupar y activar o desactivar por el usuario, como se muestra a continuación. En este ejemplo, cuando la casilla de verificación es falsa, los elementos en el grupo que la sigue están inactivos:

Seleccionar la casilla activa el grupo, permitiendo la entrada en los segundo y tercer elementos:

El fragmento de código para esto:

{
  "name": "example_group",
  "type": "group",
  "displayName": "Example Group",
  "children": [
    {
      "name": "example_group_first_item",
      "type": "boolean",
      "multiple": false,
      "displayName": "Example Group First Item",
      "defaultValue": false
    },
    {
      "name": "example_group_second_item",
      "type": "string",
      "multiple": false,
      "displayName": "Example Group Second Item",
      "location": "last",
      "defaultValue": "1",
      "enumValues": [
        {
          "enumValue": "Postal Code",
          "realValue": "0"
        },
        {
          "enumValue": "ZIP",
          "realValue": "1"
        }
      ],
      "deps": {
        "disabled": {
          "op": "not",
          "args": {
            "op": "prop",
            "args": "example_group_first_item"
          }
        }
      }
    },
    {
      "name": "example_group_third_item",
      "type": "string",
      "multiple": false,
      "displayName": "Example Group Third Item",
      "widgetHint": "password",
      "defaultValue": "",
      "deps": {
        "disabled": {
          "op": "not",
          "args": {
            "op": "prop",
            "args": "example_group_first_item"
          }
        }
      }
    }
  ]
}

Validadores

Un campo puede incluir una lista de uno o más validadores que verifican la entrada del usuario y confirman su corrección. Si un validador falla, se presenta un mensaje de error al usuario. Los validadores se activan cuando un usuario sale de un campo, generalmente utilizando la tecla tab:

Ejemplos de validadores son requerir una entrada, usar solo dígitos, requerir una dirección de correo electrónico o ingresar un código postal. Se encuentran disponibles validadores estándar para situaciones comunes, como longitud de cadena y valor numérico, y se pueden crear validadores de patrón según sea necesario.

Los validadores se basan en los Validadores de Angular, excepto por los validadores hasValue y requiredExpr, que son validadores personalizados de Integration Studio.

Todos los validadores se llaman siguiendo el patrón mostrado en este ejemplo:

{
    "displayName": "Number of columns",
    "name": "noOfColumns",
    "type": "number",
    "validators": [
        {
            "name": "required"
        },
        {
            "args": [
                "^([1-9]|[1-9]\\d|1\\d\\d|2[0-4]\\d|25[0-6])$"
            ],
            "errorMessage": "Only whole numbers 1 to 256 are allowed.",
            "name": "pattern"
        }
    ]
}

Aquí, se muestran dos validadores para el campo noOfColumns. El primer validador es un validador required, que requiere únicamente que se especifique el nombre para invocarlo. Esto significa que el campo debe completarse (es requerido). Un asterisco rojo en la interfaz de usuario de Integration Studio indica que el campo es obligatorio.

El segundo validador es un validador pattern, que busca una cadena que coincida con el patrón de expresión regular dado por ^([1-9]|[1-9]\\d|1\\d\\d|2[0-4]\\d|25[0-6])$. Si este validador falla, se mostrará el mensaje de error al usuario. Tenga en cuenta que el patrón real utilizado será ^([1-9]|[1-9]\d|1\d\d|2[0-4]\d|25[0-6])$, ya que cualquier barra invertida en el patrón debe ser escapada.

Un validador se llama por nombre, y cualquier argumento se pasa como una lista, como se muestra en los ejemplos anteriores. Se puede especificar opcionalmente un mensaje de error que se devolverá. Si no se especifica, se utiliza un mensaje de error predeterminado (como se cubre para cada validador a continuación). Observe cómo el mensaje de error puede acceder a los atributos del campo, como displayName y args, para crear validadores que sean extensibles y no frágiles a cambios en el código.

Estos validadores están disponibles por nombre:

• required

  • No toma argumentos
  • Mensaje predeterminado: ${displayName} es requerido

• requiredTrue

  • No toma argumentos
  • Mensaje predeterminado: ${displayName} es requerido
  • Este validador se utiliza comúnmente para casillas de verificación requeridas

• email

  • No toma argumentos
  • Mensaje predeterminado: ${displayName} debe ser una dirección de correo electrónico válida

• hasValue (validador personalizado de Integration Studio)

  • No toma argumentos
  • Mensaje predeterminado: ${displayName} es requerido

• min

  • Toma un argumento: el valor numérico mínimo
  • Mensaje predeterminado: ${displayName} debe tener un valor de al menos ${args[0]}

• minlength

  • Toma un argumento: el número mínimo de caracteres
  • Mensaje predeterminado: ${displayName} debe tener al menos ${args[0]} caracteres

• max

  • Toma un argumento: el valor numérico máximo
  • Mensaje predeterminado: ${displayName} tiene un valor mayor que ${args[0]}

• maxlength

  • Toma un argumento: el número máximo de caracteres
  • Mensaje predeterminado: ${displayName} excede ${args[0]} caracteres

• pattern

  • Toma un argumento: una cadena patrón de expresión regular de JavaScript que la entrada debe coincidir
  • Cualquier barra invertida en el patrón debe ser escapada: el patrón [^\s]+ debe ingresarse como [^\\s]+
  • Mensaje predeterminado: ${displayName} es inválido

• requiredExpr (validador personalizado de Integration Studio)

  • Toma un argumento: una expresión que debe ser satisfecha
  • Mensaje predeterminado: ${displayName} es requerido

Ejemplos de patrones

Cualquier barra invertida en el patrón debe ser escapada: el patrón [^\s]+ debe ingresarse como [^\\s]+

Ejemplo de trabajo

Consulta el archivo adapter.json del conector de Dropbox para un ejemplo de trabajo que utiliza muchos de estos componentes de la interfaz de usuario.