Class: Link

@nginstack/web-framework/lib/anchor/Link~ Link

Define um atalho para auxiliar o fluxo das interações ou para executar códigos sem sair da interação corrente. Através de um atalho podemos ir para uma interação dentro ou fora do processo.

Parameters:
Name Type Argument Description
name string

Nome do atalho. O valor informado também será utilizado como o texto do botão, caso não a propriedade #label não seja informada.
target string| function

Poderá ser informado:

  • nome de uma interação;
  • nome de uma atividade;
  • função que será atribuída ao evento click do link. Esta função recebe como parâmetro a instância do link.
processKey number <optional>

Parâmetro opcional que indica a chave do processo que contém a atividade ou interação informada no parâmetro "target". Será considerado o processo corrente quando não for informado.
newTab boolean <optional>

Parâmetro opcional que indica se deve ser criada uma nova aba para exibir a interação ou atividade informada em "target". Será considerado "false" quando não for informado.
Examples
// O exemplo ilustra a criação de um link definindo uma função que será
// executada ao se clicar nele, também ilustra a passagem de parâmetro obtido a partir do link.
const linkEspelhoDoPedido = this.link('consultaEspelhoDoPedido').on('click', function (event) {
  const processo = -1;
  process.setNextInteraction('run', ['chave', event.link.params.chave], processo, null, true);
});
linkEspelhoDoPedido.params['chave'] = this.ds.chave;
// O exemplo ilustra a criação de um link que irá para a interação "geraPedido".
const link = this.link('linkGeraPedido', 'geraPedido');
// O exemplo ilustra a criação de um link que irá executar a interação
// "query" do processo indicador por "chaveProcesso" e abrirá em uma nova aba, também
// ilustra a passagem de parâmetros para essa interação através do link.
const link = this.link('cadastro', 'query', chaveProcesso, true);
link.params['chave'] = this.ds.num('chave');
link.params['versao'] = this.ds.num('versao');

Extends

Members

autoSanitize :boolean

Determina se texto do atalho deve ser tratado para remover tags que possam ser utilizadas com o objetivo de injetar scripts maliciosos em ataques do tipo Cross Site Scripting (XSS).

Ao desativar esta propriedade, é de crítica importância que algum tipo de validação ou sanitização seja realizada no conteúdo a ser escrito na tela.

Type:
  • boolean

createNewTab :boolean

Indica se deverá ser aberta uma nova aba para exibir o conteúdo da interação ou atividade apontada por esta âncora.

Type:
  • boolean

cssClass :string

Classe CSS complementar que será utilizada para configurar o visual do atalho. Essa classe será adicionada à classe padrão do link, portanto a configuração visual especializada deverá considerar as configurações visuais padrão.

Deve ser informada apenas o nome da classe CSS.

Type:
  • string
Example
const link = this.link('example', 'interaction');
  link.cssClass = 'custom-link';

duplicationHandling :module:@nginstack/engine/lib/event/DuplicationHandling

Indica como deve ser tratada a tentativa de registrar uma função de listener duplicada neste Emitter. Valores possíveis: DuplicationHandling.IGNORE (padrão), DuplicationHandling.ACCEPT e DuplicationHandling.REMOVE.

Type:
Inherited From:

enabled :boolean

Indica se o componente pode ser acionado pelo usuário. Quando desabilitado, ele estará visível, mas com uma cor diferente, sinalizando que não pode ser clicado.

Type:
  • boolean

hint :string

Mensagem que será exibida para o usuário final quando ele passar o mouse sobre o componente.

Type:
  • string

label :string

Texto que será exibido para o usuário. Caso não seja informado, será utilizado o valor da propriedade "name".

Type:
  • string

layout :module:@nginstack/web-framework/lib/process/LayoutConfig~LayoutConfig

Opções que definem como este componente deve ser apresentando no leiaute da interação do processo.

Type:
See:
Example
grid.layout.column = 1;
grid.write();

link.layout.column = 2;
link.write()

// Apresentação:
// ------------   ----------
// |   grid   |   |  link  |
// ------------   ----------

listenerCompareFunction :function

