Skip to topic | Skip to bottom
Home
TechWeb06
TechWeb06.ProtocolloACDFv2r1.1 - 03 May 2006 - 14:49 - GioeleBarabuccitopic end

Start of topic | Skip to actions

Protocollo AC-DF versione 2

Questo documento descrive il protocollo AC-DF versione 2 (3 maggio 2006).

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


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:

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

5.2 DTD del catalogo DF

I cataloghi XML devono essere validati dal seguente DTD:

<!ELEMENT catalogoFormatter (nome, tipo, descrizione,
                             urlElenco,
                             urlFormattazionePagina, urlFormattazioneFrammento,
                             variabileDatiFormattazione)>
<!ELEMENT nome (#PCDATA)>
<!ELEMENT tipo (#PCDATA)>
<!ELEMENT descrizione (#PCDATA)>
<!ELEMENT urlElenco (#PCDATA)>
<!ELEMENT urlFormattazionePagina (#PCDATA)>
<!ELEMENT urlFormattazioneFrammento (#PCDATA)>
<!ELEMENT variabileDatiFormattazione (#PCDATA)>

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 in particolare l'identificativo del layout (specificato nell'attributo id dell'elemento layout) e l'URL della skin (nell'attributo url del nodo skin). L'id del layout Ŕ selezionato dall'applicazione tra i layout disponibili ottenuti con la richiesta catalogo. Similarmente l'URL della skin deve essere scelto tra gli URL delle skin associate al layout selezionato.
  • dati: sono i dati da formattare.

I dati da formattare possono essere di tre tipi:

  • elenco o scheda: sono i dati ottenuti dall'output del data-source. Possono essere anche un sottoinsieme o una versione modificata dei dati restituiti dai DS.
  • pagina: sono gli elementi che descrivono le pagine semi-statiche. Tra questi elementi ci sono quelli relativi alle form ed alla presentazione.
  • navigazione: sono i dati generati dall'application logic sulla base dei dati estratti dai DS. Il content model di questo elemento sarÓ definito nelle prossime versioni del protocollo AC-DF.

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 memorizzata nell'URL http://tw.web.cs.unibo.it/skins/cool.css.

<formatta>
    <info>
        <layout id="12"/>
        <skin url="http://tw.web.cs.unibo.it/skins/cool.css"/>
    </info>
    <dati>
        <elenco>
          ...
        </elenco>
        <navigazione>
          ...
        </navigazione>
    </dati>
</formatta>

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 DTD dei dati da formattare

<!ELEMENT formatta (info, dati)>
<!ELEMENT info (layout , skin)>
<!ELEMENT layout EMPTY>
<!ATTLIST layout id CDATA #REQUIRED>
<!ELEMENT skin EMPTY>
<!ATTLIST skin url CDATA #REQUIRED>
<!ELEMENT dati ((elenco|scheda)?, pagina?, navigazione?)>
<!ELEMENT elenco (%CMelenco;)>
<!ELEMENT scheda (%CMscheda;)>
<!ELEMENT pagina (%CMform;|%CMpresentazione;)* >
<!ELEMENT navigazione ANY>

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 X.X. 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.

7 Output del formatter

Il formatter produce tre tipi di output: l'elenco dei layout disponibili, documenti completi formattati e porzioni di documenti 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 url contiene l'URL della skin in formato CSS.

Si noti che id e nome sono obbigatori, urlEsempio e descrizione sono facoltativi e ogni layout deve fornire almeno una skin.

Di seguito Ŕ riportato un esempio di elenco di layout:

<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 url="http://tw.web.cs.unibo.it/skin/layout1-giallo.css">Giallo</skin>
        <skin url="http://tw.web.cs.unibo.it/skin/layout1-verde.css">Verde</skin>
    </layout>
    <layout id="2">
        <nome>Informazioni essenziali</nome>
        <skin 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 url="http://tw.web.cs.unibo.it/skin/layout3-gothic.css">Stile goth</skin>
        <skin url="http://tw.web.cs.unibo.it/skin/layout3-puppy.css">Cagnolini</skin>
        <skin url="http://tw.web.cs.unibo.it/skin/layout3-trainspotting.css">Trainspotting</skin>
    </layout>
</elencoLayout>

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 url del nodo skin specifica l'URL della skin.

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:

<formatta>
    <info>
        <layout id="12"/>
        <skin url="http://tw.web.cs.unibo.it/skins/cool.css"/>
    </info>
    <dati>
    ...
    </dati>
</formatta>

Il CSS indicato contiene la regola:

p { font-family: Arial; }

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

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

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 DTD dell'elenco dei layout

Gli elenchi dei layout devono essere validati dal seguente DTD:

<!ELEMENT elencoLayout (layout+)>
<!ELEMENT layout (nome, urlEsempio?, descrizione?, skin+)>
<!ATTLIST layout id ID #REQUIRED>
<!ELEMENT nome (#PCDATA)>
<!ELEMENT urlEsempio (#PCDATA)>
<!ELEMENT descrizione (%inline;)>
<!ELEMENT skin (#PCDATA)>
<!ATTLIST skin url CDATA #REQUIRED>

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 frammento di documento pronto per l'inserimento all'interno di una pagina. ╚ compito dell'AC Ŕ integrare questo frammento con il documento finale.

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

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 DTD:

<!ELEMENT errori (errore+)>
<!ELEMENT errore (codice, descrizione)>
<!ELEMENT codice (#PCDATA)>
<!ELEMENT descrizione (%inline;)>

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

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

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

Codice errore Descrizione errore
00 Formatter non disponibile
01 Dati in input errati
02 Layout richiesto inesistente


Differenze con le versioni precedenti

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.

  • Set ALLOWTOPICVIEW =
  • Set ALLOWTOPICCHANGE =

to top

You are here: TechWeb06 > ProtocolloACDFv2

to top

Copyright © Fabio Vitali + TechWeb students 2006