Vincular imagens a cadastros

Introdução

O processo de vinculação de arquivos a cadastros é útil para associar quaisquer arquivos de nosso sistema de arquivos virtual (VFS) a um determinado cadastro do Sistema. Um exemplo bem prático disso é o vínculo entre imagens e cadastros.

Objetivo

Explicar tecnicamente todo o procedimento necessário à importação de imagens, suas vinculações aos cadastros e a visualização dessas imagens no Sistema.

Estrutura do guia

A estrutura conceitual dos assuntos abordados neste guia é:

• • Pré-requisitos

  • Fluxo Operacional

    • • Configurando o ambiente para a importação e exibição.

      • Importando as imagens.

      • Visualizando e utilizando as imagens importadas.

Pré-requisitos

É necessário ter conhecimentos básicos de desenvolvimento no Sistema como conhecer o ambiente de desenvolvimento (IDE), saber criar um diretório (classe), ter o entendimento sobre o conceito do arquivo do tipo x-class, campos do tipo seleção múltipla e do tipo grade, etc. Além disso, é necessário o conhecimento do processo Importação de documentos.

Fluxo Operacional

Configurando o ambiente para a importação e exibição

Para realizar a configuração do ambiente de forma a possibilitar a importação e exibição das imagens, é necessário seguir os seguintes passos:

• 1. Iniciamos com a criação do diretório da importação dos arquivos os quais serão vinculados a um cadastro. Como estamos abordando um exemplo de importação de imagens, o novo diretório deverá ser criado em Raiz > Dados > Arquivos > Imagens.

  2. Em seguida, devemos criar o diretório de vínculo. Este diretório será utilizado para receber o arquivo x-class onde serão definidas algumas propriedades relativas à importação e é também onde será definido o campo de chave estrangeira que será a base do relacionamento com o cadastro. Este diretório deverá ficar em Raiz > Dados > Sistema > Relações > Relações entre Cadastros > Relações entre Cadastros e Arquivos > Relações entre cadastros e imagens.

  3. Agora que criamos o diretório de vínculo, devemos criar o arquivo do tipo x-class. Este arquivo precisa ter, necessariamente, as propriedades a seguir:

     1. • this.linkedTableName: deve conter o nome da tabela de cadastro que ficará vinculada às imagens importadas. Exemplo: this.linkedTableName = “iGroupUser”.

        • this.linkFieldName: o nome do campo, na tabela de vínculo, que será utilizado como chave estrangeira para a tabela de cadastro. Este é o campo base do relacionamento entre cada registro de vínculo e o respectivo registro associado na tabela de cadastro. Exemplo: this.linkFieldName = “iGroupUser”.

        • this.formatFileName: uma lista com os nomes dos campos-chaves de pesquisa. Cada arquivo importado deverá conter, em seu nome, chaves de pesquisa que serão utilizadas na busca e vinculação do arquivo importado. A importação ocorrerá para cada arquivo que tiver, em seu nome, uma chave de pesquisa correspondente a um registro da tabela de cadastro. Assim, por exemplo, para um this.formatFileName = [“iName”], os arquivos importados serão aqueles que, em seu nome, tiver um valor correspondente na coluna iName da tabela de cadastro.

        • this.targetDirectory: a chave do diretório onde ficarão armazenadas as imagens no sistema de arquivo virtual, ou seja, tabela iVfs. Estes diretórios precisarão ser filhos do diretório Imagens, localizado em Raiz > Dados > Arquivos > Imagens. Exemplo: this.targetDirectory = -1892603144; /* de Usuários */.

        • Outras propriedades opcionais são o this.acceptedMimeTypes e o this.maxFileSize. O this.acceptedMimeTypes restringe os mimetypes que serão aceitos no processo de importação. Já o this.maxFileSize define o tamanho máximo do arquivo a ser importado em bytes.

• • 1. Ainda neste arquivo do tipo x-class, outra necessidade é a própria definição do campo citado em linkFieldName. Exemplo da definição do campo iGroupUser na tabela iDataRel, campo este utilizado para a vinculação de imagens ao cadastro de usuários do Sistema:

    2. var fld = this.field("iGroupUser", "integer"); fld.label = 'Usuário'; fld.visible = true; fld.required = true; fld.classKey = -1898187809 /* Usuários */; fld.lookupType = LookupType.RECORD; fld.help = "Campo que armazena a chave do usuário associado à imagem.";