Indica como devem ser comparados dois listeners para determinar se eles são iguais. Valores possíveis: ListenerCompareFunctions.STRICT e ListenerCompareFunctions.SOURCE. O tratamento do registro de um listener duplicado é determinada pela propriedade Emitter#DuplicationHandling.

Type:
  • function
Inherited From:
See:

name :string

Nome único do componente informado ao construtor.

Type:
  • string

nextInteractionName :string

Nome da interação ou atividade que será exibida quando o componente for acionado.

Type:
  • string

nextProcessId :string

Id da instância de um processo que contém a atividade ou interação informada na propriedade "nextInteractionName". Quando esta propriedade é informada, um processo já aberto pelo usuário será navegado para a interação ou atividade informada em "nextInteractionName".

Type:
  • string

nextProcessKey :number

Chave do processo que contém a atividade ou interação informada na propriedade "nextInteractionName". Será considerado o processo corrente quando não for informado.

Type:
  • number

onClick :module:@nginstack/engine/lib/event/Adapter~Adapter

Função que será atribuída ao evento click do link.

Type:
Deprecated:
  • Use this.on('click', listener);

parameters :Array

Nomes dos parâmetros que serão passados para o processo destino ou para o evento "click" quando este link for utilizado. Os valores devem ser informados por outra API, como o writeLink do SimpleLayout. Opcionalmente, também pode ser informado um array com o nome e o valor do parâmetro.

O uso desta propriedade em colunas do SimpleLayout com múltiplos links requer a atenção de garantir que todos os links utilizem a mesma quantidade de parâmetros, pois o mesmo conjunto de valores será passado para os links. Nesse cenário de uso, deve-se preferir utilizar a propriedade params.

Caso os mesmos nomes de propriedades sejam definidos em parameters e params, será dada preferência aos valores definidos em parameters se forem informados os valores dos parâmetros. Os valores definidos em parameters sobrescrevem os definidos em params na escrita do Link.

Esta propriedade é legada e mantida apenas para fins de compatibilidade. Em novas implementações, utilize apenas a propriedade params.

Importante: alterações nos parâmetros após a execução dos métodos #write e #getHtml são ignoradas. No evento de "click" ou na interação destino são utilizados os valores dos parâmetros informados no momento da geração do HTML do link.

Type:
  • Array
Deprecated:
  • Utilize a propriedade `params`.
Example
link.parameters.push('eventKey');
link.parameters.push('description');
link.parameters.push(['action', ds.str('action')]);

sl.writeLink(ds.num('iKey'), [ds.num('iKey')], ds.str('iDescription'));

params :Record.<string, (string|number|boolean|Date|null)>

Parâmetros que serão passados para o processo destino ou para o evento "click" quando este link for clicado.

Esta propriedade é um objeto que associa os nomes das propriedades ao seus valores. As propriedades informadas serão definidas no processo destino quando o link for acionado. Somente podem ser informados valores primitivos ou datas.

Importante: alterações nos parâmetros após a execução dos métodos #write e #getHtml são ignoradas. No evento de "click" ou na interação destino são utilizados os valores dos parâmetros informados no momento da geração do HTML do link.

Type:
  • Record.<string, (string|number|boolean|Date|null)>
Example
link.params.eventKey = ds.num('iKey');
link.params.description = ds.str('iDescription');

paramsFieldNames :Array.<string>

Nomes de campos do dataSet da grade que servirão de parâmetros para o atalho. Caso seja informado uma lista textual de campos, ela será convertida automaticamente em um array de nomes.

Por padrão, os valores dos campos serão publicados como propriedades de mesmo nome no processo, portanto, é recomendado que os nomes sejam normalizados em caixa baixa. Este comportamento é alterado quando existem parâmetros abertos definidos em parameters. Nesse cenário, os campos serão publicados com os nomes dos parâmetros abertos na posição correspondente de paramsFieldNames.

Type:
  • Array.<string>
Examples
const link = this.link('myLink');
link.paramsFieldNames = ['chcriacao', 'classe'];
const link = this.link('myLink');
link.paramsFieldNames = ['CHCRIACAO', 'CLASSE'];
link.parameters = ['chaveDeCriacao', 'classeDoRegistro'];

parent :module:@nginstack/engine/lib/classdef/Field~Field|module:@nginstack/web-framework/lib/simple-layout/Column~Column

