Exibir código-fonte para Desenvolvimento:como se faz:exibindo um campo personalizado

=== Exibindo um campo personalizado ===

Esta página contém informações gerais sobre a forma de apresentar novos campos na interface do VuFind.

// Obrigado ao Luis Diaz para ajuda na elaboração deste documento. //

===== Entendo como os campos no VuFind são apresentados =====

Toda a apresentação do VuFind são renderizados usando templates do PHP dentro de [[development:architecture:user_interface|theme]]. Os dados usados nestes templates é recuperado a partir de um [[development:plugins:record_drivers|record driver]], que é uma classe PHP com muitos métodos públicos. o record driver frequentemente recupera as informações a partir do  indíce Solr ou em um registro MARC armazenado e recuperado do índice.

No caso do Solr, dos dados dos campos armazenados no índice é disponibilizados  no record driver através de sua propriedade no campo; no caso do MARC, métodos de conveniência são fornecidos para a extração de dados. Para outros formatos de dados e disponibilidade, fontes e formato de dados internos irá variar de acordo com o desenho do [[development:howtos:connecting_a_new_external_data_source|search backend]].

===== Fluxo para adicionar um campo =====

O fluxo básico para adicionar um campo é:

  - Disponibilizar os dados para o VuFind
  - torne os dados acessíveis através do record driver
  - apresentar os dados no template apropriado

====== Disponibilizar os dados para o VuFind ======

É possível que os dados já estejam disponíveis para o VuFind. Se você está recuperando um valor a partir de um campo dentro do registro MARC armazenado, ou se você deseja exibir um campo que já é visível  em outras partes do VuFind, você pode pular esta etapa.

Se você precisa processar dados na fase de indexação em vez de carregá-lo cru no MARC, você precisará ajustar o seu [[indexing:solrmarc|SolrMarc]] configurando e/ou suas definições no schema.xml do Solr. Veja a discussão no [[indexing:adding_facets|adding facets]] para obter detalhes sobre como fazer isso.

Não se esqueça de reindexar os dados e reiniciar o Solr depois de fazer alterações como esta!

====== Torne os dados acessíveis através do record driver ======

Se você estiver exibindo um campo que já está definido dentro VuFind, você pode pular esta etapa.