• 4. Para fechar este tópico de configuração, passamos agora à definição do que é possível configurar sobre a visualização das imagens no cadastro associado. Abaixo temos as propriedades que podem ser configuradas em arquivos x-class dos diretórios destes cadastros. Observe que a classe Raiz já possui uma configuração padrão que se aplica a todos os cadastros do Sistema. Sugerimos que essa configuração padrão não seja redefinida classe a classe a fim de manter uma consistência visual.

     1. • this.imageWidth: largura padrão, em pixels, da imagem associada a este registro, caso exista uma. Esta largura também será utilizada em consultas que exibam esta imagem.

        • this.imageHeight: altura padrão, em pixels, da imagem associada a este registro, caso exista uma. Esta altura também será utilizada em consultas que exibam esta imagem.

        • this.zoomImageWidth: indica a largura padrão, em pixels, da imagem associada a este registro quando está sendo exibida a ampliação dela, normalmente ativa quando ela recebe o foco do mouse.

        • this.zoomImageHeight: indica a altura padrão, em pixels, da imagem associada a este registro quando está sendo exibida a ampliação dela, normalmente ativa quando ela recebe o foco do mouse.

        • this.zoomImageOnHover: quando definido com valor lógico verdadeiro (true), indica que haverá ampliação ao passar o cursor do mouse sobre uma imagem associada a este registro.

• • 1. Neste mesmo x-class, já podemos realizar a definição do campo do tipo grade para mostrar as imagens associadas a este cadastro. Existe uma peculiaridade muito importante sobre este campo que nos leva, obrigatoriamente, a definir este campo com o nome xImages. Isto é necessário para simplificarmos a API de manipulação desta funcionalidade. Segue um exemplo da definição do campo xImages do cadastro de imagens de usuários:

    2. var fld = this.field('xImages', 'grid'); fld.order = 105000; fld.label = "Imagens"; fld.classKey = -1898141861; /* Imagens de Usuários */ fld.masterFieldNames = "iKey"; fld.detailFieldNames = "iGroupUser";

Importando as imagens

Para realizar a importação das imagens, temos duas opções. A primeira é realizada de forma interativa, por meio do processo Importação de Documentos, cuja documentação está disponível no endereço: http://erp.bematech.com/o-que-fazemos/modulos/administrador/manuais/configurando-campos-da-tabela-para-importacao-de-documentos. A segunda forma de importar imagens é de forma programática e, para isso, o desenvolvedor deve utilizar a API do DocumentStore. A documentação dessa API encontra-se no endereço: http://desenvolve.bematech.com:8001/help/symbols/DocumentStore.html.

Visualizando e utilizando as imagens importadas

Abaixo, seguem algumas formas de se obter as imagens importadas:

• 1. Podemos visualizar as imagens associadas aos cadastros através do próprio cadastro, onde veremos o campo xImages do tipo grade, conforme citamos no final da seção de configuração.

  2. Outra forma de visualizar estas imagens é através de um relatório, onde o desenvolvedor pode fazer uso da dimensão !IMAGE. Para exibir imagens em visualizações, o desenvolvedor pode se utilizar da documentação disponível em: http://erp.bematech.com/o-que-fazemos/modulos/web-framework/manuais/manual-das-visualizacoes-das-consultas-automatizadas/exibindo-imagens-em-visualizacao.

  3. Caso um cadastro tenha imagens vinculadas, todos os campos que apontam para esse cadastro passam a exibir, ao lado do valor do campo, a imagem miniatura em questão, o thumbnail. A apresentação do thumbnail é automática para todos os cadastros com imagens associadas. Caso se deseje desligar essa visualização automática, basta inserir a linha de código a seguir na classe do cadastro vinculado às imagens:

     1. this.thumbnail.visible = false;

     2. Devido ao conceito de herança de nosso sistema de arquivos, para desligar a visualização do thumbnail de todas as classes, basta definir essa mesma linha de código em um x-class no diretório Raiz.

  4. Existe também uma API que permite o desenvolvedor obter imagens via código. A documentação desta API está disponível em: http://desenvolve.bematech.com:8001/help/symbols/uwl.image.html.