Objeto que contém este atalho. Poderá ser uma instância de:

  • Field, para os atalhos definidos em um campo de grade;
  • Column, para os atalhos de uma coluna de um relatório.
Type:
See:

permissionKeyWord :string

Palavra chave utilizada para controlar o poder do usuário em disparar esta âncora. Se o usuário não tiver permissão, o componente será exibido desabilitado, independente do valor da propriedade "enabled".
Quando informado, o usuário ou o seu grupo deverão ter ao menos uma permissão que contenha a palavra chave definida. A permissão deve ser concedida no processo "Administração do sistema > Segurança > Permissões", selecionado o processo na árvore de diretórios e arquivos, e adicionando um registro na grade de permissões e preenchendo o campo "Palavras Chaves".

Type:
  • string

process :module:@nginstack/web-framework/lib/process/Process~Process

Instância do processo onde este objeto foi criado.

Type:

size :string

Controla o tamanho do texto do Link. Valores possíveis: "small", "default" ou "large".

Um valor vazio será considerado como o valor "default". O tamanho irá se ajustar às configurações de densidade variável do Web Framework.

Type:
  • string
See:
  • module:@nginstack/web-framework/lib/anchor/LinkSize
Example
const link = this.link('example', 'interaction');
link.size = 'small';
link.write('Small link');

srcId :string

Identificação do arquivo que será descarregado pelo navegador quando o usuário clicar no link. Essa identificação é gerada pelo método Process.prototype.getFileId.

O uso desta API não é mais recomendado, pois a sessão do usuário é bloqueada enquanto o arquivo é descarregado. Prefira utilizar o método Process.prototype.download.

Type:
  • string
See:
Examples
// O exemplo ilustra a criação de um link que irá fazer o download do
// arquivo "Arquivo temporário.txt"
this._download_file = this.link('_download_file');
this._download_file.srcId = this.getFileId(path, 'Arquivo temporário.txt');
// O exemplo ilustra a criação de um link que irá fazer o download do
// script -1898145534
this._download_script = this.link('_download_script');
this._download_script.srcId = this.getFileId(-1898145534, 'Incrementar conexões.reg');

validateLastInteraction :boolean

Determina se os componentes da interação corrente serão notificados que irá ocorrer uma navegação para uma outra interação, possibilitando que os componentes notificados tomem ações para validar os seus estados, podendo inclusive cancelar o comando de navegação do usuário.
A ação de validação irá variar entre os componentes notificados. Por exemplo: a grade irá executar um "post" caso o registro atual se encontre em edição e irá bloquear a navegação caso o registro não possa ser gravado.

Type:
  • boolean

<static> createProcess :*

Função chamada quando a ação precisa criar um processo. Essa propriedade é configurada automaticamente pelo Web Framework.

Type:
  • *

Methods

addListenersFromEmitter(emitter [, opt_type])

Adiciona neste emitter os listeners do emitter informado.

Parameters:
Name Type Argument Description
emitter module:@nginstack/engine/lib/event/Emitter~Emitter

Emitter que terá os eventos copiados.
opt_type string <optional>

Tipo do evento a ser copiado. Caso não seja informado, serão copiados os listeners de todos os tipos de evento.
Inherited From:

assign(obj)

Atribui as propriedades desta instância com os valores das propriedades da instância informada.

Observação: o nome do link não é copiado por este método, pois é um identificador único e imutável definido apenas no momento da sua criação.

Parameters:
Name Type Description
obj module:@nginstack/web-framework/lib/anchor/Link~Link

Objeto do qual se deseja obter os valores.

assignListeners(emitter [, opt_type])

Torna este emitter uma cópia do emitter informado. Os tipos de eventos registrados nesta instância serão preservados e complementados com os existentes em emitter.

Parameters:
Name Type Argument Description
emitter module:@nginstack/engine/lib/event/Emitter~Emitter

Emitter que terá os eventos copiados.
opt_type string| Array.<string> <optional>

Tipo do evento a ser copiado. Caso não seja informado, serão copiados os listeners de todos os tipos de evento. Também pode ser informado um array de tipo de eventos a sere copiados.
Inherited From:

clone()

Cria uma cópia desta instância.

Returns:
Type
module:@nginstack/web-framework/lib/anchor/Link~Link

