Exibir código-fonte para Formulário de Entrada

O formulário de entrada é utilizado no processo de submissão para descrever o(s) objeto(s) digital(is) a ser(em) depositado(s). Nesse caso, é apresentado no '''DSpace/TEDE2''' como páginas com campos para preenchimento ou com opções para seleção. Essa facilidade é ajustável, por meio de edição de um arquivo no padrão ''xml'', adequando-se aos tipos de documentos contemplados na política de conteúdo. Assim, a sua configuração alinha-se a essa política, relacionando o tipo de documento com os campos necessários para sua descrição.

O formulário de entrada é composto por campos. cabe ao administrador decidir quais campos de metadados são necessários e que formatos eles terão. Dessa forma, o formulário de entrada pode ser extenso ou curto, dependendo do tipo de objeto digital a ser descrito. Por não ser configurável de forma interativa nas páginas do '''DSpace/TEDE2''', necessita de apoio da equipe de informática para isso. 

O endereço dp arquivo que permite a edição dos formulários é o '''[dspace-base]/input-forms.xml'''. Se desejar criar formulários diferentes para cada idioma do sistema, poderá ser adicionado no nome do arquivo o identificador do idioma, por exemplo: 

* '''input-forms_pt_BR.xml''' para português brasileiro ou, 

* '''input-forms_es.xml''' para espanhol. 


Pode haver mais de um tipo de formulário de entrada. Neste caso a mudança entre os dois tipos de formulário não ocorre em relação ao idioma, mas dependerá da coleção em que se realizará a submissão, e assim não se pode querer utilizar mais que um tipo de formulário de entrada em uma mesma coleção. Entretanto, na maioria dos casos um formulário bem estruturado cobre a maioria dos tipos de documentos, pois alguns 
campos são comuns a todos eles, como título ou autor, por exemplo. Caso seja necessária a criação de mais de um formulário de entrada, 

Os campos de um formulário de entrada possuem relação direta com o esquema de metadado escolhido. Por padrão, o esquema de metadados do '''DSpace/TEDE2''' é o ''Dublin Core''. Na maioria dos casos o ''Dublin Core'', com seus elementos e qualificadores, é suficiente para a descrição dos objetos digitais. Porém, se for necessária a utilização de outro esquema, deve-se primeiro criar todo o esquema dinamicamente na opção de “Gerenciar metadados” vista no capítulo anterior. 

Nem todos os elementos e qualificadores estão contemplados no formulário de entrada padrão. Se preferir apenas ajustar o formulário padrão às necessidades de descrição dos documentos, é recomendável que se conheça o esquema de metadados ''Dublin core'' para melhor ajustar o formulário às necessidades de descrição. Nesse caso, basta ajustar o formulário de entrada, criando ou retirando campos. 

Por outro lado, se necessitar criar um novo elemento ou qualificador para conter uma determinada informação utilizando a prerrogativa do ''Dublin core'' de ser um esquema de metadados mais flexível, primeiro crie o elemento ou qualificador na opção “Gerenciar metadados” visto no capítulo anterior, e depois ajuste o formulário. Esse procedimento evitará erros no momento de utilização do formulário de entrada. 

Os campos podem ter vários formatos para adequar-se ao tipo de descrição. De campos de texto curto para título ou autor, a campos extensos para descrição ou resumo. Há também campos destinados a datas, com estrutura própria para esse tipo de dado. Há os campos com listas de dados para seleção ou campos que permitem vocabulário controlado. Deve-se, no entanto, escolher o melhor tipo de campo para a descrição necessária.

Os campos também podem ser únicos ou repetíveis. Por exemplo, o campo para o título deve ser único, pois é incomum um documento com mais de um título, podendo, no entanto, ter títulos alternativos utilizando outro campo. Entretanto, o campo autor precisa ser repetível, pois é comum um documento ter mais de um autor. Da mesma forma, um campo pode ser obrigatório ou opcional, dependendo das necessidades de descrição. Assim, 
ao definir o formato do campo, define-se também essas outras características. 

Este manual não tem como objetivo explicitar a configuração do arquivo do formulário de entrada, mas orientar o administrador sobre as possibilidades oferecidas. Entretanto, essas informações podem ser úteis aos integrantes da equipe de informática, pois, apesar de não orientar quanto à forma de fazê-lo, apresenta as possibilidades, contemplando aqueles conhecimentos que devem ser compartilhados entre o administrador e a equipe de informática.

