Componentes de UI do SDK do Conector Básico

Visão Geral

Estes componentes básicos de UI estão disponíveis:

• Entrada de string com valor padrão
• Entrada de string sem valor padrão
• Entrada de string com entrada oculta ("Senha")
• Entrada de string com entrada oculta (Nenhum elemento de UI visível)
• Área de texto
• Entrada numérica
• Entrada booleana (Caixa de seleção)
• Escolha de rádio
• Menu suspenso

Componentes de UI mais sofisticados estão disponíveis e descritos como Componentes Complexos.

Componentes Básicos de UI

Este exemplo mostra os componentes básicos disponíveis, com fragmentos de código detalhados nos exemplos que seguem:

Características Comuns

Todos os componentes de UI podem ter um defaultValue e validators; veja o primeiro campo de string para um exemplo de ambos. Validadores são descritos em Validadores.

Campos que mostram um ícone variável são exemplos de componentes de UI que suportam substituição de variáveis. Quando um usuário insere um colchete de abertura ([), uma lista de possíveis conclusões de variáveis (variáveis Jitterbit, de projeto e globais) será exibida. Atualmente, apenas um componente de UI Entrada de String suporta substituição de variáveis.

Recuperar valores

Os valores são recuperados das propriedades com base em seus nomes. Isso significa que os nomes precisam ser exclusivos para cada conexão e atividade.

O método de fábrica de conexão recebe uma instância das propriedades (props) que podem ser usadas 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);
}

No exemplo acima, os valores de accessToken e appKey são recuperados das propriedades usando as palavras-chave apropriadas (ACCESS_TOKEN, definido como "access-token" e APP_KEY, definido como "app-key").

Entrada de string com valor padrão

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

Entrada de string sem valor padrão

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

Entrada de string com entrada ofuscada ("Senha")

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

Entrada de string com entrada oculta (Nenhum elemento de UI visível)

Neste caso, nenhum elemento de UI visível é exibido. Um valor está disponível para configuração, seja como um valor padrão ou programaticamente por outros componentes.

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

Área de texto

Projetada para várias linhas de texto.

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

Entrada numérica

Para inserir números, com setas de incremento/decremento (visíveis ao passar o mouse ou quando o campo está em foco) e ativação por teclado (as teclas de seta para cima e para baixo aumentam e diminuem o valor).

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

Entrada booleana (Checkbox)

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

Escolha de rádio

Usado para criar grupos de botões de opção. O realValue é o valor que será retornado quando recuperado das propriedades no conector. O enumValue é exibido para o usuário.

{
  "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"
}

Menu suspenso

Usado para criar grupos de menus suspensos. O realValue é o valor que será retornado quando recuperado das propriedades no conector. O enumValue é exibido para o usuário.

{
  "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"
}

Menus suspensos suportam edição e pesquisa. Isso é especificado definindo uma propriedade adicional, enumOptions, que suporta editable e searchable:

• editable: Se true, um usuário pode adicionar uma nova opção ao menu suspenso e selecionar essa nova opção. O padrão é false.
• searchable: Se true, um usuário pode digitar no menu suspenso para filtrar as opções existentes no menu. O padrão é false.

As duas opções podem ser combinadas, se desejado. A presença de uma não implica na outra. Por exemplo, uma seleção de versão poderia ser:

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

Exemplo de menu suspenso da região AWS

Este é um exemplo mais longo que mostra como as propriedades que um usuário precisará fornecer ao configurar uma conexão ou atividade podem ser codificadas para seleção. Neste exemplo, a Região AWS para conectar ao endpoint do Amazon S3 é algo que o usuário precisará fornecer. O realValue é o valor que será retornado quando recuperado das propriedades no conector. O enumValue é exibido para o usuário.

Para especificá-lo no adapter.json e na interface do usuário, você poderia fornecer uma seleção de menu suspenso para especificar isso:

Este fragmento de código define o menu suspenso:

{
    "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"
    }]
}

Agrupamento

Itens podem ser agrupados e ativados ou desativados pelo usuário, conforme mostrado abaixo. Neste exemplo, quando a caixa de seleção é falsa, os itens no grupo que a segue estão inativos:

Selecionar a caixa de seleção ativa o grupo, permitindo a entrada nos itens segundo e terceiro:

O fragmento de código para isso:

{
  "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

Um campo pode incluir uma lista de um ou mais validadores que verificam a entrada do usuário e confirmam sua correção. Se um validador falhar, uma mensagem de erro é apresentada ao usuário. Os validadores são acionados quando um usuário sai de um campo, normalmente usando a tecla tab:

Exemplos de validadores incluem exigir uma entrada, usar apenas dígitos, exigir um endereço de email ou inserir um código postal. Validadores padrão para situações comuns, como comprimento de string e valor numérico, estão disponíveis, e validadores de padrão podem ser criados conforme necessário.

Os validadores são baseados nos Validadores do Angular, exceto pelos validadores hasValue e requiredExpr, que são validadores personalizados do Integration Studio.

Todos os validadores são chamados seguindo o padrão mostrado por este exemplo:

{
    "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"
        }
    ]
}

Aqui, dois validadores são mostrados para o campo noOfColumns. O primeiro validador é um validador required, que exige apenas que o nome seja especificado para ser invocado. Isso significa que o campo deve ser preenchido (é obrigatório). Um asterisco vermelho na interface do usuário do Integration Studio indica que o campo é obrigatório.

O segundo validador é um validador pattern, que está procurando uma string que corresponda ao padrão de expressão regular dado por ^([1-9]|[1-9]\\d|1\\d\\d|2[0-4]\\d|25[0-6])$. Se este validador falhar, a mensagem de erro será mostrada ao usuário. Observe que o padrão real usado será ^([1-9]|[1-9]\d|1\d\d|2[0-4]\d|25[0-6])$, já que qualquer barra invertida no padrão deve ser escapada.

Um validador é chamado pelo nome, e quaisquer argumentos são passados como uma lista, como mostrado nos exemplos acima. Uma mensagem de erro que deve ser retornada pode ser especificada opcionalmente. Se não for especificada, uma mensagem de erro padrão é usada (como abordado para cada validador abaixo). Observe como a mensagem de erro pode acessar os atributos do campo, como displayName e args, para criar validadores que são extensíveis e não frágeis a mudanças de código.

Esses validadores estão disponíveis por nome:

• required

  • Não aceita argumentos
  • Mensagem padrão: ${displayName} é obrigatório

• requiredTrue

  • Não aceita argumentos
  • Mensagem padrão: ${displayName} é obrigatório
  • Este validador é comumente usado para checkboxes obrigatórios

• email

  • Não aceita argumentos
  • Mensagem padrão: ${displayName} deve ser um endereço de email válido

• hasValue (validador personalizado do Integration Studio)

  • Não aceita argumentos
  • Mensagem padrão: ${displayName} é obrigatório

• min

  • Aceita um argumento: o valor numérico mínimo
  • Mensagem padrão: ${displayName} deve ter um valor de pelo menos ${args[0]}

• minlength

  • Aceita um argumento: o número mínimo de caracteres
  • Mensagem padrão: ${displayName} deve ter pelo menos ${args[0]} caracteres

• max

  • Aceita um argumento: o valor numérico máximo
  • Mensagem padrão: ${displayName} tem um valor maior que ${args[0]}

• maxlength

  • Aceita um argumento: o número máximo de caracteres
  • Mensagem padrão: ${displayName} excede ${args[0]} caracteres

• pattern

  • Aceita um argumento: uma string padrão de expressão regular JavaScript que a entrada deve corresponder
  • Qualquer barra invertida no padrão deve ser escapada: o padrão [^\s]+ deve ser inserido como [^\\s]+
  • Mensagem padrão: ${displayName} é inválido

• requiredExpr (validador personalizado do Integration Studio)

  • Aceita um argumento: uma expressão que deve ser satisfeita
  • Mensagem padrão: ${displayName} é obrigatório

Exemplos de padrões

Qualquer barra invertida no padrão deve ser escapada: o padrão [^\s]+ deve ser inserido como [^\\s]+

Exemplo funcional

Veja o arquivo adapter.json do conector do Dropbox para um exemplo funcional que utiliza muitos desses componentes de interface.