emit(event)

Emite o evento informado, executando todas as funções de listeners previamente registradas para o tipo do evento emitido.

Parameters:
Name Type Description
event module:@nginstack/engine/lib/event/Event~Event

Evento a ser emitido.
Inherited From:
Throws:

Erro que dispara caso não exista um tipo registrado para manipulação do evento. Eventos aptos a serem manipulados devem ser registrados com o método #registerEventType.

Type
EventTypeException
Returns:

Retorna a indicação que o evento foi emitido para todos os listeners e não foi solicitado o cancelamento da ação padrão associada ao evento, por meio da execução do método Event#preventDefault. Caso o evento não possa ser cancelado (@link Event#cancelable}), será retornado sempre true.

Type
boolean

filterListeners(filterFn [, opt_type])

Elimina os listeners que não satisfaçam a função de filtro.

Parameters:
Name Type Argument Description
filterFn function

Função que indicará quais filtros devem ser mantidos neste emitter. Deverá ser retornado true para indicar que o filtro deve ser preservado.
opt_type string <optional>

Tipo de evento que terá os listeners filtrados. Caso não seja informado, os listeners de todos os tipos de eventos serão filtrados.
Inherited From:

getHtml(content [, parametersValue] [, cssClass])

Gera o markup HTML do link sem escrevê-lo na tela, permitindo que ele possa ser utilizado de forma mais flexível que o possibilitado pelo método #write.

O HTML do link gerado por este método não sincronizará as alterações realizadas nas propriedades do link após a geração do HTML, exceto se o link também for escrito no processo utilizando o método #write.

Importante: quando o link possui parâmetros, o retorno deste método contém um identificador único que será distinto para cada chamada, mesmo que os parâmetros sejam os mesmos. Em cenários onde o resultado precisa ser consistente, como em agrupamentos de relatórios, é necessário armazenar e reutilizar o HTML gerado para o mesmo conjunto de parâmetros.

Parameters:
Name Type Argument Description
content string

Conteúdo que deverá ser impresso no link. Se não for informado, será impresso o rótulo ou o nome do link.
parametersValue string <optional>

Valores dos parâmetros. Prefira utilizar a propriedade #params.
cssClass string <optional>

Classe CSS adicional do link. Prefira utilizar a propriedade #cssClass.
Returns:
Type
string
Examples
// Exemplo de link sendo utilizado em markup HTML
const link = process.link('showDetails').on('click', function () {
  process.alert('Você clicou no link.');
});

process.write('<div>' + link.getHtml('Exibir detalhes') + '</div>');
// Coluna de relatório sendo escrita com links distintos de acordo com os dados do registro
const sl = process.getSimpleLayout();
sl.column('Chave');
sl.column('Ação');

const linkAprovar = process.link('linkAprovar').on('click', function () {
  process.alert('Você aprovou a operação.');
});
const linkDesaprovar = process.link('linkDesaprovar').on('click', function () {
  process.alert('Você desaprovou a operação.');
});

for (ds.first(); !ds.eof; ds.next()) {
  const chave = ds.num('CHAVE');
  linkAprovar.params.chave = chave;
  linkDesaprovar.params.chave = chave;
  const link = ds.bool('aprovada')
    ? linkDesaprovar.getHtml('Desaprovar operação')
    : linkAprovar.getHtml('Aprovar operação');
  sl.newRecord();
  sl.writeColumn(chave);
  sl.writeColumn(link, { renderContentAsHtml: true });
}
sl.end();
// Para utilizar esse método em agrupadores do SimpleLayout, defina `sl.autoSanitize = false`
// para preservar o HTML do link no rótulo do agrupador. Como cada chamada deste método gera um
// link único, em cenários com agrupamento, preserve e reutilize o mesmo HTML do link para o
// mesmo valor de grupo. Caso contrário o agrupamento será quebrado a cada registro.
const sl = process.getSimpleLayout();
sl.autoSanitize = false;
sl.column('Descrição');

const groupLink = process.link('abrirAgrupador').on('click', function (event) {
  process.alert('Você clicou no agrupador "' + event.link.params.groupName + '".');
});

const linksByGroupName = {};

