Search by

opencontent / occustomfind-ls

Opencontent

Opencontent Custom Find

Package info

github.com/OpencontentCoop/occustomfind

Type:ezpublish-legacy-extension

pkg:composer/opencontent/occustomfind-ls

Statistics

Installs: 6 180

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0


README

L'estensione permette di indicizzare in solr contenuti custom che non sono eZContentObject. E' utile per creare visualizzazioni ed effettuare ricerche su tabelle esterne.

Installation

Abilita l'estensione. Rigenera gli autoloads. Pulisci la cache.

Esempio di utilizzo

Si vuole, ad esempio, indicizzare un elenco telefonico che si possiede in un file csv e che non si intende importare come ogggetti ez ma i cui si vuole poter effettuare delle ricerche.

Abilitare il repository in occustomfind.ini.append.php del tuo siteaccess o di override

Si abilita inserendo identificatore e classe php del repository.

[Settings]
AvailableRepositories[elenco_telefonico]=ElencoTelefonicoSearchableRepository

Prima di creare il repository creiamo la classe che rappresenta un elemento dell'elenco telefonico

Creare la classe ElencoTelefonicoSearchableObject

La classe implementa OCCustomSearchableObjectInterface ed è la rappresentazione di un elemento dell'elenco telefonico

class ElencoTelefonicoSearchableObject implements OCCustomSearchableObjectInterface
{
    private $id;
    private $nome;
    private $cognome;
    private $numeriDiTelefono;
    private $note;

    /**
     * Il costruttore è liberamente definibile perché l'interfaccia non lo contempla.
     *
     * @param $id
     * @param $nome
     * @param $cognome
     * @param $numeriDiTelefono
     * @param $note
     */
    public function __construct($id, $nome, $cognome, $numeriDiTelefono, $note)
    {
        $this->nome = $nome;
        $this->cognome = $cognome;
        $this->numeriDiTelefono = $numeriDiTelefono;
        $this->note = $note;
    }

    /**
     * Questo meteodo deve resituire una stringa (bada bene non un numero) che identifica il documento univocamente in solr
     *
     * @return string
     */
    public function getGuid()
    {
        return return 'elenco-telefonico-' . $this->id;
    }

    /**
     * Questo metodo serve a definire i campi che solr deve indicizzare
     * Deve resituire un array di OCCustomSearchableFieldInterface per comodità conviene usare OCCustomSearchableField
     *
     * OCCustomSearchableField::create è una scorciatoia per
     * $field = new OCCustomSearchableField;
     * $field->setName($name)->setType($type)->isMultiValue($multiValue);
     *
     * @return OCCustomSearchableFieldInterface[]
     */
    public static function getFields()
    {
        return array(
            OCCustomSearchableField::create('id', 'int'),

            OCCustomSearchableField::create('cognome', 'string'),

            OCCustomSearchableField::create('nome', 'text'),

            // scorciatoia per isMultiValue vedi OCCustomSearchableField::setType
            OCCustomSearchableField::create('numeriDiTelefono', 'string[]'),

            OCCustomSearchableField::create('note', 'text'),
        );
    }

    /**
     * Restituisce il valore del campo presente in $field
     *
     * @param OCCustomSearchableFieldInterface $field
     *
     * @return mixed
     */
    public function getFieldValue(OCCustomSearchableFieldInterface $field)
    {
        if ($field->getName() == 'id'){
            return $this->id;

        }elseif ($field->getName() == 'cognome') {
            return $this->cognome;

        }elseif ($field->getName() == 'nome') {
            return $this->nome;

        }elseif ($field->getName() == 'numeriDiTelefono') {
            return $this->numeriDiTelefono;

        }elseif ($field->getName() == 'note') {
            return $this->note;
        }

        return null;
    }

    /**
     * Restiruisce la rappresentazione dell'oggetto come array
     *
     * @return array
     */
    public function toArray()
    {
        return array(
            'id' => $this->id,
            'cognome' => $this->cognome,
            'nome' => $this->nome,
            'numeriDiTelefono' => $this->numeriDiTelefono,
            'note' => $this->note,
        );
    }

    /**
     * Crea l'oggetto a partire da un array
     *
     * @param $array
     *
     * @return ElencoTelefonicoSearchableObject
     */
    public static function fromArray($array)
    {
        extract($array);
        return new ElencoTelefonicoSearchableObject($id, $nome, $cognome, $numeriDiTelefono, $note);
    }

}

Tuttavia se si ha già una rappresentazione dell'oggetto in array chiave -> valore è possibile usare la classe astratta OCCustomSearchableObjectAbstract Il risultato sarà più veloce

class ElencoTelefonicoSearchableObject extends OCCustomSearchableObjectAbstract
{

    public function getGuid()
    {
        return 'elenco-telefonico-' . $this->attributes['id'];
    }

    public static function getFields()
    {
        return array(
            OCCustomSearchableField::create('id', 'int'),
            OCCustomSearchableField::create('cognome', 'string'),
            OCCustomSearchableField::create('nome', 'text'),
            OCCustomSearchableField::create('numeriDiTelefono', 'string[]'),
            OCCustomSearchableField::create('note', 'text'),
        );
    }
}

