WPToXdamsBridge2017 001 Usersmanual 03 0

regesta.
exe srl
WPxdamsBridge Basic Manual

Plugin Wordpress per pubblicare contenuti di xDams
codice fiscale - Partita Iva - Iscrizione Reg. Imprese di Roma 09825831002

regesta.exe srl
via Monte Zebio 19 - 00195 Roma –
vox 0637501056 fax 0637410460
mail@regesta.com | www.regesta.com www.xdams.org
Riferimenti
Descrizione Contenuto
Oggetto Progetto di pubblicazione dell’archivio xDams su Wordpress
Descrizione Manuale di istruzioni sull’uso del plugin di bridge tra xDams e

Wordpress – versione utente basic
Categoria Manuale
Riferimenti esterni Versione del plugin 2.0
Destinatario public
Autori Carlo Bruno (CB)
Nome File WPToXdamsBridge2017_001_usersManual_03_0.docx
Pagine / versione 37 / 3.0
è un prodotto open source coperto da GNU Free Documentation License e

realizzato da regesta.exe www.regesta.com
Riservatezza
Regesta.exe srl fornisce queste informazioni prevedendo che sarà
mantenuto il corretto livello di riservatezza sui relativi contenuti.
Il documento non potrà essere fotocopiato o riprodotto, in tutto o in
parte, i contenuti non potranno essere divulgati a terzi, senza il consenso
scritto di Regesta.exe srl.
WPxdams2017_01 Plugin xDams to Wordpress Manuale base v 3.0 2

regesta.exe srl
vox 0637501056 fax 0637410460
Amendment History
Autore Data Descrizione Vers. Approvazione
CB 25 febbraio 2016 Prima Stesura 1.0
CB 2 giugno 2016 Adeguamento 2.0
funzionale:
nuove specifiche file di
configurazione
CB 16 giugno 2016 Descrizione delleP ublic 2.1
API
CB 26 luglio 2016 Utilizzo avanzato delle 2.2
API rest
CB 20 settembre 2016 Gestione lingue e 2.3
funzione vocabulary
CB 10 ottobre 2016 Modifica story e divisione 2.4
documento in manuale
base / avanzato
CB 26 ottobre 2016 Descrizione e obiettivi 2.5
CB 15 novembre 2016 Parametri aggiuntivi per 2.6
stories e gestione
standard lido
CB 16 dicembre 2016 Modifica gestione 2.7
configurazioni e import
settings
CB 24 gennaio 2017 Divisione funzionalità 2.8
core da plugin per lo
story telling
CB 4 novembre 2017 Introdotte condizioni 2.9
addizionali nella ricerca
libera
CB 25 novembre 2017 Aggiornamento del 3.0
paragrafo delle
configurazioni php

regesta.exe srl
vox 0637501056 fax 0637410460
SOMMARIO
1 INTRODUZIONE.................................................................................................... 6
1.1 Altri strumenti di supporto .........................................................................................................7
1.2 Struttura del documento .............................................................................................................7
1.2.1 SUMMARY funzioni .................................................................................................................8
2 SETTINGS ............................................................................................................. 9
2.1 Configurazione PHP (obsoleto dalla versione 2.0) ...................................................................9
2.1.1 Versioni precedenti alla 2.0 (deprecato) ..................................................................................9
2.2 General Setting ..........................................................................................................................10
2.3 Search form ................................................................................................................................11
2.3.1 Walk around form di ricerca ...................................................................................................13
2.4 Output fields ...............................................................................................................................13
2.5 Language ....................................................................................................................................15
2.5.1 Walk around language ...........................................................................................................17
2.6 Stories .........................................................................................................................................17
2.6.1 Dettaglio singola slide ............................................................................................................19
2.7 Import / export............................................................................................................................20
2.7.1 introduzione file di configurazione .........................................................................................21
2.7.2 Import di file di configurazione ...............................................................................................21
2.7.1 Export settings .......................................................................................................................21
2.7.1 Export settings .......................................................................................................................22
3 SHORTCODE ...................................................................................................... 23
3.1 Shortcode disponibili ................................................................................................................23
3.2 [xdamsItem type='archive ID' ] xdams item id [/xdamsItem] .................................................24
3.3 [xdamsImage type='archive ID' ] xdams item id [/xdamsImage] ...........................................25
3.4 [xdamsSearch type='archive ID' ][/xdamsSearch] ..................................................................25
3.5 [xdamsAdSearch type='archive ID' ][/xdamsADSearch] ........................................................26
3.6 [xdamsList type='archive ID' ] search criteria or nothing [/xdamsList]................................26
3.6.1 Criteri di ricerca: ....................................................................................................................27
3.7 [xdamsList type='archive ID' vocabulary=’number of occurrences’] field id [/xdamsList]
28
3.8 [xdamsListImg type='archive ID' ] search criteria or nothing [/xdamsListImg] ...................29
3.9 [xdamsPreview type='fotografico'] search criteria or nothing [/xdamsPreview].................30
3.10 [xdamsTree type='archive ID' ] [/xdamsTree] - coming soon ..............................................31
3.11 [xdamsTree type='archive ID' ] [/xdamsTree] - coming soon ..............................................31
4 WPTOXDAMSSTORIES ..................................................................................... 33

regesta.exe srl
vox 0637501056 fax 0637410460
4.1 Struttura a template ...................................................................................................................33