function getLink(groupName) {
  if (!(groupName in linksByGroupName)) {
    groupLink.params.groupName = groupName;
    linksByGroupName[groupName] = groupLink.getHtml(groupName);
  }
  return linksByGroupName[groupName];
}

sl.newRecord([getLink('Grupo A')], ['Grupo A']);
sl.writeColumn('Registro 1');

sl.newRecord([getLink('Grupo A')], ['Grupo A']);
sl.writeColumn('Registro 2');

sl.newRecord([getLink('Grupo B')], ['Grupo B']);
sl.writeColumn('Registro 3');
sl.end();

hasListeners(type)

Verifica se há listeners registrados para o tipo de evento informado.

Parameters:
Name Type Description
type string| Array.<string>

Tipo do evento a ser verificado. Também pode ser informado um array de tipos. Neste caso, será retornado true se houver ao menos um listener registrado para um dos tipos informados.
Inherited From:
Returns:

True se houver listeners registrados para o tipo de evento informado.

Type
boolean

listenerHandlers(type)

Obtém todas as funções de listeners registradas para o tipo de evento informado. O array retornado é uma cópia dos listeners registrados e sua manipulação não alterará a instância desta classe. Para adicionar ou remover uma nova função de listener, utilize os métodos #on ou #off.

Parameters:
Name Type Description
type string

Tipo de evento ao qual serão obtidos os EventListeners registrados.
Inherited From:
See:
Throws:

Será disparado um erro caso o tipo informado não tenha sido registrado previamente pelo método #registerEventType.

Type
EventTypeException
Returns:

Todas as funções de listeners registradas neste emitter para o tipo informado.

Type
Array.<function(module:@nginstack/engine/lib/event/Event~Event)>

listeners( [opt_type])

Obtém todos os listeners registrados para o tipo de evento informado. O array retornado é uma cópia dos listeners registrados e sua manipulação não alterará a instância desta classe. Para adicionar ou remover uma nova função de listener, utilize os métodos #on ou #off.

Parameters:
Name Type Argument Description
opt_type string <optional>

Tipo de evento ao qual serão obtidos os EventListeners registrados.
Inherited From:
See:
Throws:

Será disparado um erro caso o tipo informado não tenha sido registrado previamente pelo método #registerEventType.

Type
EventTypeException
Returns:

Todos os listeners registrados neste emitter para o tipo informado. Sempre serão retornadas instâncias de Listener, por mais que tenham sido registradas funções de listeners nos métodos #on ou #replaceListeners. Para obter as funções, acesse a propriedade Listener#handler dos elementos retornados ou utilize o método #listenerHandlers para obter a relação de funções. Caso não seja informado, serão retornados todos os listeners.

Type
Array.<module:@nginstack/engine/lib/event/Listener~Listener>

off(type, listener)

Remove uma função de listener previamente adicionada por meio do método #on.

Se uma função de listener for removida durante a emissão de um evento, ela será executada por mais que tenha sido removida. Ou seja, a remoção valerá para as emissões seguintes.

Parameters:
Name Type Description
type string

Tipo do evento que será removido.
listener module:@nginstack/engine/lib/event/Listener~Listener| function

Indica a função de listener a ser removida.
Inherited From:
See:
Returns:

Esta instância de Emitter, permitindo encadeamento de chamadas.

Type
module:@nginstack/engine/lib/event/Emitter~Emitter

offAll( [opt_type])

Remove todas as funções de listener associadas ao tipo informado. Caso o tipo não seja informado, serão removidas todas as funções de listeners de todos os tipos de eventos.

Parameters:
Name Type Argument Description
opt_type string <optional>

Tipo de evento que deverá ter os listeners removidos.
Inherited From:
Returns:

Esta instância de Emitter, permitindo encadeamento de chamadas.

Type
module:@nginstack/engine/lib/event/Emitter~Emitter

on(type, listener)

Registra uma função que deverá ser executada quando o evento indicado por type for emitido. Por padrão, a função será adicionada no final da fila de listeners, sendo executada após a execução dessas funções previamente registradas.

Se o listener for adicionado durante a emissão de um evento, ele será desconsiderado nesta emissão e será executado apenas nas emissões seguintes.

O comportamento deste emitter ao tentar registrar uma função de listener mais de uma vez é determinado pela propriedade #duplicationHandling.