Se você está adicionando totalmente um campo novo, você precisará adicionar um método getter apropriado para o record driver usado para exibir seus registros. Na situação mais comum, isto vai está em [[https://github.com/vufind-org/vufind/blob/master/module/VuFind/src/VuFind/RecordDriver/SolrMarc.php|SolrMarc]] driver, que herda a maioria de sua funcionalidade de [[https://github.com/vufind-org/vufind/blob/master/module/VuFind/src/VuFind/RecordDriver/SolrDefault.php|SolrDefault]] driver. Os métodos get existentes nestas classes deve servir como exemplos úteis para a criação de novos métodos.

Se você copiar um método existente como um modelo para o seu novo método, o detalhe mais importante a observar é o valor de retorno: certifique-se de que você devolver uma string quando se lida com um campo Solr de valor único e que você retornar um array quando lidando com um campo com valores múltiplos Solr. Isto tornará mais fácil para você lidar com dados de forma limpa no seu modelo.

Observe também que enquanto você pode simplesmente editar o record drivers existente no local, é geralmente uma melhor prática para localizar suas mudanças dentro de um módulo personalizado para facilitar futuras atualizações. Veja a página [[development:architecture:customizing_vufind|Customizing VuFind]] para maiores detalhes disto. Se estiver usando o VuFind 2.4 ou mais recente, note que [[development:code_generators|code generators]] pode automatizar a maior parte da configuração na construção de um record driver personalizado.

====== Apresentar os dados no template apropriado ======

O passo final para exibir um novo campo e torná-lo visível através de um template de exibição
O passo final para exibir um novo campo é torná-lo visível através de um modelo de exibição. Recorde-se relacionam modelos são encontrados na pasta RecordDriver do seu tema escolhido em uma pasta que corresponde ao nome da classe do driver registro. Quando VuFind escolhe um modelo para exibir, segue-se a cadeia de herança de classe '- por exemplo, se SolrMarc/core.phtml não existe, VuFind voltará a tentar SolrDefault/core.phtml, porque Solr o padrão é SolrMarc pai. Devido a este projeto, a maioria dos modelos de exibição registro de VuFind são encontrados dentro da pasta do tema RecordDriver/SolrDefault embora há muitos drivers diferentes disponíveis.

Aguns templates-chaves que você provavelmente considere para edição:

  * core.phtml - os metadados exibidos no modo de exibição de registro, independentemente no active tab
  * result-grid.phtml - um único resultado de busca, quando "grid view" está ativa
  * result-list.phtml - um único resultado de busca, quando "list view" (o modo padrão) está ativa

Deve ser possível para adicionar o novo campo para o modelo, imitando alguns dos outros códigos já presentes lá.

Tal como acontece com personalizações de código, é possível editar modelos no local, mas muitas vezes é melhor prática para criar o seu próprio tema personalizado e criar suas exibições personalizadas lá - isso vai fazer futuros upgrades mais fáceis. Veja [[development:architecture:customizing_vufind|Customizing VuFind]] para mais detalhes.

====== Exemplo passo a passo ======

//Este exemplo mostra como configurar um módulo específico, um tema personalizado e um record driver personalizado. Ele assume que você já adicionou um campo personalizado para o seu índice Solr chamado RecID -- você pode ver exemplos mais concretos de adicionar campos na página [[indexing:adding_facets|Adding Facets]]. //

1. Criar um módulo personalizado (se você não tiver feito isso)

   cd $VUFIND_HOME
   php install.php

   * No prompt "What module name would you like to use? [blank for none]" digitar o nome do seu módulo
   * Link configuration to apache’s config.d directory per the install.php directions
   * Configuração do link para o diretório config.d do apache no install.php 
   * Reinicie o apache (sudo /etc/init.d/apache2 restart)
 
2. A partir de $VUFIND_HOME digite o seguinte comando no gerador de código:

   php public/index.php generate extendservice vufind/plugin_managers/recorddriver/factories/solrmarc ModuleName

   * Você deve ver o seguinte: 

   Saved file: /usr/local/vufind/module/ModuleName/src/ModuleName/RecordDriver/SolrMarc.php
   Saved file: /usr/local/vufind/module/ModuleName/src/ModuleName/RecordDriver/Factory.php
   Successfully updated /usr/local/vufind/module/ModuleName/config/module.config.php

   * Se você receber um erro como "Class ModuleName\RecordDriver\Factory does not exist", ou se os arquivos não foram escritos, em seguida, faça o seguinte:

   export VUFIND_LOCAL_MODULES=ModuleName
   php public/index.php generate extendservice vufind/plugin_managers/recorddriver/factories/solrmarc ModuleName

3. Atualize o arquivo SolrMarc.php para adicionar um novo campo. 
  * Certifique-se a linha de namespace lê "namespace ModuleName\RecordDriver;"
  * Adicione o método getter. Veja abaixo um exemplo, mas também fazer referência ao arquivo SolrMarc.php em /module/VuFind/src/VuFind/RecordDriver/ para mais exemplos de código getter.

   Exemplo: 
   <?php
   namespace ModuleName\RecordDriver;
   class SolrMarc extends \VuFind\RecordDriver\SolrMarc
   {
    /**
     * Get the record ID of the current record.
     *
     * @return string
     */
    public function getRecordID() {
        return isset($this->fields['recID']) ?
           $this->fields['recID'] : '';
      }
   }

4. Personalize o modelo onde pretende usar esse campo, copiando os arquivos apropriados em seu tema personalizado.
   cd $VUFIND_HOME/themes
   mkdir ThemeName

  * Faça a seguinte estrutura sub-diretório: ThemeName/templates/RecordDriver/SolrDefault/
  * Coloque o seguinte conteúdo em $VUFIND_HOME/themes/ThemeName/theme.config.php:

<code>
<?php
return array(
    'extends' => 'bootstrap3'
);
</code>

  * cd $VUFIND_HOME/themes/bootstrap3/templates/RecordDriver/SolrDefault/, e copie core.phtml e result-list.phtml para os novos temas no diretório SolrDefault
  * Edite core.phtml e result-list.phtml para adicionar novos campos para exibição.

    Exemplo:
      <? $recordID = $this->driver->getRecordID(); if (!empty($recordID)): ?>
      <tr>
        <th><?=$this->transEsc('Record ID')?>: </th>
         <td property="RecID"><?=$this->escapeHtml($recordID)?></td>
       </tr>
      <? endif; ?>

  * Edite local/config/vufind/config.ini para definir o theme = ThemeName