4.1.1 Story Renders, la struttura generale di narrazione ................................................................33
4.1.2 Slide Template, struttura della singola slide ..........................................................................34
4.2 [xdamsStory] Story id [/xdamsStory] .....................................................................................34
4.3 Parametri di personalizzazione delle slide ..............................................................................36
4.4 [xdamsDynSlider type='fotografico'] search criteria or nothing [/xdamsDynSlider] ..........37

regesta.exe srl
vox 0637501056 fax 0637410460
1 INTRODUZIONE
Il presente documento è finalizzato a illustrare le modalità di utilizzo del
plugin WP to xDams Bridge realizzato per pubblicare dati catalogati con
xDams Open Source Platform(www.xdams.org) su un sito gestito con la
piattaforma editoriale Wordpress (www.wordpress.org).
xDams Open Source Platform è una soluzione software realizzata da

regesta.exe (www.regesta.com), la società italiana che nel 2012 ha
rilasciato questa piattaforma con licenza open source e che
principalmente ne coordina le ulteriori innovazioni e gli strumenti di
supporto.
regesta.exe ha inoltre realizzato Il plugin per Wordpress, rilasciato con

medesimo licenza OS., e il presente documento curandone i successivi
aggiornamenti.
E’ già possibile pubblicare, mediante il presente plugin. archivi ospitati dal

servizio The Archives Cloud (www.thearchivescloud.com) gestito da
regesta.exe.
Il materiale informativo è suddiviso in due differenti documenti:
• Manuale utente di base (il presente documento)

• Manuale utente avanzato
A partire dalla versione 1.2 del plugin le funzionalità per lo story telling
sono state enucleate rispetto al core del plugin e allocate in un nuovo
plugin denominato Wp to xDams stories il cui funzionamento non è
indipendente dall’installazione del plugin principale.
La finalità principale è quella di consentire la promozione e diffusione del

patrimonio culturale sul web anche da parte di utenti con ridotte
competenze tecnologiche. L'integrazione con il CMS consente di
avvalersi di tutte le potenzialità offerte da Wordpress, quali disponibilità di
template grafici già esistenti, funzionalità di pubblicazione e
organizzazione dei contenuti o disponibilità una molteplicità di plugin che
realizzano le più differenti funzionalità Web. La diffusione di Wordpress
infine è garanzia di continui aggiornamenti e di crescente disponibilità di
svariate opzioni editoriali, grazie ai plugin disponibili

regesta.exe srl
vox 0637501056 fax 0637410460
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.
1.1 Altri strumenti di supporto

I manuali precedentemente descritti sono una parte del materiale
informativo predisposto per favorire l’utilizzo del plugin sono infatti
disponibili:
• wiki di progetto con tutte le informazioni qui incluse –

http://support.xdams.org
• sito demo live con dati estratti da archivi realmente esistenti –

http://plugin.xdams.org
• forum sul sito www.xdams.org per fare richieste di supporto al team

che si occupa della gestione del software
• video tutorial sul canale YouTube di xDams

https://www.youtube.com/user/xdamsplatform (disponibili:
configurazioni iniziali, form di ricerca, liste di risultati e percorsi)
1.2 Struttura del documento

Il documento è organizzato in due parti:
• Configurazione utente
• Shortcode per la pubblicazione dei dati
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 due sezioni 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

regesta.exe srl
vox 0637501056 fax 0637410460
utilizzabili al posto di quelli standard utilizzando semplici API pubbliche.

L’illustrazione di queste possibilità aggiuntive è contenuta in un secondo
manuale per l’uso avanzato.
Pertanto l’utente che 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 .
1.2.1 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.

regesta.exe srl
vox 0637501056 fax 0637410460
2 SETTINGS
La configurazione iniziale del plugin prevede tre passi che devo essere
obbligatoriamente effettuati prima di cominciare a pubblicare i dati,
ovvero:
• Configurazione generale (general settings)

• Attivazione degli archivi e dei campi di ricerca ( search form fields)
• Configurazione delle preferenze di pubblicazione (output fields)
Sono inoltre disponibili funzionalità di

• Modifica dei messaggi di sistema
• Gestione Multilingua
• Creazione e gestione di “storie” (con plugin WPtoxdamsStories)
• Attività di import export delle configurazioni
Il passo stories è opzionale e consente ti predisporre mostre e percorsi

tematici virtuali. Prima di procedere comunque occorre verificare le
impostazioni di sistema.
2.1 Configurazione PHP (obsoleto dalla versione 2.0)

La versione 2.0 (la prima pubblicamente scaricabile dal sito) ha introdotto
una nuova gestione della lettura dei file per evitare le configurazioni PHP
precedentemente utilizzate e sconsigliate per motivi di sicurezza.
Pertanto dalla versione 2.0 non è più necessaria alcuna configurazione

particolare di php. Per chi utilizza la versione precedente e non ha
ancora migrato la propria installazione manteniamo nel paragrafo
successivo le indicazioni da seguire.
2.1.1 Versioni precedenti alla 2.0 (deprecato)

Una volta scaricato il plugin questo può essere attivato dalla consueta
pagina dei plugin di wordpress. Il plugin utilizza alcuni file di
configurazione e legge file richiesti da remoto pertanto, per poter
garantire il corretto funzionamento del medesimo, occorre verificare il
corretto settaggio, nel file php.ini, del parametro
allow_url_fopen
che deve essere attivo (“on”).