Parameters:
Name Type Description
type string

Tipo de evento que será registrado.
listener function

Função que será executada quando ocorrer a emissão do evento.
Inherited From:
See:
Returns:

Esta instância de Emitter, permitindo encadeamento de chamadas.

Type
module:@nginstack/engine/lib/event/Emitter~Emitter
Example
modelDef.on('afterInsert', function (event) {
  event.data.setField('codigo', 'Novo cliente');
}).on('beforePost', function (event) {
  if (event.data.str('codigo').trim() == '') {
    throw new Error('O campo código é obrigatório.');
  }
});

registerEventType(type)

Registra um novo tipo de evento, permitindo que ele possa ser utilizado por esta instância de Emitter. A tentativa de emitir um evento ou listener de um tipo não registrado provocará um erro.

Parameters:
Name Type Description
type string| Array.<string>

Tipo do evento a ser registrado. Também pode ser informado um array de tipos.
Inherited From:

replaceListeners(type, listener)

Registra uma função de listener que irá substituir todos os listeners registrados para o tipo de evento indicado por type. A função informada receberá, além do parâmetro event, um segundo parâmetro que será uma função, que ao ser invocada, emitirá o o evento informado para os listeners que foram substituídos.

O comportamento deste emitter ao tentar registrar uma função de listener mais de uma vez é determinado pela propriedade #duplicationHandling.

Importante: o uso deste método não é recomendado. Ignorar os listeners registrados previamente por outros desenvolvedores é uma má prática de desenvolvimento e pode gerar inconsistências de dados. Seu uso deve ser restrito à compatibilização de eventos antigos que dependem deste comportamento, que antes eram declarados pelo método "set" da antiga API de Eventos do Engine (classe global Event).

Parameters:
Name Type Description
type string

Tipo de evento que será registrado.
listener module:@nginstack/engine/lib/event/Listener~Listener| function

Função que será executada quando ocorrer a emissão do evento.
Inherited From:
See:
Example
this.replaceListeners('beforePost', function (event, emit) {
   event.data.codigo = 'Novo cliente';
   emit(event);
 });

restoreParameters(storedParametersId)

Restaura os parâmetros do link preservados anteriormente pelo método storeParameters.

Parameters:
Name Type Description
storedParametersId string

Id retornado pelo método storeParameters.

storeParameters( [openParameterValues])

Persiste os parâmetros do link e retorna um id que permite a sua posterior restauração pelo método restoreParameters.

Parameters:
Name Type Argument Description
openParameterValues Array <optional>

Valores dos parâmetros abertos declarados em parameters.
Returns:

Id que identifica os parâmetros armazenados.

Type
string

unregisterEventType(type)

Remove o registro de um tipo de evento, bloqueando a utilização nesta instância de Emitter. A tentativa de emitir um evento ou listener de um tipo não registrado provocará um erro.

Parameters:
Name Type Description
type string| Array.<string>

Tipo do evento a ser bloqueado. Também pode ser informado um array de tipos.
Inherited From:

updateFieldParams(rowId)

Atualiza o propriedade params com os valores dos campos definidos em paramsFieldNames.

Parameters:
Name Type Description
rowId number

Identificador do registro do qual serão lidos os campos.

write( [content] [, parametersValue] [, cssClass])

Escreve o atalho na tela.

Parameters:
Name Type Argument Description
content string <optional>

Conteúdo que deverá ser impresso no link. Se não for informado, será impresso o rótulo ou o nome do link.
parametersValue string <optional>

Valores dos parâmetros. Prefira utilizar a propriedade #params.
cssClass string <optional>

Classe CSS adicional do link. Prefira utiliza a propriedade #cssClass.
Returns:
Type
string

Events

click

Evento disparado quando o usuário clica no link. Uma referência para o link pode ser acessada pela propriedade link.

Type: module:@nginstack/web-framework/lib/anchor/LinkEvent~LinkEvent
See:
Example
const link = process.link('validate').on('click', function (event) {
  const process = event.process;
  const newPassword = process.password.field('newPassword');
  if (!newPassword) {
    throw new Error('Informe uma nova senha.');
  }
  process.setNextInteraction('confirmChangePassword');
})