Eventos da Base

Em todos os eventos da base, o objeto this também estará disponível para que seja possível acessar o objeto IBase que representa a base em questão. Os métodos e propriedades públicos deste objeto podem ser invocados e utilizados em todos os eventos abaixo citados.

OnAdvQueryDoc

Este evento ocorre na montagem do formulário de pesquisa avançada e permite alterar tal formulário. O retorno da função é código HTML. 

Function OnAdvQueryDoc
   ...
End Function

OnAdvQueryPage

Este evento ocorre na montagem da página de pesquisa avançada e permite alterar toda a página. O retorno da função é código HTML. 

Function OnAdvQueryPage
   ...
End Function

OnBeforeGotodir

Este evento ocorre sempre que navegamos para um diretório de uma base. Antes que se entre num diretório desejado, o evento é lançado. Isto possibilita, por exemplo, a alteração das própriedades de visibilidade dos campos de acordo com o diretório da hierarquia.

Para exemplificar o tratamento deste evento, imagine uma aplicação que necessita mudar a visibilidade de alguns campos de acordo com o diretório. Por exemplo, suponha que em uma aplicação de biblioteca os campos autor e editora não devam aparecer em um diretório chamado CD, pois não fazem sentido. O código abaixo implemente tal situação. 

Sub OnBeforeGotodir( nextdir )
  if LCase( Left( nextdir, 2 ) ) = "cd" then
    this.fields.Item( "autor" ).List = False
    this.fields.Item( "autor" ).Order = False   
    this.fields.Item( "editora" ).List = False
    this.fields.Item( "editora" ).Order = False
  Else
    this.fields.Item( "autor" ).List = True
    this.fields.Item( "autor" ).Order = True    
    this.fields.Item( "editora" ).List = True
    this.fields.Item( "editora" ).Order = True
  End if
End Sub

O código acima testa a variável nextdir, passada como parâmetro no evento, o diretório onde se está entrando. Caso seja o diretório CD, ou um diretório abaixo dele, os atributos relativos a vizualização e ordenação para os campos autor e editora são modificados.

OnDetailDoc

Este evento ocorre na montagem da tabela aonde se apresenta os detalhes de um registro. Através dele é possível alterar a área de detalhes de duas formas: modificando ou adicionando código HTML ao código default retornado no método defaultDetailDoc de IBase; ou mudando as propriedades de visualização de algum campo a partir da propriedade Detail de IField. 

Function OnDetailDoc( id, group, row )
  ...
End Function
Os parâmetros passados neste evento são os seguintes:

OnDetailPage

Este evento ocorre sempre que a página de detalhes de um registro está sendo montada, mais especificamente antes do código relativo as orelhas dos grupos multivalorados. Através dele é possível alterar o código desta página inserindo algo antes das orelhas ou após a área relativa ao registro. É possível também mudar a visibilidade de alguns campos assim como no evento OnDetailDoc. Os parâmetros passados neste evento são os mesmos do evento anterior e possuem a mesma semântica. 

Function OnDetailPage( id, group, row )
  ...
End Function

OnEdit

Este evento é chamado antes do salvamento de um registro em edição. Este evento pode ser utilizado para alimentar o valor de campos com preenchimento automático (usuário logado, data e hora atual), ou modificar valores existentes. Isso pode ser feito a partir da manipulação do objeto request que é passado como parâmetro. Este objeto contém os itens que foram preenchidos no formulário de edição. Os itens id, group e row estão presentes no request e obedecem a semântica destes parâmetros descritos nos eventos OnEditoDoc e OnEditPage. O exemplo abaixo mostra a utilização do evento OnEdit para guardar o login do usuário que realizou a última atualização num campo usuario_atualizacao. 

Sub OnEdit( request )
  request.AddItem "usuario_atualizacao", this.IApplication.Application.User.LoginName
End Sub

OnEditDoc

Este evento ocorre sempre que o formulário de edição de um registro está para ser montado. Através dele é possível alterar o formulário de edição de acordo com as necessidades específicas da aplicação. 

Function OnEditDoc( id, group, row )
   ...
End Function

A semântica dos parâmetros é idêntica ao caso OnDetailDoc. A única diferença é no caso de uma nova linha de um grupo, nestas situações o valor do parâmetro row é igual a -1.

OnEditPage

Este evento ocorre sempre que a página de edição de um registro está para ser montada. O evento OnEditPage está para o evento OnEditDoc assim como o evento OnDetailPage está para o evento OnDetailDoc. 

Function OnEditPage( id, group, row )
   ...
