...criar um novo elemento para uso no WIzard | Início Anterior Próximo

...criar um novo elemento para uso no WIzard

A ferramenta WIzard do WebIntegrator oferece a oportunidade do desenvolvedor poder acrescentar novos elementos a serem usados numa página WSP criados pelo próprio desenvolvedor. Esses elementos não são nada mais além do que trechos de código HTML que serão incluídos na página onde algumas propriedades poderão ser preenchidas de acordo com os valores que elas foram definidas através do WIzard.
Um elemento criado pelo desenvolvedor poderá estar disponível para todos os projetos que fazem parte de uma instalação do WebIntegrator ou apenas para um projeto específico e além do mais eles também podem estar associados a um tipo específico de dado de um dos bancos de dados do projeto, desta maneira sempre que o WIzard montar uma página baseada em um Objeto de pré-página ele tentará usar aqueles componentes que estiverem associados a um tipo específico de acordo com os valores do Objeto.
Como um exemplo inicial tente definir um elemento que servirá como entrada para valores de data dividido em três campos separado pelo símbolo da barra (/) onde um dos campos indica o dia, o outro o mês e o última campo indicando o ano. Para isso, acesse o WIzard e na janela de Propriedades clique no rótulo do campo Tipo. Na nova janela que se abre digite o nome que o componente terá no campo Nome. O código-fonte desse elemento pode ser algo semelhante com o que se segue logo abaixo:

<table> <tr> <td nowrap>Data</td> <td nowrap><input type="text" name="tmp.data.dia" size="2" value="|tmp.data.dia|">/ <input size="2" type="text" name="tmp.data.mes" value="|tmp.data.mes|">/ <input type="text" size="4" name="tmp.data.ano" value="|tmp.data.ano|"></td> </tr> </table>

Se o elemento for salvo com a opção Global marcada ele estará disponível para todos os projetos do WebIntegrator e no campo Tipo da janela de Propriedades seu nome virá precedido do símbolo $, caso contrário o elemento apenas estará disponível no projeto em que ele foi criado e no campo Tipo seu nome virá precedido do símbolo #.
O elemento acima ilustra como pode ser o código-fonte de um elemento porém ele ainda não oferece a oportunidade do desenvolvedor poder definir certos valores em tempo de design da página. Para acrescentar essa característica basta fazer referência a variáveis que irão fazer parte do ambiente do WIzard para que o elemento possa ser configurado de acordo com o que o desenvolvedor queira.
Para criar variáveis no ambiente do WIzard basta que no código-fonte do elemento o desenvolvedor referencie variáveis que comecem com o prefixo wiz., o complemento do nome da variável servirá como o nome da propriedade que será exibida na janele de Propriedades do WIzard. A sintaxe a ser usada é a seguinte:
|wiz.<nome-da-propriedade>|
Como exemplo altere o código-fonte do elemento digitado acima para que o rótulo do campo possa ser digitado pelo desenvolvedor em tempo de design da página. O código-fonte pode ser o que segue abaixo:

<table> <tr> <td nowrap>|wiz.Rotulo|</td> <td nowrap><input type="text" size="|wiz.TamCampoDia=2|" name="tmp.data.dia" value="|tmp.data.dia|">/ <input type="text" size="|wiz.TamCampoMes=2|" name="tmp.data.mes" value="|tmp.data.mes|">/ <input type="text" size="|wiz.TamCampoAno=4|" name="tmp.data.ano" value="|tmp.data.ano|"></td> </tr> </table>

A alteração feita acima faz com que o elemento possua agora uma propriedade chamada Rótulo que estará disponível para ser configurada através da janela de propriedade do WIzard quando um desenvolvedor fizer uso desse elemento numa página WSP.
Durante a definição de uma propriedade o desenvolvedor também poderá definir algum valor padrão que elá irá assumir. Para isso basta que na definição da propriedade no código-fonte do elemento o desenvolvedor atribua esse valor usando a seguinte sintaxe:
|wiz.<nome-da-propriedade>=<valor-padrão>|
Para ilustar essa possibilidade altere novamente o código-fonte do elemento exemplificado aqui oferecendo agora a chance do desenvolvedor poder definir qual o tamanho que os campos de entrada de dados terão mas já tendo eles valores pré-configurados.