Creare la classe ElencoTelefonicoSearchableRepository

La classe deve implemetare l'interfaccia OCCustomSearchableRepositoryInterface, ma tutto il lavoro sporco lo fa già la classe OCCustomSearchableRepositoryAbstract quindi per non rifare cose conviene estendere quest'ultima ma anche darne un'occhiata al codice...

class ElencoTelefonicoSearchableRepository extends OCCustomSearchableRepositoryAbstract
{
    private $csvFile;

    private $csvRows;

    /**
     * Nel costruttore salvo il nome del file csv da usare
     * Questo è solo un esempio, immagina che il nome del file csv venga caricato tramite ini
     * Tuttavia il costruttore non può avere argomenti (non abbiamo DependyInjection qui...)
     */
    public function __construct()
    {
        $this->csvFile = 'elenco_telefonico.csv';
    }

    /**
     * Parsa il file e restituisce le righe
     * @return array
     */
    private function getCsvRows()
    {
        if ($this->csvRows === null) {
            // il metodo parseFile deve parsare il file e restuire un array di righe
            // in questo esempio non è implementato
            $this->csvRows = $this->parseFile($this->csvFile);
        }

        return $this->csvRows;
    }

    /**
     * Questo metodo deve restituire la stringa dell'identificativo del repository, meglio usare quello definito nella chiave dell'ini
     */
    public function getIdentifier()
    {
        return 'elenco_telefonico';
    }

    /**
     * Questo campo deve restituire il FQCN della classe che si vuole indicizzare (creata sopra)
     */
    public function availableForClass()
    {
        return ElencoTelefonicoSearchableObject::class;
    }

    /**
     * Ritorna il numero totale di oggetti indicizzabili
     * Vedi il file bin/php/updatecustomsearchindex.php
     */
    public function countSearchableObjects()
    {
        return count($this->getCsvRows());
    }

    /**
     * Restiruisce un array di ElencoTelefonicoSearchableObject
     * Vedi il file bin/php/updatecustomsearchindex.php
     *
     * Il repository deve essere paginato: in questo esempio viene simulata la paginazione
     *
     * I metodi richiamati non sono implemetati
     *
     * @param int $limit
     * @param int $offset
     *
     * @return ElencoTelefonicoSearchableObject[]
     */
    public function fetchSearchableObjectList($limit, $offset)
    {
        $data = array();
        foreach($this->getCsvRows() as $index => $row) {

            if ($index < $offset){
                continue;
            }

            if (count($data) == $limit) {
                break;
            }

            $data[] = new ElencoTelefonicoSearchableObject(
                $this->getIdFromRow($row),
                $this->getNomeFromRow($row),
                $this->getCognomeFromRow($row),
                $this->getNumeriDiTelefonoFromRow($row),
                $this->getNoteFromRow($row)
            );

            // se invece usiamo l'approccio ad array si farà qualcosa di simile
            // $data[] = new ElencoTelefonicoSearchableObject($this->getArrayFromRow($row));
        }

        return $data;
    }

}

Indicizzare il repository da script

php extension/occustomfind/bin/php/updatecustomsearchindex.php -sbackend --repository=elenco_telefonico

Eseguire una ricerca

Per eseguire una ricerca da php occorre usare il metodo find del repository a cui passare un oggetto di classe OCCustomSearchParameters

Il risultato è un array in cui valori sono:

  • totalCount il totale di tutti i ElencoTelefonicoSearchableObject contemplati dalla ricerca
  • searchHits un array di ElencoTelefonicoSearchableObject
  • facets un array con chiave il campo e valore l'hash nome=>conteggio
$parameters = OCCustomSearchParameters::instance()

    // la ricerca libera funziona sui campi di tipo text, se sono string occorre cercare per tutta la stringa
    ->setQuery('amico di Topolino')

    // i filtri accettano array o array di array come i filters di eZFind
    // i nomi dei campi sono quelli definiti nel ElencoTelefonicoSearchableObject::getFields
    ->setFilters(array(
        array(
            'and',
            array('nome' => 'Paolino'),
            array('cognome' => 'Paperino')
        )
    ))

    // anche nelle faccette come nei filtri i nomi dei campi sono quelli definiti nel ElencoTelefonicoSearchableObject::getFields
    ->setFacets(array(array('field' => 'cognome')))

    // ordinamento
    // come sopra per i nomi dei campi
    ->setSort(array('cognome' => 'asc', 'nome' => 'asc'))

    // limite
    ->setLimit(10)

    // offset
    ->setOffset(0);

$repository = new ElencoTelefonicoSearchableRepository();
$result = $repository->find($parameters);

Per eseguire una ricerca via http occorre usare il modulo customfind, un po' limitato perché al momento non sono gestiti i fitri con 'or'

http://www.example.com/debug/customfind/elenco_telefonico?query=amico di Topolino&filters[nome]=Paolino&filters[cognome]=Paperino&facets[]=cognome&sort[cognome]=asc&sort[nome]=asc&limit10&offset=0

Per re-indicizzare il repository da script