End Function

OnGetDirName

Este evento só ocorre em bases que não utilizam a navegação hierárquica. Ele ocorre sempre que um novo registro é inserido. Através dele é possível informar à aplicação qual o diretório que deve ser utilizado para armazenar os dados do registro sendo criado. Isto permite que o armazenamento dos dados binários seja organizado hierarquicamente mesmo quando o usuário não deseja ou não precisa desta hierarquia. O evento recebe como parâmetro, um objeto request do LightBase Web com as informações alimentadas a partir do formulário de inserção de registro. Isto pode ser útil na definição do diretório.

O Evento OnGetDirName deve ser declarado como uma função e deve retornar uma string com o nome do diretório. Para exemplificar o uso deste evento apresentamos um código que retorna o nome do diretório com base am alguns campos obtidos a partir do parâmetro request. 

Function OnGetDirName( request )
  OnGetDirName = request.Value( "departamento" ) & "\" & Mid( lbrequest.Value( "nome" ), 1, 1 )
End Function

Podemos perceber que o código acima distribui os dados binários em uma árvore de diretórios onde o primeiro nível é originário de um campo chamado departamento e o segundo é a primeira letra do campo nome. Caso o diretório não exista ainda, o GoldenDoc cria. Caso este evento não seja definido, os binários numa aplicação sem diretórios são armazenados na raiz do diretório de conteúdo.

OnHeader

Este evento permite alterar o cabeçalho de todas as páginas cuja operação é relativa a uma base de dados. Este evento é equivalente ao evento OnHeader de aplicação, e como ele deve ser declarado como uma função e retornar uma string com o código em HTML referente ao cabeçalho. O exemplo abaixo de uso do evento OnHeader é extraído da aplicação LIVROS. 

Function OnHeader
  Dim appname
  if TypeName( this ) = "IBase" then
    appname = this.IApplication.Name
  else
    appname = this.Name
  end if
  OnHeader = "<table cellpadding='0'  cellspacing='0' border='0' width='100%'>" & _
    "<tr bgcolor='#354C8E'>" & _
    "<td>" & _
      "<a href=""index.asp?op=gotodir&vdir=\&appname=" & appname & "&basename=GDLIVROS"">" & _
	  "<img border=0 src='livros/header.gif'></a>" & _
    "</td>" & _			
    "</tr>" & _
    "<tr bgcolor='#FFFFFF' align='right'><td height=1><img src='livros/espaco.gif' height='1'></td></tr>" & _
    "<tr bgcolor='#F69844' align='right'><td height=28 class=menu>" & this.Menu & "  </td></tr>" & _
    "<tr bgcolor='#FFFFFF' align='right'><td height=1><img src='livros/espaco.gif' height='1'></td></tr>" & _
    "</table>"
End function

A variável appname é utilizada neste código no intuito de fazer com que o .gdb da aplicação LIVROS funcione também quando se tiver usando a aplicação LOJA.

OnInit

Este evento ocorre assim que uma instância da base é carregada em memória. Assim como o evento OnInit de aplicação, este evento pode ser utilizada para inicializar algumas variáveis e propriedades da base.

Sub OnInit
...
End Sub

OnInsert

Este evento é chamado antes da inserção de um registro. Este evento pode ser utilizado com a mesma idéia do evento OnEdit, só que no contexto de uma inserção. Da mesma forma, o parâmetro passado é um objeto request do LightBase Web. O exemplo abaixo mostra a utilização do evento OnInsert para guardar a data do cadastramento do registro no campo data_cadastro. 

Sub OnInsert( request )
  request.AddItem "data_cadastro", this.Base.Value( "LBWEB_DATE" )
End Sub

OnInsertDoc

Este evento ocorre sempre que o formulário de inserção for apresentado. É possível alterar o formuláio de inserção de registro mudando a propriedade Insert de campos durante este evento ou simplesmente modificando o código HTML retornado pelo método defaultInsertDoc de IBase. 

Function OnInsertDoc
  ...
End Function

OnInsertPage

Este evento ocorre sempre que a página de inserção de novos itens na aplicação for apresentada. Ele permite alterar a página de inserção de registros na área por fora do formulário de inserção. Além disso é possível, como no evento OnInsertDoc, mudar propriedades dos campos relativas a inserção antes da construção da página.