<table> <tr> <td nowrap>|wiz.Rotulo|</td> <td nowrap><input type="text" size="|wiz.TamCampoDia=2|" name="tmp.data.dia" value="|tmp.data.dia|">/ <input type="text" size="|wiz.TamCampoMes=2|" name="tmp.data.mes" value="|tmp.data.mes|">/ <input type="text" size="|wiz.TamCampoAno=4|" name="tmp.data.ano" value="|tmp.data.ano|"></td> </tr> </table>

O elemento representado pelo código-fonte acima possui agora quatro propriedades que podem ser configuradas pelo WIzard: Rotulo, TamCampoDia, TamCampoMes e TamCampoAno, sendo que as três últimas propriedades, respectivamente, já possuem valores pré-configurados.
A princípio as propriedades de um elemento quando são exibidas na janela de Propriedades do WIzard estão ordenadas alfabeticamente em ordem crescente de acordo com o nome da propriedade, mas o desenvolvedor poderá definir a ordem na qual as propriedades irão aparecer no WIzard bastando que após o prefixo wiz ele informe entre sinais de colchetes a sequência que a propriedade irá assumir. A sintaxe é a seguinte:
|wiz[<sequência>].<nome-da-propriedade>|
O código-fonte abaixo altera novamente o elemento para que se possa definir a sequência que as propriedades irão aparecer no WIzard.

<table> <tr> <td nowrap>|wiz[1].Rotulo|</td> <td nowrap><input type="text" size="|wiz[2].TamCampoDia=2|" name="tmp.data.dia" value="|tmp.data.dia|">/ <input type="text" size="|wiz[3].TamCampoMes=2|" name="tmp.data.mes" value="|tmp.data.mes|">/ <input type="text" size="|wiz[4].TamCampoAno=4|" name="tmp.data.ano" value="|tmp.data.ano|"></td> </tr> </table>

Uma outra possibilidade que pode ser feita para configurar qual valor uma determinada propriedade pode ter é o desenvolvedor poder especificar um determinado grupo de valores que ela poderá ter. Para isso basta que o desenvolvedor liste os possíveis valores da propriedade separados por vírgula definindo-os como valores-padrões dela. A sintaxe é a seguinte:
|wiz.<nome-da-propriedade>.combo=<valor#1>[,<valor#2>,...]|
Note a presença do sufixo combo, é ele que indica ao WIzard que essa propriedade possui um grupo de valores e que os mesmos serão exibidos numa combo-box limitando assim as opções de escolha que o desenvolvedor da página poderá ter. Caso queira o desenvolvedor também poderá indicar qual dos valores possíveis será o valor-padrão bastando que para isso delimite o valor entre os sinais de chaves. Como exemplo altere o código-fonte do elemento acrescentando a propriedade de poder alinhar verticalmente através dos valores bottom, middle ou top.

<table> <tr> <td nowrap style="vertical-align: |wiz.AlinhamentoVertical.combo={bottom},middle,top|;">|wiz[1].Rotulo|</td> <td nowrap><input type="text" size="|wiz[2].TamCampoDia=2|" name="tmp.data.dia" value="|tmp.data.dia|">/ <input type="text" size="|wiz[3].TamCampoMes=2|" name="tmp.data.mes" value="|tmp.data.mes|">/ <input type="text" size="|wiz[4].TamCampoAno=4|" name="tmp.data.ano" value="|tmp.data.ano|"></td> </tr> </table>

O desenvolvedor ainda poderá atribuir a cada um dos valores da combo um texto a fim de torná-los mais explicativos, para isso coloca-se o texto que deverá estar associado seguido do valor entre os sinais de [ e ]. A funcionalidade dos sinais de chaves também vale aqui, ou seja, delimitando um par texto-valor entre chaves esse será o valor defaul do componente.
Alterando o código-fonte do elemento para que ao invés de exibir os valores bottom, middle e top sejam exibidos os textos Abaixo, Meio e Acima ficaria assim:

<table> <tr> <td nowrap style="vertical-align: |wiz.AlinhamentoVertical.combo={Abaixo[bottom]},Meio[middle],Acima[top]|;">|wiz[1].Rotulo|</td> <td nowrap><input type="text" size="|wiz[2].TamCampoDia=2|" name="tmp.data.dia" value="|tmp.data.dia|">/ <input type="text" size="|wiz[3].TamCampoMes=2|" name="tmp.data.mes" value="|tmp.data.mes|">/ <input type="text" size="|wiz[4].TamCampoAno=4|" name="tmp.data.ano" value="|tmp.data.ano|"></td> </tr> </table>

Além das combos de valores que podem ser definidas pelo próprio desenvolvedor também poderão ser feitas referencias às combos do próprio WIzard que listam as classes CSS e as funções JavaScript disponíveis para uma página.
Para referenciar a combo com a listagem das classes CSS disponíveis utilize a seguinte sintaxe:
|wiz.<nome-da-propriedade>.combo=wiz.CSSCombo|
Para fazer referência à combo que lista as funções JavaScript disponíveis para uma página use a sintaxe a seguie:
|wiz.<nome-da-propriedade>.combo=wiz.JSCombo|
Essas combos também suportam a funcionalidade de definição de um valor padrão já vir selecionado. Para isso basta colocar o valor que se deseje vir selecionado entre chaves logo após a referência a combo. A sintaxe ficaria assim:
|wiz.<nome-da-propriedade>.combo=wiz.CSSCombo|wizJSCombo[{valor-padrão}]|
Além da possibilidade de referenciar as combos de CSS e funções JavaScript disponíveis pelo WIzard o desenvolvedor poderá referenciar as variáveis wiz.{name}, wiz.{label}, wiz.{size} e wiz.{value} para, respectivamente, recuperarem o nome que foi definido para esse componente na página, o rótulo que foi dado à coluna, o tamanho do campo da coluna e o valor padrão que essa coluna possui. As três últimas variáveis só terão utilidades com elementos do WIzard que estejam vinculados com algum tipo de dado de banco de dados pois os mesmos poderão ser usados para recuperar informações de uma coluna de uma tabela do banco.
Um outro recurso que pode ser adicionado aos componentes é ofercer ao desenvolvedor que irá utilizá-los uma dica (hint) do que cada uma das propriedades faz. Para definir o texto da dica das propriedades de um componente basta colocar dentro de um comentário HTML, no próprio código-fonte do componente, as propriedades com o texto da dica. Tomando como exemplo o componente aqui desenvolvido, a declaração dos textos das dicas ficaria assim:

<!-- |wiztitle.AlinhamentoVertical=Alinhamento vertical do campo.| |wiztitle.Rotulo=O texto do rótulo.| |wiztitle.TamCampoDia=Tamanho do campo dia.| |wiztitle.TamCampoMes=Tamanho do campo mês.| |wiztitle.TamCampoAno=Tamanho do campo ano.| --> <table> <tr> <td nowrap style="vertical-align: |wiz.AlinhamentoVertical.combo={Abaixo[bottom]},Meio[middle],Acima[top]|;">|wiz[1].Rotulo|</td> <td nowrap><input type="text" size="|wiz[2].TamCampoDia=2|" name="tmp.data.dia" value="|tmp.data.dia|">/ <input type="text" size="|wiz[3].TamCampoMes=2|" name="tmp.data.mes" value="|tmp.data.mes|">/ <input type="text" size="|wiz[4].TamCampoAno=4|" name="tmp.data.ano" value="|tmp.data.ano|"></td> </tr> </table>

Para desassociar um componente de um tipo de dados no banco o desenvolvedor deve selecionar o componente, com a tecla <ctrl> apertada desmarcar o tipo associado e gravar a alteração.