# Stilguide för chattfönster i &kopete;

## Stilreferens för chattfönster i &kopete;

Från och med &kopete; 0.12, använder vi nu formatet Adium för chattfönsterstilar. Temaformatet är baserat på HTML-mallar och CSS. De är enklare att skapa och utveckla, bara kunskap om HTML och CSS behövs. Dessutom kan stilar ha varianter (definierade med en CSS-fil), som lägger till flera egenanpassade värden.

### Referensguide.

Adium-formatet består av en katalogstruktur, HTML-mallar, CSS-filer och nyckelord som ersätts varje gång mallen behandlas. Den slutliga konverteringen är en XHTML-sida där meddelanden läggs till med DOM-åtgärder. Det centrala elementet är ett div-element som heter `Chat`. Innan och efter detta div-element finns mallar för sidhuvud och sidfot. Meddelanden finns under div-elementet `Chat`.

#### Katalogstruktur

En stil måste hålla sig till denna katalogstruktur. Koden i &kopete; styrs av katalogstrukturen. När stilen arkiveras, arkivera då katalogen `styleName`. Katalogstrukturen är en struktur i enligthet med en bundle i Mac OS X, för de som känner till operativsystemet. Du måste dessutom följa skiftläget som visas här, eftersom Unix-system är skiftlägeskänsliga.

    styleName\ (kan ha .adiumMessageStyle som suffix, eftersom det är en bundle i Mac OS X)
            Contents\
                    Info.plist
                    Resources\
                            main.css
                            Header.html
                            Footer.html
                            Status.html
                            Incoming\ (och Outgoing\)
                                    Content.html
                                    NextContent.html (för efterföljande meddelanden)
                                    Context.html (för meddelandehistorik)
                                    NextContext.html
                                    Action.html
                            Variants\
                                    *.css

#### Om <div id="insert"></div>

Detta är ett särskilt div-element som används internt. Det är en platsmarkör som anger var nästa meddelande ska infogas. Om det är ett nytt meddelande, tas det bort och det nya meddelandet tar dess plats. Men om det är ett efterföljande meddelande ersätts div-elementet med det nya meddelandets innehåll. Detta särskilda div-element krävs i mallarna Content, Context, NextContent, NextContext. Det skadar dock inte att också lägga till det i mallarna Action och Status.

#### HTML-mallar.

##### Mallbeskrivning.

`Header.html` (krävs)

  Använd mallen Header för att visa ett snyggt sidhuvud för konversationenen. Mallen infogas innan div-elementet `Chat`. Om du inte använder det, lägg bara till en tom fil.

`Footer.html` (krävs)

  Detta är i huvudsak samma som Header, men är för konversationens sidfot. Mallen infogas efter div-elementet `Chat`. Om du inte använder det, lägg bara till en tom fil.

`Status.html` (krävs)

  Mallen används för att visa ett internt meddelande. Interna meddelanden som statusändringar, meddelanden från Kopete (t.ex. inkommande filöverföring) visas. När stilen inte tillhandahåller mallen Action, används den för att visa sådana meddelanden.

`Incoming/Content.html`
`Outgoing/Content.html` (krävs)

  Innehållsmallen är meddelandets kärna. Föreställ dig den som ett block som kommer att innehålla meddelanden. Försäkra dig om att den är klar att ta emot meddelanden i följd, konstruera den inte för att bara visa ett meddelande. Meddelanden i följd infogas vid div insert-elementet.

`Incoming/NextContent.html`
`Outgoing/NextContent.html` (krävs)

  Mallen NextContent är meddelandefragment för efterföljande meddelanden. Den infogas i huvudmeddelandeblocket. HTML-mallen ska bara innehålla det som minimalt behövs för att visa ett meddelande.

`Incoming/Action.html`
`Outgoing/Action.html` (valfri) (utökning i &kopete;)

  Denna mall är en utökning av Adium-formatet i &kopete;. Den är tillgänglig för inkommande och utgående riktningar. Åtgärdsmeddelanden är specialmeddelanden som talar om att en åtgärd utförs. Till exempel: "/me installerar &kopete;" skulle visas som "DarkShock installerar &kopete;".

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

  Dessa mallar används inte i Kopete. I Adium används de för att visa historik. De är i huvudsak likadana som Content och NextContent men med vissa skillnader för att åtskilja dem från normala meddelanden.