php extension/occustomfind/bin/php/updatecustomsearchindex.php -sbackend --repository=elenco_telefonico --clean

Per svuotare il repository da script

php extension/occustomfind/bin/php/trucate.php -sbackend --repository=elenco_telefonico

Per indicizzare tutti i repository

php extension/occustomfind/bin/php/updatecustomsearchindex.php -sbackend --clean

Per re-indicizzare tutti i repository

php extension/occustomfind/bin/php/updatecustomsearchindex.php -sbackend --clean

Per svuotare tutti i repository

php extension/occustomfind/bin/php/truncate.php -sbackend

Classi Dummy

In occustomfind.ini ci sono due repository di esempio che indicizzano 10 contentuti per tipo. Per provarli occorre abilitarli

Dataset (tipo di attributo opendatadataset)

Descrizione dei campi

Nell'editor delle definizioni dei campi ogni campo ha una Descrizione: un suggerimento in solo testo (i tag HTML vengono tolti) che il redattore vede sotto il campo nel form di inserimento. Compare anche nella documentazione OpenAPI. La definizione è per lingua, quindi nella traduzione di un dataset il suggerimento si può tradurre.

Tipi di campo amount (Importo) e percentage (Percentuale)

Il valore salvato è una stringa in formato italiano, senza simboli: € e % si aggiungono solo nella tabella del dataset.

Tipo Salvato Esempi di input accettati
amount formato ANAC n.nnn,dd (sempre 2 decimali) 1550, 1550,33, 1.550,33, 1.550 (= 1550), € 1.550,33; il formato inglese (1550.33) è rifiutato
percentage numero con virgola, senza migliaia né zeri finali, max 4 decimali, segno meno ammesso 12, 12,5, 12.5, 12,5%, 12,5 %, -5,5%

Un valore non interpretabile in modo univoco (100.000.00, 1,550, abc, più di 2 decimali per l'importo) viene rifiutato con un messaggio che indica il campo. L'importo tollera il segno meno (rettifiche, storni), la percentuale no. Un solo punto seguito da 3 cifre è sempre il separatore delle migliaia (2.304 = 2304), come nei campi prezzo di eZ con locale ita-IT; per la percentuale un solo separatore è sempre il decimale.

La normalizzazione è in OpendataDatasetNumberNormalizer ed è applicata da OpendataDatasetDefinition::create(), quindi vale per form, API REST e import. I due tipi sono indicizzati come double (ordinamento e filtri numerici); la ricerca testuale libera della tabella non trova i numeri. Test: php tests/test_number_normalizer.php.

Import CSV e Google Sheet

L'import è tutto-o-niente: prima si validano tutte le righe, e se anche una sola è errata non si importa nulla; il messaggio elenca le righe da correggere (riga 1 = intestazione, massimo 20 errori riportati). La validazione avviene prima della cancellazione richiesta con «Elimina tutti i tuoi dati esistenti»: un file errato non fa perdere i dati già presenti. Vale anche per l'import in differita (oltre 200 righe) e per Google Sheet: l'errore arriva subito.

Convertire un campo di un dataset esistente in importo o percentuale

Lo script bin/php/convert_dataset_field_type.php converte un campo già esistente (per esempio importo di «Dati sui pagamenti», che oggi è una stringa) nel tipo amount o percentage. È un dry-run di default: senza --apply non scrive nulla.

# dry-run: elenca quali righe verrebbero accettate e quali rifiutate (con --report anche un CSV)
php extension/occustomfind/bin/php/convert_dataset_field_type.php -sbackend --object=<id oggetto> --field=importo --type=amount --report=/tmp/importo.csv
# conversione (solo se non ci sono righe rifiutate)
php extension/occustomfind/bin/php/convert_dataset_field_type.php -sbackend --object=<id oggetto> --field=importo --type=amount --apply
# ripristino dal backup creato dall'apply
php extension/occustomfind/bin/php/convert_dataset_field_type.php -sbackend --restore=<file di backup>

Il dry-run riporta, per ogni riga rifiutata, l'id della riga, il valore, i campi che la identificano (--identify=anno,trimestre,beneficiario) e il motivo; per gli importi segnala anche le righe che vengono accettate ma con un valore diverso da quello che l'export ANAC storico pubblicava (per esempio 1.000, letto come 1,00) e che cosa pubblicherebbe oggi l'export per le righe rifiutate (n.d. diventa 0,00). Codici di uscita: 0 ok, 2 se ci sono righe da correggere, 1 errore.

--apply: si rifiuta se resta anche una sola riga rifiutata (nessuna modifica); --empty-values="n.d.,nd,-" trasforma in campo vuoto i testi indicati (mai in automatico). Salva un backup JSON (var/<vardir>/dataset_conversion_backup/, o --backup-dir), cambia il tipo del campo nella definizione di ogni lingua (versione corrente), riscrive le righe in un'unica transazione mantenendo data di creazione, data di modifica e autore, svuota le cache, reindicizza e verifica il risultato. Si converte solo da campi di testo o numerici. Su 5.000 righe il dry-run impiega meno di un secondo e l'apply, reindicizzazione compresa, circa 8 secondi. Test della logica: php tests/test_field_converter.php.