# Guida per gli stili per la finestra di chat di &kopete;

## Guida di riferimento per gli stili della finestra di chat di &kopete;.

A partire da &kopete; 0.12, ora usiamo il formato di Adium per gli stili delle finestre di conversazione. Il formato del tema è basato su modelli HTML e su CSS. Sono più facili da creare e sviluppare, richiedono solo la conoscenza di HTML e CSS. Inoltre gli stili possono avere delle varianti (definite con file CSS) che forniscono un valore aggiunto per la personalizzazione.

### Guida di riferimento.

Il formato adium consiste di una struttura di directory, di modelli HTML, di file CSS e di parole chiave che sono sostituite ogni volta che il modello è elaborato. La conversazione finale è una pagina XHTML dove i messaggi sono aggiunti con operazioni DOM. L'elemento centrale è l'elemento div chiamato `Chat`. Prima e dopo l'elemento div, vengono i modelli Header e Footer. I messaggi sono figli dell'elemento div `Chat`.

#### Struttura della directory

Uno stile deve rispettare questa struttura di directory. Il codice di &kopete; è pensato attorno ad essa. Quando archivi lo stile, archivia la directory `styleName`. La struttura della directory è la struttura di un bundle di Mac OS X, per chi ha familiarità con tale sistema operativo. Inoltre è importante rispettare le maiuscole qui, perché i sistemi UNIX fanno distinzione.

    styleName\ (può avere un suffisso .adiumMessageStyle, perché in Mac OS X è un bundle)
            Contents\
                    Info.plist
                    Resources\
                            main.css
                            Header.html
                            Footer.html
                            Status.html
                            Incoming\ (and Outgoing\)
                                    Content.html
                                    NextContent.html (for consecutive messages)
                                    Context.html (for message history)
                                    NextContext.html
                                    Action.html
                            Variants\
                                    *.css

#### Informazioni su <div id="insert"></div>

Questo è un elemento div speciale usato internamente. È un segnaposto che indica dove inserire il prossimo messaggio. Se è un nuovo messaggio, è rimosso e lo sostituisce il messaggio nuovo. Ma se è un messaggio consecutivo dello stesso utente, l'elemento div è sostituito con il contenuto del nuovo messaggio. Questo elemento div speciale è obbligatorio nei modelli Content, Context, NextContent, NextContext. Però non fa male nemmeno nei modelli Action e Status.

#### Modelli di HTML.

##### Descrizione del modello.

`Header.html` (Obbligatorio)

  Usa il modello Header per mostrare una bella intestazione nella conversazione. Questo modello è inserito prima dell'elemento div `Chat`. Se non lo usi, puoi metterci un file vuoto.

`Footer.html` (Obbligatorio)

  È quasi lo stesso di Header, ma è messo in calce alla conversazione. Questo modello è inserito dopo l'elemento div `Chat`. Se non lo usi, puoi metterci un file vuoto.