#### Om CSS-stilmallar och varianter

HTML-mallar används för att beskriva hur strukturen skapas, men alla stilar beskrivs i CSS-filer. `main.css` är huvudstilen, där varianter bara är ändringar av huvudstilen. Exempel på varianter är annorlunda färger, ingen visning av användarfoto. Både `main.css` och varianter importeras till den slutliga XHTML-sidan.

##### -`main.css`

Detta är den huvudsakliga CSS-filen som är gemensam för alla varianter. Filen ska innehålla all huvudsaklig beskrivning av stilen.

##### Varianter

Varianter är CSS-filer placerade i katalogen `Variants/`. Varje variant är en enda CSS-fil som inkluderar `main.css` och gör ändringar av huvudstilen.

#### Felsökning av stilar

Här är två tips om hur man provar en stil medan den skapas.

##### - Spara ett exempel på en konversation.

Du kan spara en konversation i chattfönstret. Detta är en kopia av den interna XHTML-sidan som visas. Använd den i Konqueror för att prova dina CSS-filer.

##### - Inaktivera stilcachen.

En liten inställningsflagga finns för att inaktivera stilcachen. När den aktiveras, laddas HTML-mallar om varje gång en stil efterfrågas. Lägg till följande rader i `kopeterc`. Mycket användbart när en stil provas i &kopete;.

    [KopeteStyleDebug]
    disableStyleCache=true

### Nyckelordsreferens

Nyckelord liknar hål som ska fyllas i med information. För varje nytt meddelande ersätts de av det riktiga värdet som motsvarar deras sammanhang. För att helt stödja alla funktioner i Kopete, har vissa utökningar av nyckelord tillagts i Adium. Vissa nyckelord är dessutom också bara tillgängliga i vissa sammanhang.

#### Nyckelordslista för mallarna Header och Footer.

Där behandlas nyckelord när chatten startar.

`%chatName%`

  Detta är namnet på aktuell chattsession. I en typisk session visar det namn och status för kontakten. För IRC visas kanalens ämne.

`%sourceName%`
`%destinationName%`

  Dessa är namnen på kontakterna i en chattsession. `%sourceName%` är ditt namn. `%destinationName%` är namnet på kontakten du chattar med. Föredra `%chatName%` framför dessa, eftersom de kan vara förvirrande i gruppchatter och IRC.

`%incomingIconPath%`
`%outgoingIconPath%`

  Detta är kontakternas bild, foto eller avatar för en chattsession. Incoming representerar kontaktfotot och Outgoing representerar ditt eget foto. Om något foto inte är tillgängligt, används bilden `buddy_icon.png` som finns i katalogen `Incoming` eller `Outgoing`.

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

  Detta är tiden då chattsessionen började. `%timeOpened%` använder standardtidformatet för den aktuella landsinställningen. Om du vill använda ett specifikt tidformat, använd `%timeOpened{X}%` där X är en sträng som innehåller tidformatet. Tidparametrarna är samma som i glibc-funktionen `strftime`. Skriv `man strftime` för att få en lista med tillgängliga parametrar.

#### Nyckelordslista för mallarna Content, NextContent, Context, NextContext, Action

Där behandlas nyckelord för varje meddelande.

`%userIconPath%`

  Detta är kontaktens bild, foto eller avatar som hör ihop med meddelandet. Om något foto inte är tillgängligt, används bilden `buddy_icon.png` som finns i katalogen `Incoming` eller `Outgoing` beroende på meddelandets riktning.

`%senderScreenName%`

  Detta är kontaktidentifikationen för kontakten som hör ihop med meddelandet, Exempelvis jag@hotmail.com, 45566576, AnnaJohansson.

`%sender%`

  Detta är kontaktens namn som hör ihop med meddelandet. Det använder metakontaktens namn att visa som källa.

`%service%`

  Visar tjänstens namn som hör ihop med meddelandet. Exempel: Jabber, Yahoo, MSN.

`%textbackgroundcolor{X}%`

  Nyckelordet används för att representera markerad bakgrundsfärg i &kopete;. Ignorerar parametern inom parentes och använder det bara som `%textbackgroundcolor{}`.