regesta.exe srl
vox 0637501056 fax 0637410460
Nel caso dell’hosting presso la nostra web farm tale parametro è già
attivo e pertanto non occorre alcuna operazione mentre nel caso di altri
provider occorre verificare. Normalmente i provider forniscono delle
interfacce che consentono di modificare il file php.ini senza accedervi
fisicamente. Per chi lavora in locale deve accedere al file ed
eventualmente modificare la seguente linea
allow_url_fopen = On.
2.2 General Setting

L’attivazione del plugin introduce una nuova voce di menu nella
bacheca di wordpress ovvero: WP to Xdams Bridge

regesta.exe srl
vox 0637501056 fax 0637410460
La prima operazione consiste nel configurare le opzioni generali (voce fi

menu General settings) ovvero
• url che sarà utilizzata per le richieste al sistema (fornita dal
provider)
• url per recuperare le immagini (fornita dal provider)
• url per recuperare altri allegati (fornita dal provider)
La URL del primo campo è obbligatoria Una volta salvata la
configurazione si passa alla definizione dei campi da utilizzare nella
maschera da ricerca.
Fino alla versione 1.0 era obbligatorio salvare le configurazioni dei form di
ricerca e delle pagine di dettaglio prima di cominciare a lavorare. Dalla
versione 1.1 è stato introdotto il concetto di importazione automatica
delle configurazioni per cui a partire dal salvataggio delle stringhe per le
richieste al server è già possibile cominciare a lavorare sulle pagine con le
impostazioni di default.
N.B
La prima volta che si entra in configurazione saranno visibili due pulsanti
• Import and Update

• Only Update
Se sei alla prima installazione occorre premere il pulsante “Import and

Update”, secondo pulsante serve solo nel caso si stia già utilizzando
versioni precedenti del plugin e si desideri mantenere le impostazioni
precedentemente salvate. Dal salvataggio successivo al primo utilizzare
sempre il pulsante “only update” a meno che non si desideri procedere
nuovamente all’importazione dei dati da file di configurazione. Import
and Update” procede infatti con la reimportazione dei dati dai file di
configurazione e ricoprirebbe le preferenze salvate con i valori di default.
2.3 Search form

