La nuova versione ha introdotto rilevanti novità nelle sezioni di cui produciamo di seguito l’elenco. I manuali non sono ancora stati aggiornati quindi la documentazione qui presente è da considerarsi la più aggiornata.
configurare gli archivi per la pubblicazione della gerarchia
Questo sito raccoglie tutti i materiali informativi e di supporto per l”utilizzo del plugin Wp To xDams Bridge, il software creato per poter pubblicare archivi digitali descritti con la piattafforma di catalogazione xDams (www.xdams.org) su un sito gestito con WordPress (www.wordpress.org) la celebre piattaforma di blogging.
Questa integrazione consente pertanto la gestione, sulla medesima installazione, di contenuti provenienti dagli Archivi e di contenuti editoriali di natura diversa, consentendo di realizzare siti complessi
Il plugin come xDams è totalmente rilasciato con licenza GNU GPL e disponibile senza limitazioni. sono presenti in questo sito anche i manuali completi in formato PDF e i primi video tutorial ospitati dal canale You Tube di xDams.
Lo sviluppo evolutivo di xDams O.S. Platform, del plugin WordPress to xDams Bridge, dei siti e del materiale
Il materiale informativo è organizzato in tre parti:
• Configurazione utente
• Shortcode per la pubblicazione dei dati
• API
La configurazione standard predisposta permette l’utilizzo di tutte le tipologie di archivio al momento rilasciate con la distribuzione open source e di conseguenza l’utilizzo del plugin in condizioni d’uso standard di xDams.
Le prime due parti descrivono tutte le funzionalità che consentono a un utente “non tecnico” (in senso informatico) di procedere alla pubblicazione attraverso i consueti strumenti di WordPress
Agli utenti più esperti però il plugin consente anche di personalizzare ulteriormente le proprie pagine grazie alla realizzazione di moduli custom utilizzabili al posto di quelli standard utilizzando semplici API pubbliche. L’illustrazione di queste possibilità aggiuntive è contenuta nella sezione API attualmente in progress. Le informazioni sono già disponibili nel manuale (documento PDF) ma devono ancora essere riviste per la pubblicazione su questo sito
L’utente che però desidera concentrarsi solo sulle funzionalità più operative e necessarie può rinviare ad un secondo momento la lettura del manuale avanzato che descrive le su citate funzioni.
SUMMARY funzioni
Il plugin consente:
• La gestione di pagine di amministrazione
• la pubblicazione di post e pagine
L’attività di configurazione di base permette di:
• definire i campi da visualizzare nei form di ricerca con relative label
• definire i campi da visualizzare nella scheda di dettaglio con relative label
• definire i campi da visualizzare nell’elenco dei risultati
• attivare /disattivare l’accesso agli archivi
La pubblicazione è estremamente semplificata in quanto, grazie a shortcode (semplici istruzioni testuali da inserire nelle pagine di wordpress mediante l’editor grafico), sono disponibili:
• form di ricerca testuale
• form di ricerca su campi specifici
• ricerca multiarchivio
• liste di risultati in formato testuale (con o senza criteri di selezione)
• liste di risultati con preview (con o senza criteri di selezione)
• liste di risultati con slideshow (per schede con immagini)
• liste di risultati per valori esistenti in un campo (vocabolari)
• pubblicazione di singole schede
• pubblicazione di singole immagini
• semplice modulo di story telling
Il plugin è infine predisposto per
• l’import di successive configurazioni,
• l’import / export delle preferenze salvate dall’utente
• la gestione multilingue dei messaggi di sistema e delle label dei campi.
La funzione restituisce una stringa che può essere direttamente aggiunta nell’HTML di risposta e contiene la descrizione della posizione gerarchica della scheda in corrente.
es. $outHier = WPxdamsBridge_getItemHier();
La personalizzazione della stringa output può essere pilotata dalla pagina archive settings che permette di definire
la visualizzazione del livello gerarchico viene definita sempre nella pagina archive settings con le opzioni
La compilazione della stringa implica la richiesta di un file al server che contiene per ogni record un elenco di campi per ogni livello che precede gerarchicamente il livello corrente. Per operare modifiche sulla configurazione occorre conoscere la struttura del file di risposta il cui ottenimento è determinato dalle condizioni già descritte in altri contesti con in aggiunta il paramentro:
il file che otteniamo ha la seguente struttura per ogni elemento identificato dai tag
ovvero una stringa di questo tipo
<c></c>
dove all’interno del tag c/hier ho una sezione per ogni livello. All’interno di questa porzione di testo trovo i titoli estratti da campi della rispettiva scheda, contrassegnati da un inizio e una fine con sintassi convenzionale, nel nostro esempio
Nella medesima pagina archive settings trovo in fondo la possibilità di personalizzare la struttura ma per un primo livello di intervento occorre solo definire che tipologia di archivio sto gestendo. Questa configurazione viene utilizzata anche per la costruzione dell’alias dell’archivio ma si sconsiglia in questa prima fase l’ulteriore personalizzazione.
E’ possibile definire proprie specifiche in un file che è contenuto nella cartella
la ratio generale è che tutti i file nella cartella WPxdams_custom/ sono file creati dal cliente e quindi da non sovrascrivere nelle nuove versioni.
Il file CSS in particolare è:
che viene automaticamente caricato dal sistema
La versione 3.2.2 ha introdotto una nuova tipologia di API e grazie a questa feature è stato possibile creare una funzione che genera su wordpress un alias dell’albergo gerarchico di un archivio. Questo processo non si basa su dati restituiti on line dalle API (per individuare i figli di un elemento) ma su un processo che ricostruisce la struttura con un processo a parte, in maniera asincrona. Trattandosi di dati residenti sul DB è ovvio che l’inserimento di nuove schede o lo spostamento di preesistenti determina la necessità di rigenerare l’albero. la modifica dei dati della singola scheda invece non determina alcuna necessità di aggiornamento.
Per capire il funzionamento occorre sapere che le API restituiscono ora una indicazione della posizione della scheda nella struttura inviando il padre della scheda, il padre di questo e cosi via fino alla radice dell’albero gerarchico.
ovvero una stringa di questo tipo
<c></c>
Il processo realizzato estrae il valore del padre diretto e lo cerca nei valori delle schede precedenti per memorizzare il legame padre figlio.
I campi presenti nella pagina di amministrazione contengono, per ogni livello di scheda, il nome del campo (definito nella pagina output fields) su cui effettuare il confronto. Ciò detto è evidente che il nome del campo definito nella pagina di amministrazione deve avere un riscontro con i campi definiti a livello di singola scheda nelle pagine output fields.
In questo esempio estraiamo il primo valore ovvero quello contenuto tra l’inizio e [@tit@] cioè “Archivio Aperto città di Battipaglia (storico)”. Questo valore corrisponde a quello presente nel campo descritto dal path /c/did/unittitle/ del livello fond. I caratteri “||” delimitano l diversi livelli della gerarchia in successione. Il primo è il livello più alto e l’ultimo quello relativo alla scheda in oggetto. (leggi anche qui)
Si consiglia a tal proposito di utilizzare il campo con un path più preciso possibile e con la spunta del flag “clean” che elimina valori contenuti in eventuali sotto tag. Il file che contiene il campo della gerarchia contiene il solo valore del tag e quindi il confronto deve essere con il valore del campo senza ulteriori stringhe.
E’ importante prima di iniziare l’importazione di avere verificato i dati e di avere salvato la configurazione per i legami gerarchici in archive settings attivandone la funzionalità.
Dalla versione 2.2 del plugin è possibile trovare tra le voci di menu una nuova:
grazie alla quale si accede a una lista degli archivi disponibili per cui selezionandone uno si arriva alla maschera operativa. Sono presenti dei campi sulla base dei quali viene generato l’albero ovvero per ogni livello c’è il campo da utilizzare come guida. Si consiglia di lasciare i valore pre impostati.
Il processo ricostruito, per ogni scheda, cerca il calore corrispondente al livello gerarchicamente immediatamente superiore. Il calore del campo indica a quale scheda del campo occorre far riferimento per trovare l’elemento padre.
Il funzionamento è poi semplice basta sottomettere il processo premendo il secondo pulsante e attendere. L’operazione può durare a lungo per archivi che superano i 4000/5000 documenti quindi si raccomanda pazienza.
Più si allunga il tempo di lavorazione più possono esserci problemi di connessione con il server che quindi potrebbe bloccarsi. In questo caso si consiglia di ricaricare la pagina e il sistema fornirà le informazioni sullo stop e sarà pronto a ripartire dall’ultimo break, basterà far ripartire il sistema avendo cura di flaggare il checkbox per il resume del processo. Se invece si pensa di dover ripartire da zero basterà premere il pulsante con il flag disattivo.
La chiusura della pagina non determina lo stop del processo per cui rientrando si avranno informazioni sullo stato dell’elaborazione.
Attendere sempre qualche secondo prima di intraprendere nuove azioni in base a messaggi del sistema. E’ infatti presente un delay che ritarda di qualche istante le segnalazioni lato server
[xdamsTree type=’archive ID’ ][/xdamsTree]
Attiva una lista di risultati con la posizione nell’albero gerarchico in formato navigabile. Se i risultati per uno specifico nodo sono più di 10 subentra anche la paginazione
I presupposti per l’utilizzo di questa funzionalità sono due:
A differenza degli altri comandi i dati generali vengono prelevati da xDams mentre la ricostruzione dell’albero gerarchico viene fatta in maniera asincrona sul DB di WordPress. Pertanto le modifiche introdotte su xDams (nuove schede o modifica della posizione della scheda) non risultano sul front end se prima non si da corso a una nuova procedura di importazione della struttura (solo per lo specifico archivio modificato). La sintassi è la seguente
[xdamsTree type=’id archivio’ ]/[/xdamsTree]
Sono previsti i seguenti parametri
treetemplate = per definire quale template di pubblicazione (da predisporsi a cura dell’utente e posizionato nella directory “custom”) utilizzare per la pubblicazione dei risultati
formtemplate = per definire quale template di pubblicazione (da predisporsi a cura dell’utente e posizionato nella directory “custom”) utilizzare per la pubblicazione del una sezione laterale (es. box con navigazione gerarchica)
treestartlevel = per cominciare la navigazione a partire da uno specifico nodo.
formdescpost = consente di utilizzare un testo da inserire nel form prima delle chiusura del layout personalizzato
******************************************************************
****** WordPress to xDams Bridge – Release Notes *******
******* last update 18th october 2018 – version 2.2 *********
******************************************************************
**** version 2.2.0 18 oct 2018 GARD ————————–
NEW > historical archive new config file for collections
NEW > historical archive new config file for series
NEW > historical archive new config file for subserie
NEW > historical archive new config file for subfonds
NEW > historical archive new config file for files
NEW > added eaccpf archive configuration (people authority)
NEW > added itembultiearch attribute (in listshortcode) to start a multiarchive search by a detail page (relataed content)
NEW > added formdescpost attribute (in list and search shortcode)
NEW > added redirectitem attribute to customize item page (in list and search shortcode)
NEW > added redirect attribute to customize second page in vocabulary (only!) result list (in list shortcode)
NEW > added vocabularytemplate attribute to customize vocabulary results list (in list shortcode)
NEW > added menutemplate attribute to customize menu (in list and search shortcode)
NEW > added showarchives attribute to show or not other archives in result page (in search shortcode)
NEW > added showlist attribute to show a results list in first page (in search shortcode)
NEW > added xdamsTree shorcode with formdescpost, formtemplate, treetemplate and treestartlevel attributes
NEW > Create index page in back end (for xdamsTree)
NEW > singular / plural in messages
NEW > added responsive menu (using in your template WPxdamsBridge_getPagingMenuBootstrap ())
NEW > added alphabetical navigation menu for vocabulary
NEW > added separator in output fields settings (beetween two occurencies of same field
NEW > added group end value in output fields settings
NEW > added hierarchy visualization in item page
NEW > added customization options for hierarchy visualization
NEW > added itemdescpre itemdescpos listdespre listdescpos attributes in text and Ad search
NEW > photo archive new config file for collections
NEW > photo archive new config file for series
NEW > photo archive new config file for files with media field
NEW > added page list customization for multiarchives search (option for archive in archive settings)
NEW > number of results in menu made visible or not (customizable)
NEW > customizable width of search box
NEW > customizable redirect page in search form (results page in a different wordpress page)
NEW > custom form and results page in 2 different cols (example ABG)
NEW > added field attribute as search criteria
NEW > added field attribute value for field selection (output fields page)
NEW > added option to publish only the attribute value
CHANGE > changed “search form field” configuration page label in “Archives settings”
CHANGE > OA configuration file upgraded
FIX > error in cleaning html tags.
FIX > bug in search caused by characters as è é ç etc.
FIX > null value in description
FIX > to publish only public item without search criteria ( no error if the search criteria have been added in shortcode)
FIX > correct visualization of multiple occurences of a field in absence of end tag (only “/>”)
FIX > uncorrect visualization a field value when it is at the end of the XML tag
FIX > search text condition error in xdamsList shorcode
FIX > obsolete method for capabilities in add menu page
FIX > eliminated double slash in photo url
**** version 2.1.4 23 aug 2108 Stari Most ——-not published——
**** version 2.1.3 09 jan 2108 Stari Most ————————–
FIX > compatibility issues in Admin using some themes
FIX > visualizzation of character with umlaut, accent etc. in vocabulary list
FIX > management of characters in unicode for vocabulary search
FIX > @=text to find in search criteria for listing
**** version 2.1.2 22 dec 2017 Stari Most ————————–
NEW > added a check in configuration to publish only value of a tag excluding nested subtags
FIX > pages menu after serch form
**** version 2.1.1 18 dec 2017 Stari Most ————————–
NEW > add and delete field in search form settings
NEW > selective import for archives levels and search form fields
NEW > added new level configurations in OA archive
FIX > search field configuration for OA Archive
FIX > special html character management in search form (wrong visualization es. /’ )
**** version 2.1 12 dec 2017 Stari Most ————————–
NEW > modifiable img field in output field settings
NEW > management of external urls form images and/or attachments
NEW > attachments management for multiaccount installations
Una volta completate le operazioni di configurazione degli archivi e delle modalità di pubblicazione dei risultati è possibile definire dove e come gli archivi vengono pubblicati. Tale pubblicazione, a questo punto, avviene semplicemente immettendo in un post o in una pagina uno shortcode, ovvero delle stringhe di testo contraddistinte da un tag iniziale indicato tra parentesi quadre e un tag che chiude l’esecuzione di tale codice, sempre indicato tra parentesi quadre.
La sintassi segue questa regola:
[nomeDelTag] contenuto [/nomeDelTag]
dove il simbolo / seguito dal nome del tag ne indica la chiusura
Nel tag iniziale possono essere inclusi dei parametri per cui la sintassi diventa
[nomeDelTag param1=val1 param2=val2] contenuto [/nomeDelTag]
Un esempio di utilizzo reale di shortcode è il seguente:
[xdamsItem type=’fotografico’] IT-xDams-archivioprovincialems-FT0001-000371[/xdamsItem]
| shortcode | descrizione |
| [xdamsItem type=’archive ID’ ] xdams item id [/xdamsItem] | Pubblica una scheda |
| [xdamsImage type=’archive ID’ ] xdams item id [/xdamsImage] | Pubblica l’immagine allegata di una scheda |
| [xdamsSearch type=’archive ID’ ] search criteria or nothing [/xdamsSearch] | Form ricerca fulltext |
| [xdamsAdSearch type=’archive ID’ ][/xdamsADSearch] | Form ricerca avanzata |
| [xdamsList type=’archive ID’ ] search criteria or nothing [/xdamsList] | Lista |
| [xdamsList type=’archive ID’ vocabulary=’number of occurrences’] field id [/xdamsList] | Lista (vocabolario) |
| [xdamsListImg type=’archive ID’ ] search criteria or nothing [/xdamsListImg] | Lista con immagini |
| [xdamsPreview type=’fotografico’] search criteria or nothing [/xdamsPreview] | Lista con immagini e preview |
| [xdamsDynSlider type=’fotografico’] search criteria or nothing [/xdamsDynSlider] | Slider |
| [xdamsStory type=’story ID’ height=’maximum height of the slide’ ratio=’fullscreen’ interval=’slides interval’ ] Story id [/xdamsStory] | Story Telling |
| [xdamsTree type=’archive ID’ ] [/xdamsTree] | Albero – coming soon |
| [xdamsTree type=’archive ID’ ] [/xdamsTree] | Albero – coming soon |
[xdamsPreview type=’archive ID’ ] search criteria or nothing [/xdamsPreview]
Concettualmente lavora come xdamsList ma si adatta meglio ad archivi per i quali è prevista una immagine di preview utilizza una modalità tipo anteprima.
Produce una elenco di risultati paginati, se non viene inserito alcun criterio la lista pubblica l’intero archivio.
Come nel caso della ricerca full text nel type potrà essere inserito o l’ID di uno specifico archivio o il valore convenzionale “@all” che consentirà la ricerca su tutti gli archivi.
listtemplate per definire quale template di pubblicazione (da predisporsi a cura dell’utente e posizionato nella directory “custom”) utilizzare per la pubblicazione dei risultati
i template per la pubblicazione sono prioritari rispetto a quelli eventualmente definiti a livello di bacheca
possono essere aggiunti dei criteri di selezione per realizzare liste filtrate di oggetti. Qui maggiori info
Il menu di paginazione include due icone per passare da questo tipo di visualizzazione alla visualizzazione “preview” ( vedi paragrafo successivo)
Di seguito invece una immagine del possibile risultato ottenibile con il template standard.
[xdamsListImg type=’archive ID’ ] search criteria or nothing [/xdamsListImg]
Concettualmente lavora come xdamsList ma si adatta meglio ad archivi per i quali è prevista una immagine di preview perché il risultato su due colonne prevede appunto una anteprima dell’immagine.
Produce una elenco di risultati paginati, se non viene inserito alcun criterio la lista pubblica l’intero archivio.
Come nel caso della ricerca full text nel type potrà essere inserito o l’ID di uno specifico archivio o il valore convenzionale “@all” che consentirà la ricerca su tutti gli archivi.
listtemplate per definire quale template di pubblicazione (da predisporsi a cura dell’utente e posizionato nella directory “custom”) utilizzare per la pubblicazione dei risultati
i template per la pubblicazione sono prioritari rispetto a quelli eventualmente definiti a livello di bacheca
possono essere aggiunti dei criteri di selezione per realizzare liste filtrate di oggetti. Qui maggiori info
Il menu di paginazione include due icone per passare da questo tipo di visualizzazione alla visualizzazione “preview” ( vedi paragrafo successivo)
Di seguito invece una immagine del possibile risultato ottenibile con il template standard.
il testo incluso all’interno dello shortcode permette di definire dei criteri di ricerca da applicare come selezione.
Questo paragrafo da indicazioni che sono valide per tutti cli shortcode che prevedono liste di risultati. Vediamo qualche esempio:
es.:
/c/controlaccess/subject/=spiagge
è necessario indicare correttamene tutto l’xpath e possono essere usati anche AND e OR.
Per la ricerca fulltext occorre seguire la seguente sintassi
es. :
/c/@level=item
possono essere utilizzati operatori logici:
/c/@level=item OR /c/@level=file
Questo ultimo esempio è utile per visualizzare solo i documenti che in qualche modo rappresentano il nodo finale dell’albero gerarchico più specificatamente utilizzati per descrivere oggetti e non livelli organizzativi dell’archivio. Al momento le condizioni possono essere multiple ma non il medesimo operatore logico.
Utilizzando un criterio di ricerca come quelli visti in precedenza si possono creare percorsi tematici tanto più efficaci quanto più questa operazione è pianificata già in fase di catalogazione, utilizzando. per esempio nel campo temi parole chiave specifiche che possano essere successivamente utilizzate come parole chiave in fase di ricerca.
Naturalmente occorre considerare che il parametro “@all” richiede che il campo di ricerca sia analogo su tutte le schede. Nel caso di query su archivi con struttura differente occorre prevedere eventualmente campi differenti.
Per esempio in caso di archivio storico (o fotografico ecc.) e bibliografia occorre prevedere la ricerca in OR sulle diverse tipologie di tag aggiungendo all’ultimo esempio precedente anche la clausola /mods/extension/level=item , pertanto un’ipotesi di short code può essere.
[xdamsListImg type=’@all’ ] /c/@level=item OR /c/@level=file OR/mods/extension/level=item[/xdamsListImg]
E’ stata implementata la ricerca per campo con specifico attributo la sua sintassi è
nome campo/@nome attributo=valore da ricercare
vediamo un esempio:
/eac-cpf/cpfDescription/relations/cpfRelation/relationEntry/@localType=IT-NOMEARCHIVIO1-006145