`Status.html` (Obbligatorio)

  Questo modello è usato per mostrare un messaggio interno. I messaggi interni sono i cambi di stato e i messaggi da Kopete (&eg;, l'arrivo di un trasferimento di file). Quando lo stile non fornisce un modello Action, è usato anche per i messaggi di azione.

`Incoming/Content.html`
`Outgoing/Content.html` (Obbligatorio)

  Il modello Content è il nocciolo del messaggio. Pensalo come un blocco che fa da supporto ai messaggi. Assicurati che sia pronto ad accettare messaggi consecutivi, non progettarlo per mostrare un solo messaggio. I messaggi consecutivi saranno inseriti all'elemento div di inserimento.

`Incoming/NextContent.html`
`Outgoing/NextContent.html` (Obbligatorio)

  Il modello NextContent è un frammento di messaggio per messaggi consecutivi. Sarà inserito nel blocco del messaggio principale. Il modello HTML dovrebbe contenere il minimo indispensabile per mostrare il messaggio.

`Incoming/Action.html`
`Outgoing/Action.html` (Opzionale, estensione di &kopete;)

  Questo modello è un'estensione di &kopete; al formato Adium. È disponibile per le direzioni Incoming e Outgoing. I messaggi di azione sono messaggi speciali che dicono che noi stiamo facendo un'azione. Ad esempio /me sta installando &kopete; potrebbe essere mostrato come DarkShock sta installando &kopete;.

`Incoming/Context.html`
`Incoming/NextContext.html`
`Outgoing/Context.html`
`Outgoing/NextContext.html` (Opzionale)

  Questi modelli non sono usati da Kopete. In Adium, sono usati per mostrare la cronologia. Sono quasi identici a Content e NextContent, ma con qualche differenza per distinguerli dai messaggi normali.

#### Informazioni sugli stili CSS e le varianti

Dei modelli HTML sono usati per descrivere com'è fatta la struttura. Ma tutto lo stile è descritto in file CSS. `main.css` è lo stile principale, dove le varianti sono solo alterazioni dello stile principale. Esempi di varianti sono colori diversi, assenza della visualizzazione della foto dell'utente. Sia `main.css` che le varianti sono importate nella pagina XHTML finale.

##### -`main.css`

Questo è il file CSS principale che è comune a tutte le varianti. Questo file deve contenere tutte le descrizioni principali dello stile.

##### -Varianti

Le varianti sono file CSS presenti nella cartella `Variants`. Ciascuna variante è un singolo file CSS che include `main.css` ed esegue alterazioni dello stile principale.

#### Debug degli stili

Ecco un paio di consigli per verificare il funzionamento di uno stile durante la sua creazione.

##### -Salvare una conversazione di esempio.

Nelle finestre di conversazione puoi salvare una conversazione. Questa è una copia della pagina XHTML interna che è visualizzata. Usala in Konqueror per provare i file CSS.

##### -Disabilitare la cache dello stile.

Una piccola variabile di configurazione esiste per disabilitare ela cache dello stile. Quando è abilitata, ricarica il modello HTML ogni volta che viene chiesto uno stile. Aggiungi la riga seguente al file `kopeterc`. È utilissimo per provare uno stile in &kopete;

    [KopeteStyleDebug]
    disableStyleCache=true

### Guida di riferimento delle parole chiave

Le parole chiave sono come buchi da riempire con i dettagli. In ciascun messaggio, sono sostituite dal valore corretto corrispondente al loro contenuto. Per gestire completamente tutte le funzioni di &kopete;, abbiamo aggiunto qualche estensione alle parole chiave di Adium. Inoltre alcune parole chiave sono disponibili solo in certi contesti.

#### Elenco di parole chiave per i modelli Header e Footer.

Queste parole chiave sono valutate all'inizio di una conversazione.

`%chatName%`

  Questo è il nome della sessione di conversazione corrente. Per una sessione tipica, mostra il nome del contatto ed il suo stato. Per IRC, mostra l'argomento del canale.

`%sourceName%`
`%destinationName%`

  Questi sono i nomi dei contatti della sessione di conversazione. `%sourceName%` è il tuo nome. `%destinationName%` è il nome del contatto con cui stai chiacchierando. È preferibile usare `%chatName%` rispetto ai precedenti, perché possono essere fonte di confusione nelle discussioni di gruppo o per IRC.

`%incomingIconPath%`
`%outgoingIconPath%`

  Queste sono le immagini/foto/avatar dei contatti della sessione di conversazione. Incoming rappresenta la foto del contatto e Outgoing la tua. Se non ci sono foto disponibili, verrà usata l'immagine `buddy_icon.png` che è nella cartella `Incoming` o `Outgoing`.

`%timeOpened%`
`%timeOpened{X}%`

  È l'ora in cui è iniziata la conversazione. `%timeOpened%` usa il formato predefinito per l'ora nel locale attuale. Se vuoi usare un formato specifico di tempo, usa `%timeOpened{X}%` dove X è una stringa contenente il formato dell'ora. I parametri dell'ora sono identici a quelli usati dalla funzione della glibc `strftime`. Usa `man strftime` per vedere l'elenco di formati disponibili.

#### Elenco delle parole chiave per i modelli Content, NextContent, Context, NextContext e Action

Queste parole chiave sono valutare per ogni messaggio.

`%userIconPath%`

  Questa è l'immagini/foto/avatar del contatto associato al messaggio. Se non ci sono foto disponibili, verrà usata l'immagine `buddy_icon.png` che è nella cartella `Incoming` o `Outgoing`.

`%senderScreenName%`

  Questo è l'ID del contatto associato al messaggio. Esempi: me@hotmail.com, 45566576, JohnSmith.

`%sender%`

  Questo è il nome del contatto associato al messaggio. Usa il nome da visualizzare del metacontatto come fonte.

`%service%`

  Mostra il nome del servizio associato al messaggio. Esempi: Jabber, Yahoo, MSN.

`%textbackgroundcolor{X}%`

  In &kopete;, questa parola chiave può essere usata per rappresentare il colore per evidenziare lo sfondo. Ignora il parametro fra parentesi graffe ed usalo solo come `%textbackgroundcolor{}`.

`%senderStatusIcon%` (estensione di &kopete;)

  Mostra l'icona di stato del contatto associato al messaggio. È il percorso di un file.

`%senderColor%`
`%senderColor{N}%` (estensione di &kopete;)

  Genera un colore partendo dall'ID del contatto del mittente. Può essere usato per mostrare un colore diverso per il nick del contatto.

  `%senderColor{N}%` dove N è un numero positivo. Se N è più grande di 100, rappresenta un colore più chiaro del colore del contatto. Se vale 150, indica un colore del 50% più chiaro. Se vale meno di 100 è un colore più scuro. È utile per avere uno sfondo colorato in modo diverso per ciascun contatto.

  Se vuoi usare questi colori in una variante, ma non nello stile principale, devi ricorrere ad un trucco.

      <div style="color:%senderColor%;border:none;border-color:%senderColor{40}%;"
      ><p class="message"
      >...</p
      ></div>

  puoi applicare il colore dell'elemento p.message nel file`main.css`, e nella variante inserire qualcosa come

      p.message { color:inherit; border-color:inherit; }

#### Elenco di parole chiave comune per i messaggi e per Status.html

`%message%`

  Il messaggio stesso. È un frammento di HTML.

`%time%`
`%time{X}%`

  L'ora in cui è stato ricevuto il messaggio. `%time%` usa il formato orario predefinito per il locale attuale. Se vuoi usare un formato orario specifico, usa `%time{X}%` dove X è una stringa contenente il formato orario. I parametri del formato sono gli stessi della funzione `strftime` della glibc. Usa `man strftime` per vedere la lista dei parametri disponibili.

`%messageDirection%` (Estensione di &kopete;)

  Rappresenta la direzione del messaggio, se il messaggio deve essere mostrato da destra a sinistra (come per l'arabo) o da sinistra a destra. Vedi Linee guida per la direzione dei messaggi per scoprire come usare in modo appropriato questa parola chiave.

## Linee guida per gli stili della finestra di chat di &kopete;

Le linee guida per gli stili della finestra di conversazione di &kopete; è una raccolta delle cose che lo stile della finestra di conversazione deve supportare per essere compatibile con Kopete.

### Gestione dell'evidenziazione

Il tuo stile deve mostrare delle evidenziazioni, a volte. In Kopete e Adium, `%textbackgroundcolor{}%` è sostituito con il colore di evidenziazione. Aggiungi questo attributo di stile: `background-color: %textbackgroundcolor{}%` all'elemento HTML che mostra il messaggio.

### Un modello per i messaggi consecutivi ora è obbligatorio.

Queste linee guida sono per chi deve riscrivere dei vecchi stili XSL nel nuovo formato. Tutti gli stili devono fornire un modello per i messaggi consecutivi. Ora è una funzione predefinita.

### Usa la codifica UTF-8.

Il titolo dice tutto. Devi salvare i file in UTF-8.

### Fornisci il file `Contents/Info.plist` per mantenere l'interoperabilità con Adium

Il file `Contents/Info.plist` non è ancora usato da Kopete. Ma se vuoi creare uno stile compatibile con Adium, devi fornire anche questo file. Ecco un esempio base del file. Le stringhe da sostituire sono racchiuse fra $.

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
    <dict>
            <key
    >CFBundleDevelopmentRegion</key>
            <string
    >English</string>
            <key
    >CFBundleGetInfoString</key>
            <string
    >$Il nome completo dello stile$</string>
            <key
    >CFBundleIdentifier</key>
            <string
    >$L'ID dello stile nella forma: com.adiumx.smooth.operator.style$</string>
            <key
    >CFBundleInfoDictionaryVersion</key>
            <string
    >1.0</string>
            <key
    >CFBundleName</key>
            <string
    >$Il nome dello stile$</string>
            <key
    >CFBundlePackageType</key>
            <string
    >AdIM</string>
            <key
    >MessageViewVersion</key>
            <integer
    >3</integer>
    </dict>
    </plist>

### Fornisci il file `buddy_icon.png`

Devi mettere un file di nome `buddy_icon.png` in `Incoming` e `Outgoing`. Queste immagini saranno usate quando il contatto non ha una foto.

### La parola chiave `%messageDirection%` permette la gestione delle lingue scritte da destra a sinistra.

La parola chiave `%messageDirection%` è presente per le lingue del mondo che scrivono da destra a sinistra. Definisce la direzione del messaggio, se è rtl (right-to-left, da destra a sinistra) o ltr (left-to-right, da sinistra a destra). Aggiungi questo attributo di stile all'elemento HTML che mostra il messaggio: `direction: %messageDirection%`. L'anteprima dello stile nella configurazione dell'aspetto include un controllo per il testo scritto da destra a sinistra per vedere se lo stile viene mostrato correttamente. Dovrebbe far cominciare la stringa dalla destra.