Mediante questa pagina è possibile definire (partendo dall’alto:
• Se un singolo archivio è visibile

• Se occorre visualizzare tutti gli elementi o solo quelli definiti
all’interno della piattaforma di back end xDams come pubblici
• Per ogni campo
o se il campo è visibile
o personalizzare la label di pubblicazione

regesta.exe srl
vox 0637501056 fax 0637410460
Possono anche essere salvati i nomi dei file (.php) che contengono le
istruzioni di visualizzazione (template) per:
• la maschera di ricerca
• la pubblicazione della scheda singola.
• La pubblicazione delle liste di risultati.

regesta.exe srl
vox 0637501056 fax 0637410460
E’ possibile infatti costruirsi delle proprie maschere di ricerca e

visualizzazione con un altro livello di personalizzazione.
Naturalmente occorre avere una certa dimestichezza con il linguaggio
php mentre sono disponibili delle semplici API per la richiesta di dati a
xDams OS.
Di default vengono utilizzati template standard nella directory
“Directory dei plugin/WPxdamsBridge/WPxdams_template”
Nella directory
WPxdamsBridge/custom
possono essere posizionati i file custom. Nel caso di personalizzazioni del

template è preferibile utilizzare tali template custom, magari ricavati
clonando quelli di default e personalizzabili a proprio piacimento, in
quanto cosi non si corre il rischio che operazioni di aggiornamento del
plugin possano comportare la perdita delle personalizzazioni nel
frattempo introdotte. Nella directory /css possono essere rintracciati i fogli
di stile del plugin.
2.3.1 Walk around form di ricerca

Al momento è possibile solo un form di ricerca per ogni archivio ma lo
shortcode permette di creare form di ricerca con tutti i campi o solo con
un campo specifico.
Nel caso si desideri creare una nuova vista del form di ricerca
personalizzata è possibile definire un nuovo archivio virtuale, che insista
sempre su un medesimo archivio reale, ma che consente di creare una
maschera con dati diversi da quella già definita.
Ragionamento analogo può essere applicato nel caso della

visualizzazione di dettaglio di una scheda, più archivi virtuali possono
rendere possibile definire schemi di visualizzazione diversi in base a
necessità diverse ma su medesimi archivi.
2.4 Output fields

Per ognuna delle schede disponibili di uno specifico archivio (operazione
possibile a partire inizialmente dai file di configurazione di ogni tipologia di
scheda) è possibile descrivere quali campi mostrare e con quali label.

regesta.exe srl
vox 0637501056 fax 0637410460
In fase di avvio del progetto si può richiamare ogni singola scheda e

salvare la configurazione personalizzata. La funzione di import a partire
dalla versione 1.1 salva la configurazione di default sul DB già in fase di
prima attivazione e da qui la configurazione può essere gestita poi nel
plugin.
Per gestire più viste dei medesimi dati si può procedere come al punto
“walk around” del paragrafo precedente. Si può invertire l’ordine dei
campo mediante drag and drop.
E’ possibile modificare
• il nome del campo da file di configurazione
Attenzione questa è la stringa che viene utilizzata per identificare il dato

nel file di risposta delle API rest e pertanto deve corrispondere al path (o
parte di esso se non ci sono ambiguità) utilizzato per descrivere il dato
medesimo:
Altri campi utilizzabili per la personalizzazione:

• la casella di input per definire la propria label personalizzata
• il flag per pubblicare o meno il campo.
• Il flag per cancellare il campo

regesta.exe srl
vox 0637501056 fax 0637410460
• 4 campi di testo il cui contenuto viene inserito prima e dopo il titolo

e il valore assunto dal campo.
Questi 4 campi servono a personalizzare la visualizzazione delle liste senza

alcun intervento di programmazione infatti possono contenere semplice
testo (es. punteggiatura) o comandi HTML (es. per a capo, 
e per il grassetto o e per il corsivo).
Per i più esperti è possibile anche definire una classe la cui descrizione
includere poi in un file CSS.
Viene pubblicata anche

• l’informazione se è un gruppo di campi
• l’informazione se prevede un attributo
• la label originale del file di configurazione
Nel caso si importi un nuovo file di configurazione occorre ripetere

l’operazione e salvare. Nella stessa pagina è inoltre disponibile il pulsante
“update and add” che consente di inserire un campo ex-novo
direttamente da back office.
2.5 Language
Da questa pagina è possibile gestire la pubblicazione multilingua degli
archivi.

regesta.exe srl
vox 0637501056 fax 0637410460
Esistono due tipologie di pagine per definire:
• traduzione personalizzata dei messaggi di sistema (general terms)

• traduzione personalizzata delle label dei i campi di output e
ricerca
il tasto “add language” consente di aggiungere la traduzione in nuove

lingue, questa opzione è disponibile solo nell’opzione general terms. Per
ogni archivio è disponibile la traduzione delle stringhe. Nel caso una
lingua non fosse prevista il sistema proporrà i termini del main language.
I termini tradotti vengono memorizzati in file di configurazione conservati

nella sottodirectory “languages” della directory “_custom”.

regesta.exe srl
vox 0637501056 fax 0637410460
nota bene: la traduzione dei messaggi di sistema fa riferimento all’id del

messaggio, pertanto cambiandone la label nella lingua principale non si
verificano problemi di alcun genere. Nel caso dei campi di ricerca e di
output la lista dei termini da tradurre viene ricavata dall’insieme di label
personalizzate, per esempio il xpath/title può avere label “titolo” o “titolo
del libro” a seconda del tipo di scheda, oppure può essere il medesimo.
Per questo motivo si è scelto di tradurre direttamente le label, ciò significa
che cambiando una di queste, per esempio da “titolo” a “titolo proprio”
dovrò aggiornare conseguentemente la traduzione.
2.5.1 Walk around language

Al momento il sistema non consente di leggere file già esistenti per
linguaggi non ancora inizializzati pertanto l’azione “add language”
produce la visualizzazione di una colonna vuota e l’eventuale
sovrascrizione di file esistenti al salvataggio. Si consiglia pertanto in
situazioni del genere (per esempio da una istanza di test alla produzione)
di creare un nuovo file per il linguaggio desiderato e poi sovrapporre i file
già generati nell’altra istanza.
2.6 Stories
Questa funzionalità, inizialmente inclusa nel plugin e poi spostata in un
plugin dedicato permette di pubblicare slideshow, ovvero pagine in cui
sono visualizzate animazioni come sequenze di slide.

regesta.exe srl
vox 0637501056 fax 0637410460
Si tratta in pratica di un modulo elementare di story telling.
E’ possibile descrivere N a piacere storie ed eventualmente duplicarne

per derivarne nuove con caratteristiche simili. La voce di menu introduce
all’elenco delle storie, successivamente con il tasto “manage” si accede
all’elenco delle slide.
E’ possibile definire:
• una immagine di sfondo
• titolo
• autore
• descrizione
• numero di slides
• per ogni slides:

o Identificativo scheda (id archivio e id scheda)

regesta.exe srl
vox 0637501056 fax 0637410460
o La url di immagine alternativa (se non presente questo

campo di default viene presa, se esiste, quella della
scheda
o Html alternativo da utilizzare al posto dell’immagine
E’ possibile cambiare l’ordine delle slide mediante drag and drop ed

eliminare definitivamente una scheda.
2.6.1 Dettaglio singola slide

Per ogni scheda è presente nella pagina descritta in precedenza un
pulsante “detail” che consente di attivare una nuova schermata.

regesta.exe srl
vox 0637501056 fax 0637410460
Non tutte le opzioni presenti in questa pagina sono attive per tutti i modelli
di slideshow, dipende ovviamente da quali funzionalità sono state
implementate, si lascia alla spiegazione di ogni singolo slideshow la
definizione dei campi realmente utilizzati.
Da questa pagina si può impostare
• I campi scheda gia visti nella precedente pagina

• Titolo slide
• Flag visualizzazione titolo slide
• Flag visualizzazione titolo storia
• Flag visualizzazione campi scheda (se inserito id archivio/scheda)
• Flag visualizzazione per ogni singolo campo scheda
• Layout di ogni singola scheda (dipende dallo slider che si
sceglierà)
• Parametri vari di configurazione del layout di ciascuna singola
slide (dimensioni area immagine e testo, allineamento, colore
testo, ecc.)
• Parametri testo (dimensioni per le 3 tipologie di testo e margini)
• Parametri immagini (dimensioni e margini)
2.7 Import / export
Le funzionalità attivabili da questa voce di menù sono tre:

• Importazione, anche selettiva, di archivi dai file di configurazione
pubblicati insieme al plugin
• Esportazione di tutte le preferenze salvate dall’utente in un file di
tipo json
• Importazione da file delle preferenze salvate come descritto al
punto precedente
I file di configurazione si intendono i file pubblicati con il plugin e che

descrivono la struttura degli archivi. Il plugin propone alcune
configurazioni ionizialai che possono essere modificate dall’utente.
Per una più dettagliata descrizione di questi file si consiglia la lettura del
manuale avanzato ma nel paragrafo che segue ne anticipiamo una
breve introduzione

regesta.exe srl
vox 0637501056 fax 0637410460
2.7.1 introduzione file di configurazione

La conoscenza dei dettagli relativi a questi file non è necessaria al
corretto funzionamento ma l’obiettivo di questa breve introduzione è di
dare una prima overview dello schema dei dati che possono essere
importati. Tali file sono al momento predefiniti per gli archivi che utilizzano
la modalità standard offerta dall’hosting erogato da regesta. I file si
trovano bella cartella:
Directory dei plugin/WPxdamsBridge/WPxdams_config
Il file principale è il file archive.json che elenca gli archivi e delle tipologie
di schede che si possono gestire. Correlati a questo ci sono, nella
medesima directory, un file specifico per ogni archivio (sempre .json),
utilizzati per descrivere le opzioni dei form di ricerca
Per ogni tipo di scheda infine esistono ulteriori opzioni di configurazione

specificate in ulteriori file XML.
2.7.2 Import di file di configurazione

Una volta arrivati nella pagina specifica ci si trova di fronte all’elenco
degli archivi che si possono aggiornare, cliccando sul flag di selezione si
indica quali archivi saranno importati o re-importati al comando di import.
L’attivazione del comando determinerà la ricopertura di ogni dato già

salvato nel DB con i dati presenti nei file pertanto occorre essere
perfettamente sicuri di volere importare un archivio.
La prima importazione non creerà ovviamene problemi ma una
importazione, successiva alla prima, di archivi già gestiti determinerà la
perdita dei dati preesistenti relativamente ai campi di ricerca e
visualizzazione.
2.7.1 Export settings

Questa funzionalità permette di creare un file di tipo json contenente le
informazioni che sono state memorizzate sul DB mediante tutte le pagine
di configurazione, ovvero le label dei campi, gli indirizzi per le richieste
rest, storie ecc.
Al momento il file denominato savedsettings.json viene allocato in:
Directory dei plugin/WPxdamsBridge/WPxdams_config

regesta.exe srl
vox 0637501056 fax 0637410460
Scopo principale di questa funzione è il back up dei dati e la migrazione

da un’installazione di test a una di produzione o viceversa.
2.7.1 Export settings

Questa funzione è speculare alla precedente e consente di importare sul
DB i dati contenuti nel file savedsettings.json precedentemente descritto e
posizionato nella directory citata al paragrafo precedente.

regesta.exe srl
vox 0637501056 fax 0637410460
3 SHORTCODE
La pubblicazione dei contenuti a questo punto avviene semplicemente
immettendo in un post o in una pagina degli shortcode
3.1 Shortcode disponibili
shortcode descrizione
[xdamsItem type='archive ID' ] xdams item Pubblica una scheda

id [/xdamsItem]
[xdamsImage type='archive ID' ] xdams Pubblica l’immagine allegata di

item id [/xdamsImage] una scheda
[xdamsSearch type='archive ID' ] search Form ricerca fulltext

criteria or nothing [/xdamsSearch]
[xdamsAdSearch type='archive ID' Form ricerca avanzata

][/xdamsADSearch]
[xdamsList type='archive ID' ] search Lista

criteria or nothing [/xdamsList]
[xdamsList type='archive ID' Lista (vocabolario)

vocabulary=’number of occurrences’]
field id [/xdamsList]
[xdamsListImg type='archive ID' ] search Lista con immagini

criteria or nothing [/xdamsListImg]
[xdamsPreview type='fotografico'] search Lista con immagini e preview

criteria or nothing [/xdamsPreview]
[xdamsDynSlider type='fotografico'] Slider

search criteria or nothing
[/xdamsDynSlider]
[xdamsStory type='story ID' Story Telling

height=’maximum height of the slide’
ratio=’fullscreen’ interval=’slides interval’ ]
Story id [/xdamsStory]
[xdamsTree type='archive ID' ] Albero - coming soon

[/xdamsTree]

regesta.exe srl
vox 0637501056 fax 0637410460
shortcode descrizione
[xdamsTree type='archive ID' ] Albero - coming soon

[/xdamsTree]
Esempio di utilizzo shortcode:
[xdamsItem type='fotografico'] IT-xDams-archivioprovincialems-FT0001-000371[/xdamsItem]
3.2 [xdamsItem type='archive ID' ] xdams item id [/xdamsItem]
questo shortcode pubblica una scheda specifica in base ai campi definiti

nel “setting”. La pubblicazione di default utilizza il template standard ma
come detto possono essere definiti template personalizzati.

regesta.exe srl
vox 0637501056 fax 0637410460
Nel caso di schede che prevedano la presenza di immagini di preview

questa viene pubblicata. Se la scheda include anche file da visualizzare
(es .pdf) la lista dei download è presente in basso.
Analogamente nel caso di scheda audiovideo se presente un link a

versione su YouTube è in grado di incorporare automaticamente il player.
3.3 [xdamsImage type='archive ID' ] xdams item id [/xdamsImage]

pubblica l’immagine allegata a una scheda specifica
3.4 [xdamsSearch type='archive ID' ][/xdamsSearch]

Attiva una form di ricerca a testo libero, 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.
Tra tag iniziale e tag finale può essere inserita una o una serie di condizioni
aggiuntive rispetto al testo da cercare, questa opzione può risultare
particolarmente utile se si desidera limitare l’esito della ricerca ai soli
oggetti dell’archivio come nell’esempio che segue:
[xdamsSearch type='storico' form='full']/c/@level=item OR /c/@level=file[/xdamsSearch]
Questa condizione è posta in AND con il testo da cercare per cui occorre
fare attenzione a come descrivere l’opzione stessa. Per evitare poco
comprensibili effetti derivanti dalla differente priorità tra gli operatori logici
al momento sono gestite solo condizioni uguali (tutti AND oppure tutti OR).
Sono previsti i seguenti parametri
listtemplate 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 box di ricerca
form per descrivere il risultato atteso nella pubblicazione accetta tre valori
• basic= inizialmente solo box di ricerca e successivamente risultati e
box di ricerca
• full= box di ricerca e risultati insieme sempre

regesta.exe srl
vox 0637501056 fax 0637410460
• mixed = inizialmente solo box di ricerca e successivamente solo

risultati
3.5 [xdamsAdSearch type='archive ID' ][/xdamsADSearch]

attiva una form di ricerca su campi specifici, sono previste due opzioni:
All, tutti i campi previsti e attivati nel setting

Nome campo specifico, solo il campo indicato
Sono previsti i seguenti parametri

formtemplate per definire quale template di pubblicazione (da predisporsi

a cura dell’utente e posizionato nella directory “custom”) utilizzare per la
pubblicazione del box di ricerca
form per descrivere il risultato atteso nella pubblicazione accetta tre valori
• basic= inizialmente solo box di ricerca e successivamente risultati e
box di ricerca
• full= box di ricerca e risultati insieme sempre
• mixed = inizialmente solo box di ricerca e successivamente solo
risultati
i template per i form di ricerca sono prioritari rispetto a quelli

eventualmente definiti a livello di bacheca
3.6 [xdamsList type='archive ID' ] search criteria or nothing [/xdamsList]

produce una elenco di risultati, paginati e in un formato “lista”, 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.


regesta.exe srl
vox 0637501056 fax 0637410460
i template per la pubblicazione sono prioritari rispetto a quelli

eventualmente definiti a livello di bacheca
3.6.1 Criteri di ricerca:

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 questo shortcode

ma anche per quelli seguenti che prevedono liste di risultati. Vediamo
qualche esempio:
nome campo=valore da ricercare produce lista di risultati

es.:
/c/controlaccess/subject/=spiagge
mentre per la ricerca fulltext occorre seguire la seguente sintassi
@=testo da ricercare
è necessario indicare correttamene tutto l’xpath e possono essere usati

anche AND e OR.
level= tipo scheda pubblica solo schede del tipo richiesto
es. :
/c/@level=item
oppure utilizzando 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.
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.

regesta.exe srl
vox 0637501056 fax 0637410460
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]
3.7 [xdamsList type='archive ID' vocabulary=’number of occurrences’]

field id [/xdamsList]
produce una elenco di risultati, paginati e in un formato “lista”, come nel
caso precedente ma in questo caso il campo field id è mandatorio.
field Id corrisponde all’xpath completo del campo che viene utilizzato

come selettore
number of occurrences = numero di risultati da visualizzare per pagina
il risultato che questo shortcode produce è la lista dei valori presenti nel
campo in oggetto e può essere utilizzato, per esempio, per produrre una
lista degli autori della bibliografia o l’indice dei soggetti.

regesta.exe srl
vox 0637501056 fax 0637410460
esempio: [xdamsList type='biblioB' vocabulary='10'

]/mods/name/namePart/[/xdamsList], elenco di persone relative alla
Bibliografia, 10 risultati per pagina.
3.8 [xdamsListImg type='archive ID' ] search criteria or nothing

[/xdamsListImg]
Concettualmente lavora come il precedente 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.
Per la specifica dei criteri di ricerca si rimanda a quanto già descritto nel
paragrafo precedente relativo allo shortcode “xdamsList”.

regesta.exe srl
vox 0637501056 fax 0637410460
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.
3.9 [xdamsPreview type='fotografico'] search criteria or nothing

[/xdamsPreview]
Questo shortcode pubblica i dati con una modalità diversa da quelli

precedenti, utilizzando una modalità tipo anteprima, ma come i
precedenti possono essere applicati criteri di ricerca con le medesime
proprietà dei precedenti, per esempio il seguente comando:
[xdamsPreview type='fotografico']/c/@level=item[/xdamsPreview]
pubblica solo gli elementi item.

regesta.exe srl
vox 0637501056 fax 0637410460
paragrafo precedente relativo allo shortcode “xdamsList”. Si sottolinea
che anche in questo caso può essere usato il parametro “@all”.
Il menu di paginazione dispone di un comando per alternare la presnte

vista con quella del paragrafo precedente e viceversa.
3.10 [xdamsTree type='archive ID' ] [/xdamsTree] - coming soon

questo shortcode non è attivo al momento ma permetterà la ricerca
gerarchica ovvero da un nodo scoprire tutti i nodi figlio e navigare
ricorsivamente fino alle foglie dell’albero. Sarà dotato di briciole di pane
per risalire ai livelli precedenti.
3.11 [xdamsTree type='archive ID' ] [/xdamsTree] - coming soon

questo shortcode non è attivo al momento ma permetterà la ricerca
gerarchica ovvero da un nodo scoprire tutti i nodi figlio e navigare

regesta.exe srl
vox 0637501056 fax 0637410460
ricorsivamente fino alle foglie dell’albero. Sarà dotato di briciole di pane

per risalire ai livelli precedenti.

regesta.exe srl
vox 0637501056 fax 0637410460
4 WPTOXDAMSSTORIES
WPtoxDamsStories è il plugin introdotto a partire dalla versione 1.2 per

gestire lo story telling e più in generale le funzioni avanzate di
pubblicazione.
Il nuovo plugin presenta una struttura simile per file e cartelle a quello
principale e può funzionare solo se questo è installato e funzionante.
Sulla base di quanto già descritto si possono costruire storie con un

numero di slide variabile e per ogni slide è possibile definire quale tipo di
layout utilizzare. Mediante lo shortcode posso definire per ogni pagina
quale schema narrativo utilizzare e specificarlo nello shortcode.
Compatibilmente con le necessarie personalizzazioni una unica storia può
essere utilizzata con moduli narrativi diversi.
In ogni caso è presente una funzione di duplicazione della storia che

permette di adattare la storia a differenti modi di renderla on line.
Le pagine di amministrazione sono:

• Elenco delle storie
• Elenco delle slide di una storia
• Dettaglio di una singola slide
Non tutti i parametri previsti a livello di slide possono essere utilizzati dai
moduli di narrazione quindi è bene attenersi alle indicazioni relative a tali
layout
4.1 Struttura a template

La creazione o personalizzazione dei moduli narrative è piuttosto semplice
in quanto è stata utilizzata una strategia su due livelli
• Struttura della narrazione

• Struttura della singola slide
4.1.1 Story Renders, la struttura generale di narrazione

Il primo parametro viene configurato direttamente a livello di interfaccia,
come vedremo di seguito, e indica il nome del file che desideriamo

regesta.exe srl
vox 0637501056 fax 0637410460
utilizzare. L’utente finale può seguire le indicazioni presenti in interfaccia e

quindi non preoccuparsi di cosa accade dal punto di vista tecnico.
Utenti più espeti pero possono prendere spunto dai file .php esistenti nella
directorytemplate/storyRender per costruirsi visioni personalizzate,
utilizzando magari template di slideshow disponibili in rete e differenti da
quelli qui utilizzati.
Il codice contiene già tutte le chiamate necessarie all’identificazione dei

dati necessari alla personalizzazione. Il file .php generato deve essere
allocato nella directory citata per essere utilizzato nelle pagine in cui lo
shortcode richiederà il loro utilizzo attraverso i paramteri di configurazione.
4.1.2 Slide Template, struttura della singola slide

Anche il secondo parametro viene configurato direttamente a livello di
interfaccia, e indica anche in questo caso il nome del file che
desideriamo utilizzare. L’utente finale può seguire le indicazioni presenti in
interfaccia e non preoccuparsi di cosa accade dal punto di vista
tecnico.
Utenti più esperti pero possono prendere spunto dai file .php esistenti nella
directory WPxdams_templates/slideTemplate per costruirsi strutture
personalizzate per le proprie slide.
Questi nuovi file .php possono essere allocati nella directory citata e
verranno automaticamente messi a disposizione dell’interfaccia di
gestione
4.2 [xdamsStory] Story id [/xdamsStory]

Sulla base delle stories configurate da back end questo comando
permette di visualizzare un percorso tematico con redazione
Alcune funzioni del plugin (come questa che è stata testata) possono
essere richiamate anche in modo diverso per esempio richiamandola
direttamente in un template utilizzando un campo custom di wordpress

regesta.exe srl
vox 0637501056 fax 0637410460
Il modulo stories permette di utilizzare diversi formati di rendering della

storia contraddistinti da differenti codici con cui viene valorizzato il
parametro type
default scorrimento delle slide in un solo verso senza preview delle

rimanenti (come nella foto). Sono utilizzabili solo i campi presenti nella
pagina elenco delle slide.
fixRender scorrimento delle slide con preview delle rimanenti e possibilità

di reindirizzare una specifica slide quale immagine ingrandita,
(personalizzabile a livello di slide è caratterizzato da altezza fissa della slide
per ottenere la migliore personalizzazione in caso di installazioni specifiche
responsiveSlider scorrimento delle slide con preview delle rimanenti e

possibilità di reindirizzare una specifica slide quale immagine ingrandita
personalizzabile a livello di slide è caratterizzato da altezza variabile della
slide per gestire la pubblicazione responsive sul web
fixRender pubblicazione verticale delle slide, personalizzabile a livello di

slide è caratterizzato da altezza fissa della slide
Lo shortcode da utilizzare utilizza quattro parametri

regesta.exe srl
vox 0637501056 fax 0637410460
[xdamsStory type='default' height='800' interval='6000']1[/xdamsStory]
Di seguito le impostazioni possibili:
• nel campo tra i codici viene specificati l’id della storia che si
intende pubblicare (nell’esempio “1”)
• ratio deve essere nella forma ratio=’fullscreen’ per consentire una
gestione dei post in formato fullscreen
• heigth altezza della slide, utilizzato solo da fixRender ed espresso in
pixel (inserire solo il numero!)
• Type indica quale tipo di slideshow si intende utilizzare
• interval determina il tempo in cui ogni slide rimane in primo piano
4.3 Parametri di personalizzazione delle slide

È possibile definire:
• id archivio combinato a id scheda

• url per immagine alternativa
• testo HTML alternativo all’immagine
• titolo della slide e opzione di pubblicazione
• descrizione
• flag pubblicazione dei metadata
• flag di pubblicazione per ognuno dei singoli tipi di metadati
• inserimento del titolo della storia
• tipo di slide layout
• allineamento testo
• colore testo
• dimensioni dell’area testo (attenzione il valore 100% impedisce la
pubblicazione delle immagini)
• dimensione del font per tipologia di testo
• margine dal top per tipologia di testo
• allineamento della fotografia
• dimensione massima della foto (questo campo lavora solo su una
dimensione al momento quindi specificare in base all’orientamento
dell’immagine). I senso di questo campo è definire una dimensione
stabile per le fotografie nel caso di layout completamente
responsive, non è utilizzato da fixrender

regesta.exe srl
vox 0637501056 fax 0637410460
4.4 [xdamsDynSlider type='fotografico'] search criteria or nothing

[/xdamsDynSlider]
Questo shortcode ha gli stessi criteri di ricerca di quelli relativi alle liste di
risultati ma pubblica i dati con utilizzando un javascript per rendere più
interattiva l’esperienza utente.
L’anteprima dell’immagine è di dimensioni più contenute rispetto alla
preview descritta al paragrafo precedente
paragrafo precedente relativo allo shortcode “xdamsList”. Si sottolinea
che anche in queesto caso può essere usato il parametro “@all”.

WPToXdamsBridge2017 001 Usersmanual 03 0

Caricato da

Informazioni sul documento

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

WPToXdamsBridge2017 001 Usersmanual 03 0

Caricato da

Copyright:

Formati disponibili

regesta.

WPxdamsBridge Basic Manual

codice fiscale - Partita Iva - Iscrizione Reg. Imprese di Roma 09825831002

Descrizione Manuale di istruzioni sull’uso del plugin di bridge tra xDams e

Riferimenti esterni Versione del plugin 2.0

Autori Carlo Bruno (CB)

Nome File WPToXdamsBridge2017_001_usersManual_03_0.docx

Pagine / versione 37 / 3.0

è un prodotto open source coperto da GNU Free Documentation License e

WPxdams2017_01 Plugin xDams to Wordpress Manuale base v 3.0 2

WPxdams2017_01 Plugin xDams to Wordpress Manuale base v 3.0 3

WPxdams2017_01 Plugin xDams to Wordpress Manuale base v 3.0 4

4.1 Struttura a template ...................................................................................................................33

WPxdams2017_01 Plugin xDams to Wordpress Manuale base v 3.0 5

xDams Open Source Platform è una soluzione software realizzata da

regesta.exe ha inoltre realizzato Il plugin per Wordpress, rilasciato con

E’ già possibile pubblicare, mediante il presente plugin. archivi ospitati dal

Il materiale informativo è suddiviso in due differenti documenti:

• Manuale utente di base (il presente documento)

La finalità principale è quella di consentire la promozione e diffusione del

WPxdams2017_01 Plugin xDams to Wordpress Manuale base v 3.0 6

Questa integrazione consente pertanto la gestione, sulla medesima

1.1 Altri strumenti di supporto

• wiki di progetto con tutte le informazioni qui incluse –

• sito demo live con dati estratti da archivi realmente esistenti –

• forum sul sito www.xdams.org per fare richieste di supporto al team

• video tutorial sul canale YouTube di xDams

1.2 Struttura del documento

La configurazione standard predisposta permette l’utilizzo di tutte ò

Le due sezioni descrivono tutte le funzionalità che consentono a un

Agli utenti più esperti però il plugin consente anche di personalizzare

WPxdams2017_01 Plugin xDams to Wordpress Manuale base v 3.0 7

utilizzabili al posto di quelli standard utilizzando semplici API pubbliche.

Pertanto l’utente che desidera concentrarsi solo sulle funzionalità più

1.2.1 SUMMARY funzioni

L’attività di configurazione di base permette di:

La pubblicazione è estremamente semplificata in quanto, grazie a

• form di ricerca testuale

Il plugin è infine predisposto per

WPxdams2017_01 Plugin xDams to Wordpress Manuale base v 3.0 8

• Configurazione generale (general settings)

Sono inoltre disponibili funzionalità di

Il passo stories è opzionale e consente ti predisporre mostre e percorsi

2.1 Configurazione PHP (obsoleto dalla versione 2.0)

Pertanto dalla versione 2.0 non è più necessaria alcuna configurazione

2.1.1 Versioni precedenti alla 2.0 (deprecato)

che deve essere attivo (“on”).

WPxdams2017_01 Plugin xDams to Wordpress Manuale base v 3.0 9

2.2 General Setting

WPxdams2017_01 Plugin xDams to Wordpress Manuale base v 3.0 10

La prima operazione consiste nel configurare le opzioni generali (voce fi

• Import and Update

Se sei alla prima installazione occorre premere il pulsante “Import and

2.3 Search form

• Se un singolo archivio è visibile

WPxdams2017_01 Plugin xDams to Wordpress Manuale base v 3.0 11

WPxdams2017_01 Plugin xDams to Wordpress Manuale base v 3.0 12

E’ possibile infatti costruirsi delle proprie maschere di ricerca e

Di default vengono utilizzati template standard nella directory

“Directory dei plugin/WPxdamsBridge/WPxdams_template”

possono essere posizionati i file custom. Nel caso di personalizzazioni del

2.3.1 Walk around form di ricerca

Ragionamento analogo può essere applicato nel caso della