Para ilustrar o uso deste evento, utilizaremos a aplicação de LIVROS. Suponha que desejamos impedir o cadastro de novos livros sem a informação da capa. Para isso, podemos fazer com que capa seja um campo obrigatório e isto pode ser feito na definição do próprio campo. Porém, isto faria com que o campo fosse obrigatório também na edição. E por ser um campo tipo imagem implicaria em sempre adicionar um valor na edição. Assim, resolvemos mudar a propriedade "Required" do campo "capa" no evento OnInsertPage para verdadeiro e no evento OnEditPage mudar esta propriedade para falso. Apresentamos a seguir o código destes eventos. 

Function OnInsertPage
	this.Fields.Item( "capa" ).Required = True
End Function

Function OnEditPage( id, group, repet )
	this.Fields.Item( "capa" ).Required = False
End Function

OnListDoc

Este evento na montagem da página de listagem de registros, no entanto, ele permite alterar apenas a forma de apresentação de um registro no nível dos campos. 

Function OnListDoc
  ...
End Function

OnListPage

Este evento ocorre sempre que o sistema está montando a página de listagem de registros, seja o resultado de uma pesquisa, seja os registros presente em um diretório. Ele permite alterar a forma que a informação é apresentada. 

Function OnListPage
  ...
End Function

OnTagValue e OnIsTagValid

Os eventos OnTagValue e OnIsTagValid só podem ser utilizados conjuntamente. Tais eventos permitem que se inclua marcas nas páginas lbsp retornadas em algun eventos (OnDetaildoc, OnDetailPage, OnEditDoc, OnEditPage, OnListDoc, OnListPage) e as trate de maneira personalizada. Sempre que uma marca desconhecida pelo GoldenDoc e pelo LightBase Web é encontrada na página lbsp que está sendo compilada, o GoldenDoc lança tais eventos. O evento OnIsTagValid é utilizado para validar a existência do tag no nível da aplicação, para tal deve-se retornar verdadeiro/falso de acordo com a existência do tag informado no parâmetro tagname.

Caso o evento OnIsTagValid retorne falso para alguma marca, isto significará que a marca não é reconhecida pela aplicação e um erro de compilação do template será mostrado. Nos outros casos, o evento OnTagValue será lançado sempre que a marca for encontrada durante a construção da página resultante de um processo. O evento OnTagValue deve retornar então o valor que deve ser colocado no lugar da marca.

O retorno do evento OnTagValue é do tipo string. Neste evento, é possível acessar os valores dos campos da base para o registro corrente. Se a marca está entre um <%BEGINRECORD%> e um <%ENDRECORD%>, este evento será invocado a cada registro a ser processado e os dados do registro em questão poderão ser acessados através dos objetos do GoldenDoc.

Como dito anteriormente, estes eventos só fazem sentido se utilizados em conjunto e, ainda, em conjunto com outro evento do GoldenDoc que permita a modificação das páginas lbsp utilizadas pelo sistema para a apresentação dos dados das bases. Assim, utilizaremos um único exemplo para ilustrar a utilização destes eventos.

Imagine a seguinte situação: na aplicação de LIVROS, precisamos indicar os livros novos presentes na aplicação através da inclusão de um ícone ao lado do registro. Um livro deve ser considerado novo se o valor do campo ano for igual ao ano corrente. Não é possível fazer isso apenas colocando o ícone ao lado de cada registro, pois precisamos saber o ano do livro para poder tomar esta decisão. Assim, a solução que adotaremos será tratar o evento OnListDoc para introduzir um marca nossa e também utilizaremos os eventos OnIsTagValid e OnTagValue para tratar da marca em questão.

Abaixo mostramos o código utilizado para tratamento do evento OnListDoc. 

Function OnListDoc
  OnListDoc = "<%EXTRAHTML_OFF%> <%NOVOLIVRO%> " & this.defaultListDoc
End Function

O evento OnIsTagValid deve ser tratado para indicar que a tag NOVOLIVRO que foi introduzida no lbsp de listagem de livros atavés do evento acima é válida, vejamos a seguir. 

Function OnIsTagValid( tagname )
  OnIsTagValid = false
  if UCase(tagname) = "NOVOLIVRO" then
    OnIsTagValid = true
  End if
End Function

O evento OnTagValue deve ser tratado para informar o texto que deve ser utilizao para substituir a marca encontrada. Lembrando que desejamos substituir a marca NOVOLIVRO por um ícone caso seja um livro novo, veja a seguir o tratamento deste evento. 

Function OnTagValue( tagname )
  If UCase( tagname ) = "NOVOLIVRO" Then
    If CInt( this.base.Value( "ano" ) ) >= Year( Now ) Then
      OnTagValue = "<img src=livros/novo.gif>"
    End If
  End If
End Function