[https://github.com/wtonribeiro/TEDE-legado/blob/master/input-forms.xml Exemplo de formulário]


== Metadados ==

A descrição de  um documento no '''DSpace/TEDE2''' é possível graças à  ação conjunta de duas ferramentas: os campos descritores (metadados) e os formulários de entrada de dados. Para se ter uma lista dos campos por padrão disponíveis no sistema, basta estar logado com perfil de administrador e então acessar: '''Administrador > Configurações gerais > Registrar metadados >'''. Nesta lista, é possível observar que o padrão adotado pelo '''DSpace/TEDE2''' é o Dublin Core Qualificado, mas caso seja necessário, é possível se adicionar novos campos, ou então editá-los, ou mesmo excluí-los. E ainda possível adotar, ou criar, um novo esquema. Essas operações são de fácil manuseio, pois todas podem ser feitas por meio da interface gráfica do sistema. 

Este documento, faz restrição à orientação somente no tange a edição dos formulários de entrada, deixando ao leitor a tarefa de edição dos esquemas de metadados. É necessário alertar, no entanto, que caso o formulário faça referência a algum campo inexistente no esquema, o sistema retornará erro e impedirá a conclusão da submissão.

== Formulário de entrada ==


=== Estrutura do formulário ===
O arquivo de formulário é organizado por meio da seguinte estrutura:

''Cabeçalho'': Contém informações sobre o padrão do arquivo (''xml'') e associação de formulários à coleções específicas.

''Formulários'': É possível configurar mais de um tipo de formulário, e a diferenciação entre os diversos tipos é realizada pela tag ''<form name="traditional">'', onde “traditional” deve ser substituído pelo nome desejado para o novo formulário.

''Páginas'': Cada página representa uma nova etapa de descrição.

''Campos'': São, de fato, a porta de entrada da informação, e se conectada a um, ou conjuntos de metadados;

''Valores padrão de preenchimento'': São os valores que aparecerão nas listas, ''radio buttons'', caixas de seleção, etc. 


=== Estrutura dos campos ===

Os campos são declarados como tags na estrutura do arquivo de formulários. Exemplo de entrada para :
        	<field>
        	<dc-schema>dc</dc-schema>
        	<dc-element>type</dc-element>
         	<dc-qualifier></dc-qualifier>
         	<repeatable>false</repeatable>
         	<label>Tipo de documento</label>
         	<input-type value-pairs-name="common_types">dropdown</input-type>
         	<hint>Selecione o tipo de documento.</hint>
         	<required>Este é um campo obrigatório</required> 
        	</field>

Descrição de exemplo para Autor ('''dc.contributor.author''')

{| border=1

! width=30% | Tag !! width=40% | Comentário 
|-
|'''<dc-schema>dc</dc-schema>''' || dc é a sigla do esquema de metadados que se está adotando, neste exemplo o ''Dublin Cor''e.
|-
| '''<dc-element>contributor</dc-element>''' ||''contributor'' é o elemento do esquema dc.
|-
| '''<dc-qualifier>author</dc-qualifier>''' || ''author'' qualificador do elemento ''contributor''.
|-
| '''<repeatable>false</repeatable>''' || O valor ''false'' determina que o campo não será repetitivo (cada registro não terá mais que um valor para ''dc.contributor.author'').
|-
| '''<label>Autor</label>''' || Texto descritivo do campo
|-
| '''<input-type>name</input-type>''' || Name é tipo do campo, que será ajustado para descrição no formato de citação: Sobrenome, Nome.
|-
| '''<hint>Informe o nome do Autor.</hint>''' || Frase que aparece logo abaixo do campo.
|-
| '''<required>Este é um campo obrigatório</required>''' || Determina que o campo será de preenchimento obrigatório. Se nenhum valor for colocado, o preenchimento se torna facultativo.
|-
|}


=== Tipos dos campos ===

Os tipos de campos devem ser definidos nas chaves '''<input-type>''Tipo de campo''</input-type>'''. Os tipos de campos são:


'''<input-type>'''''onebox'''''</input-type>''' – Um campo único para entrada de texto simples.

'''<input-type>'''''twobox'''''</input-type>''' – Um par de campos de texto simples.

'''<input-type>'''''textarea'''''</input-type>''' – Um campo de texto com várias linhas, para usar nas descrições que requerem várias linhas como, por exemplo: resumo.

'''<input-type>'''''name'''''</input-type>''' – Para identificação de pessoas, será salvo no formato ‘Sobrenome’, ‘Nome’

'''<input-type>'''''date'''''</input-type>''' – Data. Necessita ao menos que o ano seja preenchido.

'''<input-type>'''''series'''''</input-type>''' – para valores de fascículos/número. São salvos em valores separados por ponto e vírgula.

'''<input-type>'''''dropdown'''''</input-type>''' – Escolha do valhor em uma lista “drop-down”. Esta lista deve estar definida em ''form-value-pairs'' e o nome deve remeter a essa lista.

'''<input-type>'''''qualdrop_value'''''</input-type>''' – Usado para listar qualificadores para o campo. É necessário que estes valores estejam em uma lista definida em ''form-value-pairs''.

'''<input-type>'''''list'''''</input-type>''' – Campo de escolha de valores por checkbox ou radio button list. Se for repetitivo, uma lista de checkboxes é exibida. Se não for, uma lista de radio buttons será exibida. É necessário que estes valores estejam em uma lista definida em ''form-value-pairs''.


=== Campos controlados ===

A seleção de valores pré-estabelecidos para um determinado campo pode ser efetuada de diversas formas. A saber: definição de ''valores padrão de preenchimento'' (como listas e caixas de seleção), criação de um ''vocabulário controlado'', ou mesmo utilização de um ''controle de autoridade''.  As duas primeiras opções serão objetos deste documento, enquanto que a terceira será abordada outro texto, pois sua configuração exige o uso de outros elementos, externos à edição de formulários.


=== Valores padrão de preenchimento ===

Ao definir o tipo do campo, caso se escolha os padrões '''dropdown, qualdrop_value''' ou '''list''', é necessário se fazer referencia à lista de valores do qual se fará escolha na hora da submissão. Essa lista é declarada no final do arquivo '''imput_forms.xml''', e será incluída dentro de  '''<form-value-pairs> ...  </form-value-pairs>'''. Um exemplo deste tipo de técnica é utilizada, por exemplo, no campo tipo de documento (dc.type):
<pre>
<field>
     <dc-schema>dc</dc-schema>
     <dc-element>type</dc-element>
     <dc-qualifier></dc-qualifier>
     <repeatable>false</repeatable>
     <label>Tipo de documento</label>
     <input-type value-pairs-name="common_types">dropdown</input-type>
     <hint>Selecione o tipo de documento.</hint>
     <required></required> 
</field>
   ....
<value-pairs value-pairs-name="common_types" dc-term="type">
   <pair>
      <displayed-value>Artigo</displayed-value>
       		<stored-value>artigo</stored-value>
   </pair>
   <pair>
      <displayed-value>Tese</displayed-value>
      <stored-value>tese</stored-value>
   </pair>
   <pair>
     <displayed-value>Dissertação</displayed-value>
     <stored-value>dissertação</stored-value>
   </pair>
</value-pairs>
</pre>
Os valores que aparecem na tag '''<displayed-value>''' são aqueles que serão exibidos como opções de seleção na tela, enquanto que os '''<stored-value>''' serão os efetivamente armazenados no metadado ''dc.type''

== Vocabulários controlados ==

Os vocabulários controlados no '''DSpace/TEDE2''' são conjuntos de termos organizados em uma estrutura relacional (Kobayashi, 2008) que fornecem, de forma padronizada, os termos para utilização na submissão e indiretamente auxiliam nas buscas. Assim, servem para facilitar o preenchimento de determinados campos e na recuperação de documentos. 

A utilização de vocabulários controlados foi disponibilizado no '''DSpace/TEDE2''' a partir da versão 1.4.x. Entretanto, até a versão 1.6.0 os vocabulários controlados estão disponíveis, de forma padrão, apenas para a interface JSPUI, que mantém a compatibilidade com as versões mais antigas pois possui a mesma tecnologia de construção. 

Para o '''DSpace/TEDE2''', o vocabulário controlado pode ser utilizado em vários campos, ou seja, pode-se ter mais que um campo com vocabulário controlado. Sua utilização dá-se por meio de janelas pop up (páginas que abrem ao clicar uma opção hipertextual). As janelas do vocabulário controlado apresentam os termos organizados hierarquicamente em formato de árvores cujos termos, ao serem clicados, são transferidos para os campos relacionados. 

A implementação dos vocabulários controlados geralmente é feita em duas etapas: a criação do arquivo do vocabulário controlado e sua adição ao formulário de entrada. Essas etapas não são sequenciais, mas devem ser efetuadas para a plena utilização dessa facilidade.

O arquivo do vocabulário controlado possui um formato XML, que possui uma estrutura própria para organização hierárquica. Deve-se criar um arquivo para cada campo de metadado a usar o vocabulário controlado. Assegure-se da boa formação da estrutura XML para evitar erros.

O nome do arquivo de vocabulário controlado deve ser indicado na definição do campo onde ele será utilizado, no formulário de entrada. Deve-se notar que, mesmo que coloque o nome do arquivo no formulário de entrada, na interface XMUI não haverá a chamada para esse vocabulário, somente na interface JSPUI. 


=== Configurando vocabulários controlados ===
Um bom exemplo são as Áreas de Conhecimento do CNPq. Há a necessidade de classificação entre áreas e subáreas, e isso gera a necessidade de uma ordem taxonômica. Para ativar o controle via um vocabulário em um campo, é necessário que se explicite o nome do vocabulário que o controlará na tag ''<vocabulary>'':
<pre>
<field>
  <dc-schema>dc</dc-schema>
     …  
  <vocabulary>cnpq</vocabulary>
</field>
</pre>
Ela fará busca pelo arquivo de vocabulário ''cnpq.xml'', que deverá estar dentro da pasta '''[dspace-base]/config/controlled-vocabularies/'''. Este arquivo será organizado de forma a criar uma taxonomia entre os termos que lá se encontram. Segue exemplo:
<pre>
<node id="cnpq" label="CNPq">
  <isComposedBy>
    <node id="1" label="Ciências Exatas e da Terra">
      <isComposedBy>
        <node id="101" label="Matemática">
        </node>
    <node id="102" label="Probabilidade e Estatística">
    </node>
        …
     </node>
  </isComposedBy>
</node>		
<node id="2" label="Ciências Biológicas">
  <isComposedBy>
    …
  </isComposedBy>
</node>
  ….
  </isComposedBy>
</node>
</pre>

=== Ativando vocabulários controlados ===
Com a conclusão e codificação do seu vocabulário controlado (''cnpq.xml'' foi usado como exemplo) e te-lo transferido para a pasta informada acima, seu vocabulário não estará liberado ainda. Faz-se necessário a configuração do arquivo ''dspace.cfg'' presente na pasta '''[dspace-base]/config'''. 
Ao abrir o arquivo, localize o código abaixo:

         #### Controlled Vocabulary Settings #####
         
         # Enable or disable the controlled vocabulary add-on
         # Warning: this feature is not compatible with WAI (it requires javascript to function)
         #
         #webui.controlledvocabulary.enable = true

É necessário somente deletar a # (chave) presente na última linha:
         webui.controlledvocabulary.enable = true

Com isso seu vocabulário estará liberado para utilização.

[https://github.com/ibict-br/TEDE/blob/dspace-4_x/dspace/config/controlled-vocabularies/cnpq.xml Exemplo de vocabulário (áreas do conhecimento do CNPq)]

== Formulários dinâmicos ==

A configuração de formulários dinâmicos se dá por quatro tipos de técnicas diferentes: a modularização do arquivo de formulários de acordo com a língua escolhida, a particularização de um tipo de formulário para uma, ou um grupo de coleções, a exibição ou ocultação de um campo conforme o preenchimento do metadado ''dc.type'', e a exibição exclusiva de campos na etapa de revisão dos metadados. A seguir é exibido um passo-a-passo sobre o modo de implementação de cada uma dessas técnicas.


=== Modularização do formulário de acordo com a língua escolhida ===

O sistema adota por padrão o arquivo '''[dspace-base]/config/''input-forms.xml''''' como possuidor de todos as informações de formulários de entrada, de forma independente à língua corrente. No entanto, se o suporte multilínguas estiver configurado, é possível realizar configuração  de formulário para cada opção de idioma. 

Nesse contexto, ''input-forms.xml'' corresponderá às configurações de língua inglesa (en), e poderão ser criados quantos arquivos forem necessários de formulários, um para cada pacote de língula instalado. Os arquivos devem estar na pasta  '''[dspace-base]/config''', e receberão o seguinte nome ''input_forms_{xxx}.xml'', onde ''{xxx}'' representa o código da lingua de acordo com o padrão ''ISO 639-1''. Exemplos:
<pre>
*input-forms_pt_BR.xml para o português brasileiro; 
*input-forms_es.xml para o espanhol;
*input-forms_de.xml para o alemão.
</pre>
Na inteface ''XMLUI'' a seleção de língua é realizada de forma automática, conforme a região (país) em que se faz acesso ao sistema, e os idiomas configurados no browser. E na ''JSPUI'' é possível adcionar um menu que realiza a mudança entre os diversos idiomas disponíveis. O  arquivo de formulário corrente será sempre o corresponte a língua selecionada.

=== Particularização de formulário a um grupo de coleções ===

Na estrutura do arquivo de formulários, dentro da tag '''<form-definitions>''' estão os possíveis tipos de formulários configurados e seus nomes são declarados pela tag '''<form name="example">''' onde example representa um exemplo de nome para dado um tipo de formulário configurado.  Então, como exemplo, considera-se um contexto em que há dois formulários configurados, um chamado traditional, e o outro example, deve-se editar o cabeçalho do arquivo de formularios, na tag '''<form-map>''':

  <form-map>
   <name-map collection-handle="default" form-name="traditional" />
   <name-map collection-handle="123/1" form-name="example" />
 </form-map>

*Utilizando-se ''collection-handle="default"'' define-se o formulário que será utilizado para qualquer coleção, exceto para as que seguem identificadas com formulários específcos;

*A declaração ''collection-handle="123/1" form-name="example"'' estabelece que a coleção cujo handle é 123/1 fara uso somente do formulário example

=== Exibição de campo condicionada ao dc.type ===

A exibição de determinados campos pode ser condicionada, durante à submissão, ao valor preenchido para o metadado ''dc.type''. Recomenda-se que esteja presente em um campo do tipo dropdown logo no início da primeira página. Na página seguinte, dando sequência ao preenchimento, só aparecerão os campos condicionados ao valor obtido anteriormente no ''dc.type''. Se a tag  '''<type-bind>''' não for incluída no campo ele aparecerá para todos os tipos de documento. Exemplo:
<pre>
<page number="1">
  <field>
    <dc-schema>dc</dc-schema>
    <dc-element>type</dc-element>
    <dc-qualifier></dc-qualifier>
    <repeatable>false</repeatable>
    <label>Tipo de documento</label>
    <input-type value-pairs-name="common_types">dropdown</input-type>
    <hint>Selecione o tipo de documento.</hint>
    <required></required> 
  </field>
</page>
<page number="2">
  <field>
    <dc-schema>dc</dc-schema>
    <dc-element>contributor</dc-element>
    <dc-qualifier>author</dc-qualifier>
    <repeatable>false</repeatable>
    <label>Autor</label>
    <input-type>name</input-type>
    <hint>Entre com o nome do autor.</hint>
    <required>Este é um campo obrigatório</required> 
       	 </field>
         <field>
    <dc-schema>dc</dc-schema>
    <dc-element>contributor</dc-element>
    <dc-qualifier>advisor</dc-qualifier>
    <type-bind>tese, dissertação</type-bind>
    <repeatable>false</repeatable>
    <label>Orientador</label>
    <input-type>name</input-type>
    <hint>Entre com o nome do orientador.</hint>
    <required>Este é um campo obrigatório</required> 
  </field>
   …
   ...
<value-pairs value-pairs-name="common_types" dc-term="type">
  <pair>
     <displayed-value>Artigo</displayed-value>
     <stored-value>artigo</stored-value>
  </pair>
  <pair>
     <displayed-value>Tese</displayed-value>
     <stored-value>tese</stored-value>
  </pair>
  <pair>
     <displayed-value>Dissertação</displayed-value>
     <stored-value>dissertação</stored-value>
  </pair>
</value-pairs>
</pre>

=== Exibição de campos somente na etapa de revisão de metadados  ===

Caso uma dada coleção possua uma etapa de revisão de metadados, é possível incluir uma tag para marcar os campos que aparecerão somente nesta fase, mesmo aqueles de caráter obrigatório. Segue exemplo:

       <field>
        <dc-schema>dc</dc-schema>
       …
         <hint> … </hint>   
         <visibility>workflow</visibility>
         <required>Este é um campo obrigatório.</required>
       </field>