ProtocolloACDFv9 < TechWeb06

TechWeb06
TechWeb06.ProtocolloACDFv9r1.4 - 25 Oct 2006 - 17:24 - MatteoMinghettitopic end
---+!! Protocollo AC-DF versione 9

Questo documento descrive il protocollo AC-DF versione 9 (6 ottobre 2006).

I cambiamenti dalle versioni precedenti sono riassunti in [[#DifferenzePrecVersioni][un'apposita sezione alla fine di questo documento]].

%TOC%

-------

---++ 5 Catalogo DF

Il catalogo DF contiene le metainformazioni relative al formatter stesso.

Il catalogo di un formatter si ottiene attraverso una richiesta HTTP GET del documento disponibile all'URL stabilito e reso pubblico da ogni gruppo al momento della registrazione (nella sezione 8 sono riportate le regole per la registrazione dei data-source e dei formatter).

Si assuma ad esempio che nel wiki sia registrato il seguente formatter:

| *Nome* | *Catalogo XML* | *Catalogo HTML* |
| TWFormatter | http://tw.web.cs.unibo.it/catalogo-formatter.xml | http://tw.web.cs.unibo.it/catalogo-formatter.html |

L'URL che gli AC devono utilizzare per la richiesta del catalogo è appunto =http://tw.web.cs.unibo.it/catalogo-formatter.xml=.

Si noti che il catalogo è un documento XML (application/xml) e può essere statico o dinamico. Inoltre è necessario fornire anche una versione human-readable (HTML o XHTML) dello stesso.

Come per il DS, anche nel caso del DF il ruolo del catalogo è fondamentale: per *ogni* richiesta l'AC *deve* consultare il catalogo del DF e recuperare l'URL completo degli script attraverso i quali richiedere l'elenco dei layout o la formattazione di un documento. Sebbene sia possibile implementare meccanismi di caching, è *obbligatorio* recuperare dinamicamente gli URL degli script dal catalogo.

---+++ 5.1 Formato del catalogo DF

All'interno del catalogo DF le metainformazioni sul formatter sono espresse tramite i sequenti elementi:
   * =nome=: il nome del formatter
   * =tipo=: il tipo di output prodotto. Ogni formatter dichiara il content-type del risultato che produce, specificando un tipo MIME. Valori possibili: text/html per le pagine HTML, application/pdf per i file PDF, application/xhtml+xml per documenti XHTML, etc. È possibile personalizzare il tipo di dato prodotto ed aggiungere altri tipi a questo elenco.
   * =descrizione=: una descrizione human-readable del formatter, del tipo di dati che produce, eventualmente note su autori, implementazione o altre informazioni.
   * =urlElenco=: l'URL al quale richiedere l'elenco dei layout disponibili (vedi sezione 6.1)
   * =urlFormattazionePagina=: l'URL al quale POSTare un elenco di dati da formattare, (vedi sezione 6.2)
   * =urlFormattazioneFrammento=: l'URL al quale POSTare i dati da formattare in frammenti utilizzabili dall'AC client-side (vedi sezione 6.3)
   * =variabileDatiFormattazione=: il nome della variabile da POSTare agli script specificati in =urlFormattazionePagina= e =urlFormattazioneFrammento= (vedi sezione 6.2 e 6.3)

Gli URL contenuti in =urlElenco=, =urlFormattazionePagina= e =urlFormattazioneFrammento= non devono contenere la parte di query (=?var1=xxx&var2=yyy=).

Di seguito è riportato un esempio di catalogo di un formatter:
<verbatim>
<catalogoFormatter>
  <nome>TWformatter</nome>
  <tipo>application/pdf</tipo>
  <descrizione>Un efficiente e ricco formatter PDF</descrizione>
  <urlElenco>http://tw.web.cs.unibo.it/elenco-layout.php</urlElenco>
  <urlFormattazionePagina>http://tw.web.cs.unibo.it/formatter-pagina.php</urlFormattazionePagina>
  <urlFormattazioneFrammento>http://tw.web.cs.unibo.it/formatter-frammento.php</urlFormattazioneFrammento>
  <variabileDatiFormattazione>dati_da_formattare</variabileDatiFormattazione>
</catalogoFormatter>
</verbatim>

---+++ 5.2 Schema Relax NG del catalogo DF

I cataloghi XML devono essere validati dal seguente schema Relax NG (disponibile online in sintassi compatta all'URL http://ltw06_01.web.cs.unibo.it/wg-df/schema_formatter-6/catalogoFormatter.rnc ed in sintassi XML all'URL http://ltw06_01.web.cs.unibo.it/wg-df/schema_formatter-6/catalogoFormatter.rng):

<verbatim>
start = catalogoFormatter

catalogoFormatter = element catalogoFormatter {
        element nome { text },
        element tipo { text },
        element descrizione { testo.cmSemplice },
        element urlElenco { xsd:anyURI },
        element urlFormattazionePagina { xsd:anyURI },
        element urlFormattazioneFrammento { xsd:anyURI },
        element variabileDatiFormattazione { xsd:NMTOKEN }
}
</verbatim>

---++ 6 Richieste al data formatter

Come specificato alla sezione 2, l'applicazione può inoltrare tre tipi di richieste al formatter:
   * _elenco_ dei layout disponibili;
   * _formattazione_ di dati _in un unico documento_ (si noti che tutti i documenti devono essere formattati dal DF);
   * _formattazione_ di dati _in un frammento di documento_ (si noti che tutti i frammenti di documenti devono essere formattati dal DF).

Nelle sottosezioni successive sono riportate le specifiche dettagliate e complete del protocollo AC-DF.

---+++ 6.1 Elenco dei layout

L'elenco dei layout contiene la lista dei layout resi disponibili dal formatter e delle skin associate ad ogni layout.

L'elenco dei layout si ottiene attraverso una richiesta HTTP GET del documento il cui URL è specificato dall'elemento =urlElenco= del catalogo del formatter. Si rimanda alla sezione 5 per una descrizione dettagliata del catalogo.

Prendendo ad esempio il catalogo descritto nella sezione 5.1, per ottenere l'elenco dei layout, l'applicazione richiede la risorsa =http://tw.web.cs.unibo.it/elenco-layout.php= ed il formatter risponde con l'elenco dei layout disponibili, in un documento XML secondo le specifiche riportate nella sezione 7.1.


---+++ 6.2 Formattazione di dati XML in un documento completo

La richiesta di formattazione di dati XML in documento completo è realizzata tramite un POST HTTP allo script indicato nel catalogo col tag =urlFormattazionePagina=. L'applicazione spedisce in una variabile, il cui nome è specificato dal tag del catalogo =variabileDatiFormattazione=, un documento XML dal quale il formatter estrae sia i dati da formattare che i parametri di formattazione.

Si consideri il catalogo di esempio riportato nella sezione 5.1: l'applicazione fa un POST HTTP allo script =http://tw.web.cs.unibo.it/formatter-pagina.php= e spedisce nella variabile =dati_da_formattare= la richiesta XML.

Si ricorda che i formatter deve essere utilizzati anche per generare tutte le pagine del progetto, ad eccezione dei cataloghi. Questo significa che la pagina iniziale, la pagina della ricerca e le altre pagine devono essere formattate da un formatter.

---++++ 6.2.1 Dati da formattare

La richiesta è suddivisa in due parti:
   * =info=: contiene le informazioni relative al layout scelto ed al meccanismo di iniezione del codice dell'AC client-side nell'output; 
   * =dati=: sono i dati da formattare.

Le informazioni passate in =info= sono tre:
   * =layout=: l'attributo =id= di questo elemento indica quale layout utilizzare tra quelli messi a disposizione dal formatter nel catalogo;
   * =skin=: l'attributo =id= di questo elemento indica quale skin usare per decorare il layout scelto;
   * =ajax=: contiene le informazioni sull'URL del codice dell'AC client-side (nel sotto-elemento =urlAC=) e su quale metodo gestisce l'avvio dell'AC (nel sotto-elemento =codiceIniziale=).

L'id del layout deve essere selezionato dall'AC tra i layout disponibili ottenuti con la richiesta catalogo. Allo stesso modo l'id della skin deve essere scelto tra gli id delle skin associate al layout selezionato.

L'elemento =ajax= può essere omesso se l'AC server-side ritiene che lo user-agent non sia in grado di supportare la tecnologia Ajax.

I dati da formattare contenuti in =dati= possono essere di vari tipi:
   * =elenco=, =scheda=: i dati ottenuti dall'output del data-source. Possono essere anche un sottoinsieme o una versione modificata dei dati restituiti dai DS. Ad alcuni elementi possono essere aggiunti degli attributi per contenere collegamenti ad altre risorse, come descrito nella sezione 6.2.2;
   * =titolo=: un testo che descrive la pagina da formattare;
   * =query=: degli elementi che descrivono una maschera con la quale interrogare l'AC;
   * =menuContestuale=: una serie di elementi correlati ad una risorsa presente all'interno degli elementi =elenco= e =scheda=;
   * =menuStatico=: una serie di elementi (=testo= o =link=) che formano un menu con contenuti statici non legati ai dati presenti in =elenco= o =scheda=;
   * =contenutoStatico=: alcuni elementi che forniscono informazioni statiche aggiuntive (credit, link alle pagine di aiuto, ecc).

Questi elementi sono descritti in dettaglio nelle sottosezioni seguenti.

Di seguito è riportato un esempio di richiesta: l'applicazione chiede al formatter di applicare ai dati contenuti nel nodo =dati= il layout con =id=12= ed aggiungere la skin indicata da =id=cool=.

<verbatim>
<formatta>
    <info>
        <layout id="12"/>
        <skin id="cool"/>
    </info>
    <dati>
        <elenco>
          <scheda id="1">...</scheda>
          <scheda id="2">...</scheda>
        </elenco>
        <titolo>Risultato della ricerca</titolo>
        <query>
            <form>
                <label for="cognome">Cognome :</label>
                <input name="cognome" type="text"/>
                <input type="submit" value="Ricerca"/>
            </form>
        </query>
        <contenutoStatico tipo="crediti">
            Prodotto dall'AC LTW e dal formatter del gruppo LTW3
        </contenutoStatico>
    </dati>
</formatta>
</verbatim>

Il formatter risponde a tale richiesta e spedisce il documento finale (pronto per la visualizzazione), secondo le specifiche riportate nella sezione 7.2.

---++++ 6.2.1.1 L'elemento =titolo=

L'elemento =titolo= indica quale titolo è associato ai dati che l'AC sta spedendo al formatter.

L'uso classico del contenuto di questo elemento è come =title= nelle pagine HTML o come titolo con un font particolare nei PDF.

---+++++!! 6.2.1.1.1 Esempi per l'elemento =titolo=

Un esempio di =titolo= associato ad una scheda:
<verbatim>
<formatta>
    <info>...</info>
    <dati>
        <scheda>
            <titolo>Le città invisibili<titolo>
            <autore>Italo Calvino</autore>
        </scheda>
        <titolo>Scheda del libro <em>Le città invisibili</em></titolo>
    </dati>
</formatta>
</verbatim>

Un esempio di =titolo= associato ad un elenco:
<verbatim>
<formatta>
    <info>...</info>
    <dati>
        <elenco>
            <scheda id="1">
                <titolo>La cantatrice calva</titolo>
            </scheda>
            <scheda id="2">
                <titolo>Teatro 2</titolo>
            </scheda>
            <scheda id="3">
                <titolo>Il giuoco dell'epidemia</titolo>
            </scheda>
        </elenco>
        <titolo>Libri di Eugène Ionesco pubblicati prima del 1972</titolo>
    </dati>
</formatta>
</verbatim>

---++++ 6.2.1.2 L'elemento =query=

Ogni elemento =query= indentifica una form con la quale l'utente può contattare l'AC.

L'attributo opzionale =titolo= indica il titolo della form contenuta.

L'attributo opzionale =tipo= permette di indicare al formatter che la form contenuta rappresenta una query particolare che dovrebbe essere presenta in un modo diverso dal normale. Se l'attributo =tipo= non è presente, allora la form contenuta rappresenta una query generica.
Esistono due valori possibili per l'attributo =tipo=:
   * =ricercaVeloce=: sono le quick search in cui un certo numero di elementi è preprogrammato; solitamente queste query sono visualizzate in un piccolo spazio;
   * =sceltaLayout=: la form contenuta è utilizzata per impostare il layout e la skin da usare e non per effettuare una ricerca sui dati.

L'unico elemento ammesso in =query= è l'elemento HTML =form= molto simile al corrispettivo HTML ma senza gli attributi presentazionali come =id= e =style=.

---+++++!! 6.2.1.2.1 Particolarità dell'elemento =form=

L'elemento =form= contenuto in query si differenzia dall'elemento =form= di HTML per due particolarità:
   * l'attributo =for= delle label è collegato al =name= e non all'=id= degli elementi =input= a cui si riferiscono;
   * non è possibile avere del testo libero in =form=; per inserire del testo bisogna usare l'elemento =testo= ed indicare nel suo attributo =for= il =name= dell'elemento a cui si riferisce il testo contenuto.

---+++++!! 6.2.1.2.2 Esempi dell'elemento =query=

Un esempio di richiesta con una =query= generica:
<verbatim>
<formatta>
    <info>...</info>
    <dati>
        <titolo>Form di ricerca</titolo>
        <query>
            <form action="http://ltw.web.cs.unibo.it/query.php5" method="post">
                <label for="autore">Autore del libro</label>
                <input type="text" name="autore"/>
                <testo for="autore">Il nome o il cognome dell'autore</testo>
                <label for="titolo">Titolo del libro</label>
                <input type="text" name="titolo"/>
                <input type="submit" value="Cerca!"/>
            </form>
        </query>
    </dati>
</formatta>
</verbatim>

Un esempio di richiesta con più =query=:
<verbatim>
<formatta>
    <info>...</info>
    <dati>
        <titolo>Form di ricerca</titolo>
        <query titolo="Ricerca semplice">
            <form action="http://ltw.web.cs.unibo.it/query.php5" method="post">
                <label for="autore">Autore del libro</label>
                <input type="text" name="autore"/>
                <testo for="autore">Il nome o il cognome dell'autore</testo>
                <label for="titolo">Titolo del libro</label>
                <input type="text" name="titolo"/>
                <input type="submit" value="Cerca!"/>
            </form>
        </query>
        <query titolo="Ricerca avanzata">
            <form action="http://ltw.web.cs.unibo.it/query.php5" method="post">
                <label for="autore">Autore del libro</label>
                <input type="text" name="autore"/>
                <testo for="autore">Il nome o il cognome dell'autore</testo>
                <label for="titolo">Titolo del libro</label>
                <input type="text" name="titolo"/>
                <label for="anno">Anno di pubblicazione</label>
                <input type="text" name="anno"/>
                <label for="editore">Editore</label>
                <input type="text" name="editore"/>
                <input type="submit" value="Cerca!"/>
            </form>
        </query>
    </dati>
</formatta>
</verbatim>


Un esempio di richiesta con più =query= e l'attributo =tipo=:
<verbatim>
<formatta>
    <info>...</info>
    <dati>
        <elenco>
            <scheda id="1">...</scheda>
            <scheda id="2">...</scheda>
            <scheda id="3">...</scheda>
        </elenco>
        <titolo>Risultato della ricerca per "Trilussa"</titolo>
        <query titolo="Altra ricerca">
            <form action="http://ltw.web.cs.unibo.it/query.php5" method="post">
                <label for="autore">Autore del libro</label>
                <input type="text" name="autore"/>
                <testo for="autore">Il nome o il cognome dell'autore</testo>
                <label for="titolo">Titolo del libro</label>
                <input type="text" name="titolo"/>
                <input type="submit" value="Cerca!"/>
            </form>
        </query>
        <query tipo="ricercaVeloce" titolo="Altri libri di 'Trilussa'">
            <form action="http://ltw.web.cs.unibo.it/query.php5" method="post">
                <input type="hidden" name="autore" value="Trilussa"/>
                <label for="titolo">Titolo</label>
                <input type="text" name="titolo"/>
            </form>
        </query>
    </dati>
</formatta>
</verbatim>

---++++ 6.2.1.3 L'elemento =menuContestuale=

In un =menuContestuale= possono essere inserite delle informazioni aggiuntive su una risorsa. Ogni =menuContestuale= è identificato da un attributo obbligatorio =codice= che contiene una stringa univoca all'interno di ogni richiesta.

Le informazioni aggiuntive che possono essere specificate tramite un =menuContestuale= si trovano nei suoi sottoelementi:
   * =elementiCorrelati=: gli stessi elementi presenti in =elenco= e =scheda= a cui stato aggiunto l'attributo =href=;
   * =navigazione=: una lista di link =precedente= / =successivo= che descrivono un percorso di navigazione a partire da quella risorsa;
   * =altriLink=: una serie di =link=  arbitrari.

Nella sezione 6.2.2 ci sono alcuni esempi su come utilizzare un =menuContestuale= collegandolo ad uno o più elementi di una =scheda= o di un =elenco=

---++++ 6.2.1.4 L'elemento =menuStatico=

Un =menuStatico= rappresenta una serie di link a risorse non collegate con la scheda o l'elenco di voci mostrate all'utente.

L'attributo opzionale =titolo= indica il titolo del =menuStatico=.

All'interno di un elemento =menuStatico= possono essere presenti solo degli elementi =link=

---+++++!! 6.2.1.4.1 Esempi dell'elemento =menuStatico=

Un esempio di =menuStatico=
<verbatim>
<formatta>
    <info>...</info>
    <dati>
        <titolo>Form di ricerca</titolo>
        <menuStatico titolo="Link interessanti">
            <link href="http://ltw.web.cs.unibo.it">L'home page del gruppo</link>
            <link href="http://pinuccio.blogspot.com">Il blog di Pinuccio</link>
            <link href="http://mindraider.sf.net/">
                Mindreader, il programma con cui abbiamo scritto gli RDF
            </link>
        </menuStatico>
        <query>
            <form action="http://ltw.web.cs.unibo.it/query.php5" method="post">
                <label for="autore">Autore del libro</label>
                <input type="text" name="autore"/>
                <input type="submit" value="Cerca!"/>
            </form>
        </query>
    </dati>
</formatta>
</verbatim>

---++++ 6.2.1.5 L'elemento =contenutoStatico=

Gli elementi =contenutoStatico= possono essere usati per indicare degli elementi statici spesso utilizzati per decorare le pagine statiche.

L'attributo opzionale =tipo= permette di indicare al formatter che gli elementi contenuti in certo =contenutoStatico= hanno significato particolare e dovrebbero essere presenti in maniera diversa dai normali =contenutoStatico=. Quando l'attributo =tipo= non è presente il =contenutoStatico= contiene dei contenuti generici da formattare a piacimento del formatter.
Esistono due valori possibili per l'attributo =tipo=:
   * =intestazione=: gli elementi presenti dentro al =contenutoStatico= vanno intesi come testata o intestazione della pagina;
   * =crediti=: gli elementi rappresentano i crediti della pagina ed andrebbero visualizzati in maniera consona.

All'interno di =contenutoStatico=, insieme al semplice testo, possono essere utilizzati questi elementi, praticamente identici ai corrispettivi HTML:
   * =testo=: un blocco di testo decorato con altri elementi come =em= o =span=;
   * =link=: un link ad una risorsa esterna;
   * =img=: un'immagine;
   * =ul= e =ol=: liste in cui l'ordine degli elementi (=li=) non conta, liste =ul=, e liste in cui l'ordine conta, liste =ol=;
   * =table=: una tabella;
   * =h1= ... =h6=: un titolo.

---+++++!! 6.2.1.5.1 Esempi dell'elemento =contenutoStatico=

Un esempio di =contenutoStatico= generico
<verbatim>
<formatta>
    <info>...</info>
    <dati>
        <titolo>Help</titolo>
        <contenutoStatico titolo="Come funziona la pagina di ricerca">
            <testo>
                Per utilizzare la pagina di ricerca bisogna inserire il
                <em>Cognome</em> di un autore o il <em>titolo</em> di
                un'opera.
            </testo>
            <testo>
                È possibile cambiare l'aspetto delle pagine impostando
                un <em>layout</em> ed un <em>layout</em> tramite
                l'apposita combo-box.
            </testo>
            <table>
                <thead>
                    <tr>
                        <td>Nome layout</td><td>Gruppo del formatter</td>
                    </tr>
                <thead>
                <tbody>
                    <tr>
                        <td>Minimal chic</td><td>Gruppo LTW4</td>
                    </tr>
                    <tr>
                        <td>"A Caso"-layout</td><td>Gruppo LTW6</td>
                    </tr>
                </tbody>
            </table>
        </contenutoStatico>
    </dati>
</formatta>
</verbatim>

Un esempio di =contenutoStatico= con =tipo=
<verbatim>
<formatta>
    <info>...</info>
    <dati>
        <titolo>Form di ricerca</titolo>
        <query>
            <form action="http://ltw.web.cs.unibo.it/query.php5" method="post">
                <label for="autore">Autore del libro</label>
                <input type="text" name="autore"/>
                <input type="submit" value="Cerca!"/>
            </form>
        </query>
        <contenutoStatico tipo="intestazione">
            <testo>Progetto TW2006 del gruppo LTW</testo>
            <img src="http://ltw.web.cs.unibo.it/logo.png" alt="Logo LTW"/>
        </contenutoStatico>
        <contenutoStatico tipo="crediti">
            <ul>
                <li>Realizzato dal gruppo LTW</li>
                <li>I componenti del gruppo: Gianni, Pinotto, Franco e Ciccio</li>
            </ul>
        </contenutoStatico>
    </dati>
</formatta>
</verbatim>

---++++ 6.2.2 Aggiunta di informazioni contestuali ai dati di =scheda= e =elenco=

È possibile arricchiere i dati ricevuti dai DS con informazioni aggiuntive.

Per fare questo si possono aggiungere vari attributi opzionali a =scheda= *privato dell'attributo =cod=*, =elenco= ed ai loro sotto-elementi.

Questi attributi aggiuntivi sono tre:
   * =href=: un URL che contiene una risorsa strettamente collegata all'elemento d'appartenenza;
   * =descrizione=: un testo che descrive l'URL contenuta in =href=;
   * =altreInfo=: il valore dell'attributo =codice= dell'elemento =menuContestuale= che contiene altre informazioni correlate all'elemento d'appartenenza.

Un esempio dell'uso di questi attributi è
<verbatim>
<formatta>
    <info>...</info>
    <dati>
<!-- il prossimo elemento si legge: Ci sono informazioni aggiuntive
     sulla <scheda/> e queste informazioni sono nel menuContestuale che ha come
     attributo codice la stringa 'infoFrancesca'. -->
        <scheda altreInfo="infoFrancesca">
            <dati>
                <titolo>Si chiama Francesca questo romanzo</titolo>

<!-- il prossimo elemento si legge: L'<autore/>Paolo Nori</> è strettamente legato
     all'URL http://ltw.web.cs.unibo.it/query.php?autore=Paolo+Nori al quale è possible
     trovare 'Altri libri di Paolo Nori'. Inoltre ci sono informazioni aggiuntive
     sull'<autore>Paolo Nori</> e queste informazioni sono nel menuContestuale che ha
     come codice la stringa 'infoNori'. -->
                <autore href="http://ltw.web.cs.unibo.it/query.php?autore=Paolo+Nori"
                        descrizione="Altri libri di Paolo Nori"
                        altreInfo="infoNori">Paolo Nori</autore>
            </dati>
        </scheda>



        <menuContestuale codice="infoNori">
            <altriLink>

<!-- il prossimo elemento si legge: Alle risorse collegate a questo menuContestuale
     è associato il sito 'Il sito preferito da Paolo Nori' raggiungibile all'URL
     http://clarence.com. -->
                <link href="http://clarence.com">Il sito preferito da Paolo Nori</link>
            </altriLink>
            <navigazione>

<!-- il prossimo elemento si legge: Le risorse collegate a questo menuContestuale
     hanno come precedente l'URL http://ltw.web.cs.unibo.it/query.php?più_giovane_di=Paolo+Nori
     che ha come titolo 'Scrittori più giovani di Paolo Nori'. -->
                <precedente href="http://ltw.web.cs.unibo.it/query.php?più_giovane_di=Paolo+Nori">
                    Scrittori più giovani di Paolo Nori
                </precedente>
            </navigazione>
        </menuContestuale>



        <menuContestuale codice="infoFrancesca">
            <elementiCorrelati>

<!-- il prossimo elemento si legge: Alle risorse collegate a questo menuContestuale
     è associato l'autore 'Julio Cortázar' raggiungibile all'URL 
     http://ltw.web.cs.unibo.it/query.php?autore=Julio+Cortázar -->
                <autore href="http://ltw.web.cs.unibo.it/query.php?autore=Julio+Cortázar">
                    Julio Cortázar
                </autore>
            </elementiCorrelati>
            <navigazione>

<!-- i prossimi elementi si leggono: Le risorse collegate a questo menuContestuale
     hanno come precedenti 'Le cose non sono le cose' (http://ltw.web.cs.unibo.it/scheda.php?id=17) e
     'Grandi ustionati' (http://ltw.web.cs.unibo.it/scheda.php?id=1928) e
     come successivo 'Gli scarti' (http://ltw.web.cs.unibo.it/scheda.php?id=2973) -->
                <precedente href="http://ltw.web.cs.unibo.it/scheda.php?id=17">
                    Le cose non sono le cose
                </precedente>
                <precedente href="http://ltw.web.cs.unibo.it/scheda.php?id=1928">
                    Grandi ustionati
                </precedente>
                <successivo href="http://ltw.web.cs.unibo.it/scheda.php?id=2973">
                    Gli scarti
                </successivo>
            </navigazione>
            <altriLink>

<!-- il prossimo elemento si legge: Alle risorse collegate a questo menuContestuale
     è associato il sito 'Sito ufficiale' raggiungibile all'URL
     http://paolonori.it. -->
                <link href="http://paolonori.it">Sito ufficiale</link>
            </altriLink>
        </menuContestuale>
    </dati>
</formatta>
</verbatim>

---++++ 6.2.3 Esempi di richieste di formattazione dati

Un esempio di richiesta è

<verbatim>
<formatta>
<info>
    <layout id="completo"/>
    <skin id="primavera"/>
</info>
<dati>
    <scheda>
        <info>
            <id>scheda20</id>
            <team>LTW</team>
            <originale>originale</originale>
        </info>
        <dati>
            <titolo>Brillano nel buio</titolo>
            <anno>2005</anno>
            <autore href="http://www.lorenzo.it"
                    descrizione="Sito ufficiale di Lorenzo Bartoli">Lorenzo Bartoli</autore>
            <autore>Roberto Recchioni</autore>
            <genere href="http://ltw.web.cs.unibo.it/r.php5?genere=fumetti"
                    descrizione="Altri fumetti">fumetti</genere>
            <testo>
                <trama>
                    <personaggio href="http://it.wikipedia.org/John_Doe"
                                 descrizione="Wikipedia su John Doe"
                                 altreInfo="collanaJohnDoe">John
                    Doe</personaggio> finisce a
                    <luogo altreInfo="luogoHartford">Hartford</luogo> per
                    cercare una vecchia conoscenza.
                </trama>
            </testo>
        </dati>
    </scheda>
    <titolo>Scheda di <em>John Doe - Brillano nel buio</em></titolo>
    <query>
        <form action="http://ltw.cs.unibo.it/r.php5" method="post">
            <label for="titolo">Titolo :</label>
            <input type="text" name="titolo"/>
            <input type="submit" value="Cerca"/>
        </form>
    </query>
    <menuContestuale codice="collanaJohnDoe">
        <elementiCorrelati>
            <!-- il prossimo elemento si legge "al <personaggio>John Doe</>
                 è collegata la <ricerca> intitolata 'Tutti i volumi della
                 collana John Doe' che si trova all'URL
                 'http://ltw.cs.unibo.it/r.php5?collana=John+Doe'" -->
            <ricerca href="http://ltw.cs.unibo.it/r.php5?collana=John+Doe">
                Tutti i volumi della collana John Doe
            </ricerca>

            <!-- il prossimo elemento si legge "al <personaggio>John Doe</>
                 è collegato il <genere>noire</> che si trova all'URL
                 'http://ltw.cs.unibo.it/r.php5?genere=Noir'" -->
            <genere href="http://ltw.cs.unibo.it/r.php5?genere=Noir">noir</genere>

            <!-- il prossimo elemento si legge "al <personaggio>John Doe</>
                 è collegato il <personaggio>Dylan Dog</> che si trova
                 all'URL 'http://ltw.cs.unibo.it/r.php5?personaggio=Dylan+Dog'" -->
            <personaggio href="http://ltw.cs.unibo.it/r.php5?personaggio=Dylan+Dog">
                Dylan Dog
            </personaggio>
        </elementiCorrelati>
        <altriLink>
            <link href="http://ltw.cs.unibo.it/r.php5?iniziaCon=J">Altri libri che iniziano con J</link>
        </altriLink>
    </menuContestuale>
    <menuContestuale codice="luogoHartford">
        <altriLink>
            <link href="http://maps.google.com/q=Hartford">Cerca Hartford su Google Maps</link>
        </altriLink>
    </menuContestuale>
    <contenutoStatico>
        Stai usando l'AC del gruppo
        <link href="http://ltw.web.cs.unibo.it">LTW</link>
    </contenutoStatico>
</dati>
</formatta>
</verbatim>

---++++ 6.2.4 Schema Relax NG della richiesta di formattazione dati

I dati spediti ai formatter per richiedere la formattazione di dati provenienti dal DS devono essere validati dal seguente schema Relax NG (disponibile online in sintassi compatta all'URL http://ltw06_01.web.cs.unibo.it/wg-df/schema_formatter-6/formatta.rnc ed in sintassi XML all'URL http://ltw06_01.web.cs.unibo.it/wg-df/schema_formatter-6/formatta.rng):

<verbatim>
start = formatta

formatta = element formatta {
        element info { info.cm },
        element dati { dati.cm }
}

info.cm =
        element layout { attribute id { xsd:NMTOKEN }, empty },
        element skin { attribute id { xsd:NMTOKEN }, empty },
        element ajax { ajax.cm }?

        ajax.cm =
                element urlAC { xsd:anyURI },
                element codiceIniziale { text }

dati.cm =
        elencoConHRefEAltreInfo?,
        schedaConHRefEAltreInfo?,
        (
          element titolo { testo.cmSemplice }? &
          element query { query.cm }* &
          element menuContestuale { menuContestuale.cm }* &
          element menuStatico { menuStatico.cm }* &
          element contenutoStatico { contenutoStatico.cm }*
        )

        # elencoConHRefEAltreInfo è l'elemento 'elenco' al quale è
        # possibile aggiungere gli attributi 'href', 'descrizione'
        # e 'altreInfo'. Gli stessi attributi possono essere aggiunti
        # a tutti i sotto-elementi di 'elenco'
        elencoConHRefEAltreInfo = element elenco { ANY }


        # schedaConHRefEAltreInfo è l'elemento 'scheda' al quale è
        # possibile aggiungere gli attributi 'href', 'descrizione'
        # e 'altreInfo'. Gli stessi attributi possono essere aggiunti
        # a tutti i sotto-elementi di 'dati' dentro 'scheda'
        schedaConHRefEAltreInfo = element scheda { ANY }

        query.cm =
                attribute tipo { xsd:NMTOKEN }?,
                attribute titolo { text }?,
                form

        menuContestuale.cm =
                attribute codice { xsd:NMTOKEN }, (
                element elementiCorrelati { elementiCorrelati.cm }* &
                element navigazione { navigazione.cm }* &
                element altriLink { altriLink.cm }* )

                elementiCorrelati.cm =
                        schedaConHRef.element* &
                        element ricerca { link.cm }*

                navigazione.cm =
                        element precedente { link.cm }*,
                        element successivo { link.cm }*

                altriLink.cm = link*

        menuStatico.cm =
                attribute titolo { text }?,
                link*

        contenutoStatico.cm =
                attribute tipo { "intestazione" | "crediti" }?,
                attribute titolo { text }?, (
                testo.cmSemplice &
                testo* &
                link* &
                img* &
                ul* & ol* &
                table* )


# schedaConHRef.element è un qualsiasi elemento ammissibile dentro
# a 'dati' in 'scheda' al quale è stato aggiunto l'attributo 'href'
schedaConHRef.element = element * - ricerca { ANY }

ANY =
        attribute * { text }* &
        element * { ANY }* &
        text
</verbatim>

---+++ 6.3 Formattazione di dati XML in un frammento di documento

La richiesta di formattazione di dati XML per un frammento è simile alla richiesta che viene effettuata per la formattazione in un intero documento descritta nella sezione 6.2.
L'unica differenza è che l'URL dello script da utilizzare è quello contenuto nell'elemento =urlFormattazioneFrammento= del catalogo.

Il formatter risponde alle richieste di formattazione di dati XML in un frammento di documento con una porzione di documento pronta per essere inserita dall'Ajax Engine nel documento visualizzato all'utente in quel momento, secondo le specifiche riportate in sez. 7.3.

La richiesta deve avere come elemento radice =frammenti= ed ogni suo figlio di primo livello avrà l'attributo =id= come identificatore univoco all'interno della pagina di destinazione. L'attributo =id= è necessario per far capire al codice Ajax dove andare a posizionare il frammento ricevuto.

---++ 7 Output del formatter

Il formatter produce tre tipi di output: l'elenco dei layout disponibili, documenti completi formattati e porzioni di documento formattate.


---+++ 7.1 Elenco dei layout

L'elenco dei layout racchiude informazioni sui layout messi a disposizione dal formatter.

Le informazioni relative ad ogni layout sono espresse tramite l'attributo =id= e gli elementi =nome=, =urlEsempio=, =descrizione= e =skin=:
   * =id=: l'identificatore del layout. È utilizzato nella richiesta di formattazione (sezioni 6.2 e 6.3) per specificare il tipo di layout da applicare al documento;
   * =nome=: il nome del layout;
   * =urlEsempio=: l'URL di un documento di esempio che mostra il layout e la sua resa grafica finale;
   * =descrizione=: una descrizione human-readable del layout, del tipo di formattazione che produce, dell'organizzazione della pagina, della divisione in blocchi, etc;
   * =skin=: il nome di una skin che specifica lo stile grafico da applicare al layout. L'attributo =id= è l'identificatore univoco della skin ed è usato nelle richieste di formattazione di dati al DF. L'attributo =url= contiene l'URL della skin in formato CSS.

Si noti che in ogni elemento layout devono essere presenti l'attributo =id=, l'elemento =nome= ed almeno una =skin=. Gli elementi =urlEsempio= e =descrizione= sono facoltativi.

Di seguito è riportato un esempio di elenco di layout:

<verbatim>
<elencoLayout>
        <layout id="1">
                <nome>Normale</nome>
                <urlEsempio>http://tw.web.cs.unibo.it/esempi-formatter/normale.pdf</urlEsempio>
                <descrizione>Un layout con le sole informazioni</descrizione>
                <skin id="1" url="http://tw.web.cs.unibo.it/skin/layout1-giallo.css">Giallo</skin>
                <skin id="2" url="http://tw.web.cs.unibo.it/skin/layout1-verde.css">Verde</skin>
        </layout>
        <layout id="2">
                <nome>Informazioni essenziali</nome>
                <skin id="1" url="http://tw.web.cs.unibo.it/skin/layout2-bn.css">Bianco e nero</skin>
        </layout>
        <layout id="3">
                <nome>TUTTO!</nome>
                <urlEsempio>http://tw.web.cs.unibo.it/esempi-formatter/tutto.png</urlEsempio>
                <descrizione>Un layout semplicemente folle, c'è tutto! Vi lascerà a bocca aperta!</descrizione>
                <skin id="gothic" url="http://tw.web.cs.unibo.it/skin/layout3-gothic.css">Stile goth</skin>
                <skin id="puppy" url="http://tw.web.cs.unibo.it/skin/layout3-puppy.css">Cagnolini</skin>
                <skin id="train" url="http://tw.web.cs.unibo.it/skin/layout3-trainspotting.css">Trainspotting</skin>
        </layout>
</elencoLayout>
</verbatim>

---++++ 7.1.1 Le skin

Un documento formattato è composto da due parti, chiamate per semplicità layout e skin. Il layout specifica i blocchi di testo, le immagini, le parti fisse e variabili di una pagina, ecc. La skin specifica le proprietà tipografiche della pagina come font, colore, dimensioni, ecc.

In ODALISK il formatter deve correttamente applicare la skin al documento, come specificato dall'applicazione attraverso la richiesta di formattazione descritta nelle sezioni 6.2 e 6.3. L'attributo =id= del nodo =skin= specifica l'ID con il quale l'AC si può riferire ad una skin, mentre l'attributo =url= contine l'URL della skin in formato CSS.

Il comportamento del formatter è diverso nel caso di supporto diretto dei CSS da parte dello user-agent o meno. In altri termini: in un documento HTML è possibile semplicemente aggiungere il riferimento al CSS ma ad esempio in un PDF è necessario esprimere in modo alternativo le stesse proprietà. Di conseguenza il formatter, se produce documenti HTML (o XHTML o XML) associa al documento direttamente  il CSS e lo rispedisce all'applicazione, altrimenti recupera questa risorsa, interpreta le regole ed assegna la stessa formattazione (se possibile) al documento che sta producendo.

Si consideri ad esempio un formatter che produce file PDF utilizzando XSL-FO e riceve questa richiesta:

<verbatim>
<formatta>
    <info>
        <layout id="12"/>
        <skin id="cool"/>
    </info>
    <dati>
    ...
    </dati>
</formatta>
</verbatim>

Il CSS della skin richesta contiene la regola:

<verbatim>
p { font-family: Arial; }
</verbatim>

Il formatter applica il layout con id =12= e, per applicare la skin, legge il CSS associato all'id =cool=, trasforma questa regola in sintassi XSL-FO, la applica ad un blocco

<verbatim>
<fo:block font-family="Arial">Contenuto del paragrafo</fo:block>
</verbatim>

e genera il risultato tramite un convertitore. Nel PDF finale il testo del paragrafo sarà di tipo _Arial_ come richiesto dall'applicazione.


---++++ 7.1.2 Schema Relax NG dell'elenco dei layout

Gli elenchi dei layout devono essere validati dal seguente schema Relax NG (disponibile online in sintassi compatta all'URL http://ltw06_01.web.cs.unibo.it/wg-df/schema_formatter-6/elencoLayout.rnc e in sintassi XML all'URL http://ltw06_01.web.cs.unibo.it/wg-df/schema_formatter-6/elencoLayout.rng):

<verbatim>
start = elencoLayout

elencoLayout = element elencoLayout {
        element layout { layout.cm }+
}

layout.cm =
        attribute id { xsd:NMTOKEN },
        element nome { text },
        element urlEsempio { xsd:anyURI }?,
        element descrizione { testo.cmSemplice }?,
        element skin { skin.cm }+

skin.cm =
        attribute id { xsd:NMTOKEN },
        attribute url { text },
        testo.cmSemplice
</verbatim>


---+++ 7.2 Formattazione di dati XML in un documento completo

Quando al formatter viene richiesto di formattare dei dati XML in un documento completo, il formatter risponde con un documento formattato e decorato secondo il layout e la skin richiesti.

Nell'header HTTP della risposta, il formatter deve indicare il MIME type del documento prodotto.

L'output di questo formatter è un documento completo e pronto per la visualizzazione, per cui l'AC deve semplicemente inoltrarlo allo user-agent ed aggiungere le informazioni necessarie per una corretta visualizzazione. Solitamente l'unica informazione da aggiungere è il content type, che specifica il tipo di documento prodotto ed è suggerito dal formatter.

Fondamentalmente i formatter possono generare due tipi di output: output testuali (ed XML) e output binari. In entrambi i casi è il ruolo dell'AC è marginale: si limita a impostare l'header HTTP Content-Type al MIME type suggerito dal formatter e consegnare i dati che formano il documento stesso.

È importante ribadire che tutte le pagine, anche quelle accessorie come home, ricerca ed help, devono essere formattate da un formatter.

---+++ 7.3 Formattazione di dati XML in un frammento di documento

Se al formatter viene chiesto di formattare dei dati XML in un frammento di documento, il formatter risponde con una porzione di documento formattata e decorata secondo il layout e la skin richiesti.

L'output di questo formatter è un documento XML che ha come radice l'elemento =frammenti=.
È compito dell'AC è integrare questi frammenti con il documento finale.

Gli elementi discendenti diretti di =frammenti= devono avere l'attributo =id=. L'attributo =id= servirà all'AC client-side per capire quale elemento andare a rimpiazzare nel documento attualmente visualizzato.

È possibile richiedere la formattazione in un frammento di documento delle pagine accessorie (home, ricerca, ecc.).

---++++ 7.3.1 Scheda dell'output del formatter di frammenti


I dati ricevuti dal formatter in seguito ad una richiesta di formattazione di dati XML in un frammento di documento devono essere validati dal seguente schema Relax NG (disponibile online in sintassi compatta all'URL http://ltw06_01.web.cs.unibo.it/wg-df/schema_formatter-6/frammenti.rnc e in sintassi XML all'URL http://ltw06_01.web.cs.unibo.it/wg-df/schema_formatter-6/frammenti.rng):


<verbatim>
start = frammenti

frammenti = element frammenti { ANYConID* }

ANYConID =
        element * {
                attribute * - id { text }*,
                attribute id { xsd:NMTOKEN },
                mixed { element * { ANY }* }
        }

ANY =
        attribute * { text }*,
        mixed { element * { ANY }* }
</verbatim>

---+++ 7.4 Gestione degli errori

Le richieste inoltrate al formatter possono generare diversi errori. Per gestirli il protocollo AC-DF prevede un messaggio di errore che riporta un codice ed una descrizione
human-readable dell'errore. Il messaggio deve essere validato dal seguente schema Relax NG:

<verbatim>
start = errori

errori = element errori {
        element errore { errore.cm }
}

errore.cm =
        element codice { text },
        element descrizione { testo.cmSemplice }
</verbatim>

Il seguente frammento XML riporta un esempio di messaggio di errore:

<verbatim>
<errori>
    <errore>
        <codice>00</codice>
        <descrizione>Formatter non disponibile</descrizione>
    </errore>
</errori>
</verbatim>

Viene riportata di seguito una tabella con i possibili errori e relative descrizioni:

| *Codice errore* | *Descrizione errore* |
| 00 | Non disponibile |
| 10 | Dati in input errati |
| 20 | Layout richiesto inesistente |
| 30 | Skin richiesta inesistente |

------

#DifferenzePrecVersioni
---++ Differenze con le versioni precedenti

---+++!! Cambiamenti da versione 8 a versione 9
   * Modificato il content model della richiesta di formattazione: 
      * dal tag "scheda" rimosso l'attributo "cod", in quanto lo stesso servizio si può ottenere aggiungendo l'attributo "href"
      * definita la forma della richiesta di formattazione frammenti, imponendo la presenza dell'elemento radice "frammenti" dentro al quale incapsulare tutti i frammenti da formattare
      * aggiunto al content model del tag "testo" all'interno di "menuContestuale" i tag "h1", "h2", "h3", "h4", "h5" e "h6", con lo stesso significato che hanno in HTML, per migliorare l'impaginazione di pagine statiche strutturate come la home o l'help

---+++!! Cambiamenti da versione 7 a versione 8
   * Modificato il coontent model di "errori".

---+++!! Cambiamenti da versione 6 a versione 7
   * Modificati i codici di errore.

---+++!! Cambiamenti da versione 5 a versione 6

---++++!! Formattazione di dati
   * Aggiunto l'attributo =titolo= per l'elemento =query=.
   * Aggiunto l'attributo =tipo= per =contenutoStatico=.
   * Aggiunto del testo che spiega come usare l'attributo =for= di =label= e =testo=
   * Aggiunte varie sezioni con la descrizione dettagliata dei singoli elementi e rispettivi esempi.


---+++!! Cambiamenti da versione 4 a versione 5

---++++!! Formattazione di dati
   * Corretto lo schema di =scheda= e =elenco= con gli attributi aggiuntivi.
   * Cambiato l'attributo che identifica un menuContestuale da =id= a =codice=.
   * Cambiato il content model di =menuStatico= per contenere solo =link=.
   * Corretto l'errore nello schema di =formatta= che rendeva l'attributo =titolo= obbligatorio.
   * Aggiunti degli esempi di dati formattare.
   * Modificato lo scheda dell'output del formatter per frammenti di documenti.

---++++!! Gestione errori
   * Aggiunto un nuovo errore per le skin inesistenti.

---+++!! Cambiamenti da versione 3 a versione 4

---++++!! Generale
   * Riscritti i DTD in schema Relax NG in sintassi compatta.

---++++!! Formattazione di dati
   * Ampliata la descrizione degli elementi contenuti in =dati=.
   * Aggiunto l'elemento =contenutoStatico=
   * Aggiunto l'attributo =tipo= a =query=
   * Aggiunto l'attributo =titolo= a =menuStatico= e =menuContestuale=


---+++!! Cambiamenti da versione 2 a versione 3

---++++!! Formattazione di dati
   * Aggiunto l'elemento =ajax= alle =info= da passare al formatter per richiedere la formattazione di dati.
   * Rimossi =pagina= e =navigazione= in favore degli elementi con più significato =menuContestuale=, =query= e =menuStatico=.
   * Aggiunti nuovi attributi =href=, =descrizione= e =altreInfo= agli elementi di =scheda= ed =elenco=.


---+++!! Cambiamenti da versione 1 a versione 2

---++++!! Generale
   * Corretto qualche refuso.
   * Riscritti tutti i nomi degli elementi da lowercase-dashed a camelCase.

---++++!! Catalogo DF
   * Rinominati gli elementi =name= e =type= in =nome= e =tipo=.

---++++!! Formattazione di dati
   * Cambiato il content model di =dati= da =ANY= a =(elenco|scheda)?, pagina?, navigazione?=.

---+++!! Cambiamenti da 0.9 a Protocollo AC-DF versione 1

---++++!! Generale
   * Riordinati i capitoli e riscritta in parte la descrizione del protocollo.

---++++!! Catalogo DF
   * Riscritto il DTD del catalogo per rendere =catalogo_formatter= un contenitore di elementi e non di attributi.
   * Rimosso il vincolo che obbliga =url-elenco=, =url-formattazione-pagina= e =url-formattazione-frammento= a riferirsi ad un unico script.
   * Aggiunto il vincolo che impedisce di avere una parte di query negli URL di =url-elenco=, =url-formattazione-pagina= e =url-formattazione-pagina=.

---++++!! Elenco dei layout
   * Aggiunto l'elemento =skin= a =layout= per permettere di pubblicare le skin disponibili per un dato layout.

---++++!! Gestione degli errori
   * Aggiunto il contenitore esterno =errori= per uniformare il protocollo AC-DF al protocollo AC-DS.

%HIDE%
   * Set ALLOWTOPICVIEW = 
   * Set ALLOWTOPICCHANGE = 
%E%
to top
End of topic
Skip to action links | Back to top
Edit | Attach image or document | Printable version | Raw text | More topic actions
Revisions: | r1.4 | > | r1.3 | > | r1.2 | Total page history | Backlinks
You are here: TechWeb06 > ProtocolloACDFv9

to top