`%senderStatusIcon%` (utökning av &kopete;)

  Visar kontaktens statusikon som hör ihop med meddelandet. Det är en filsökväg.

`%senderColor%`
`%senderColor{N}%` (utökning av &kopete;)

  Skapa en färg från avsändarens kontaktidentifikation. Kan användas för att visa en annan färg för kontaktens smeknamn.

  `%senderColor{N}%` där N är ett positivt tal. Om N är större än 100 representerar det en ljusare färg än kontaktens färg. Om N är lika med 150 är det en färg som är 50 % ljusare. Om N är mindre än 100 är det en mörkare färg. Användbar för att låta bakgrunden färgas olika för varje kontakt.

  Om du vill använda färgerna i en variant, men inte i huvudstilen, finns ett sätt att komma runt det.

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

  Du kan använda färgen för elementet p.message i filen `main.css`, och skriva något som liknar följande i varianten:

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

#### Nyckelordslista gemensam för meddelanden och Status.html

`%message%`

  Själva meddelandet. Det är ett HTML-fragment.

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

  Tiden då meddelandet togs emot. `%time%` använder standardtidformatet för den aktuella landsinställningen. Om du vill använda ett specifikt tidformat, använd `%time{X}%` där X är en sträng som innehåller tidformatet. Tidparametrarna är samma som i glibc-funktionen `strftime`. Skriv `man strftime` för att få en lista med tillgängliga parametrar.

`%messageDirection%` (utökning av &kopete;)

  Representerar meddelandets riktning, om meddelandet måste visas skrivet från höger till vänster eller från vänster till höger.Värden är antingen "rtl" eller "ltr". Läs Guide för meddelanderiktning för att ta reda på hur nyckelordet används på ett riktigt sätt.

## Stilguide för chattfönster i &kopete;

Stilguide för chattfönster i &kopete; är en uppsättning saker som din chattfönsterstil måste stödja för att fungera tillsammans med Kopete.

### Stöd markeringar

Stilen måste visa markeringar. I Kopete och Adium ersätts `%textbackgroundcolor{}%` med markeringsfärgen. Lägg till stilattributet `background-color: %textbackgroundcolor{}%` i HTML-elementet som visar meddelandet.

### Meddelandemallar för efterföljande meddelanden krävs.

Denna guide är till för dem som skriver om gamla XSL-stilar till det nya formatet. Alla stilar måste tillhandahålla en mall för efterföljande meddelanden. Det är nu en standardfunktion.

### Använd kodningen UTF-8.

Rubriken säger allt. Du måste spara filerna som UTF-8.

### Tillhandahåll `Contents/Info.plist` för att fungera tillsammans med Adium

Filen `Contents/Info.plist` används inte ännu i Kopete, men om du vill att stilen ska fungera tillsammans med Adium måste du tillhandahålla filen. Här är en grundläggande exempelfil. Strängar att ersätta omges av "$".

    <?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
    >$Your style full name$</string>
            <key
    >CFBundleIdentifier</key>
            <string
    >$Your style ID in the form: com.adiumx.smooth.operator.style$</string>
            <key
    >CFBundleInfoDictionaryVersion</key>
            <string
    >1.0</string>
            <key
    >CFBundleName</key>
            <string
    >$Your style name here$</string>
            <key
    >CFBundlePackageType</key>
            <string
    >AdIM</string>
            <key
    >MessageViewVersion</key>
            <integer
    >3</integer>
    </dict>
    </plist>

### Tillhandahåll `buddy_icon.png`

Du måste placera en fil som heter `buddy_icon.png` i `Incoming` och `Outgoing`. Bilderna används när kontakten inte har något foto.

### Stöd språk som skrivs från höger till vänster med nyckelordet `%messageDirection%`.

Nyckelordet `%messageDirection%` är till för de språk i världen som skrivs från höger till vänster. Det definierar meddelandets riktning om det är "rtl" (höger till vänster) eller "ltr" (vänster till höger). Lägg till stilattributet i HTML-elementet som visar meddelandet: `direction: %messageDirection%`. Förhandsgranskningen av stilen i utseendeinställningen innehåller en kontroll av att stilen visar höger till vänster riktigt. Den ska visa strängen med början från höger.