# Przewodnik po stylach okna rozmowy &kopete;

## Informacje o stylach okna rozmowy &kopete;

Począwszy od &kopete; 0.12, w stylu okna rozmowy wykorzystywany jest format Adium. Ten format motywów bazuje na szablonach HTML i CSS. Są one łatwiejsze do tworzenia i rozwijania, konieczna jest tylko znajomość HTML i CSS. Styl może mieć również warianty (określone jako plik CSS), podnoszące jego możliwości dostosowania do upodobań użytkownika.

### Krótki przewodnik

Format Adium określa strukturę katalogów, szablony HTML, pliki CSS i słowa kluczowe, które są zastępowane za każdym razem, gdy przetwarzany jest szablon. Końcowym efektem jest okno rozmowy, w postaci strony XHTML, gdzie wiadomości są dodawane operacjami DOM (drzewa obiektów dokumentu). Centralnym elementem jest element div, nazywany `Chat`. Przed i po elemencie div znajdują się szablony Header i Footer. Wiadomości są elementami potomnymi elementu div `Chat`.

#### Struktura katalogu

Styl musi trzymać się określonej struktury katalogów. Kod &kopete; również został napisany z myślą o tej strukturze. Archiwizując styl, musisz zarchiwizować katalog `styleName`. Struktura katalogu odpowiada strukturze pakietu w systemie Mac OS X, jeśli znasz ten system operacyjny, to poczujesz się jak w domu. Musisz zwrócić uwagę na wielkość liter, ponieważ system UNIX rozróżnia małe i wielkie litery.

    styleName\ (może posiadać przyrostek .adiumMessageStyle, ponieważ w Mac OS X jest to pakiet)
            Contents\
                    Info.plist
                    Resources\
                            main.css
                            Header.html
                            Footer.html
                            Status.html
                            Incoming\ (i Outgoing\)
                                    Content.html
                                    NextContent.html (dla kolejnych wiadomości)
                                    Context.html (dla historii wiadomości)
                                    NextContext.html
                                    Action.html
                            Variants\
                                    *.css

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

Jest to specjalny element div używany wewnętrznie. To symbol zastępczy, który ma wskazywać, gdzie wstawić następną wiadomość. Jeśli to nowa wiadomość, stara wiadomość jest usuwana, a jej miejsce zajmuje nowa. Ale jeśli to kolejna wiadomość, element div jest zastępowany zawartością nowej wiadomości. Specjalny element div jest wymagany w szablonach Content, Context, NextContent, NextContext. Ale można go również umieścić w szablonach Action i Status.

#### Szablony HTML

##### Opis szablonu

`Header.html` (Wymagany)

  Użyj szablonu Header, aby wyświetlić nad rozmową ładny nagłówek. Ten szablon jest umieszczany przed elementem div `Chat`. Jeśli nie chcesz z tego korzystać, umieść tam pusty plik.

`Footer.html` (Wymagany)

  Podobny do szablonu Header, ale umieszczany jest w stopce rozmowy. Ten szablon jest wstawiany po elemencie div `Chat`. Jeżeli nie będziesz go używać, umieść tam pusty plik.

`Status.html` (Wymagany)

  Ten szablon jest używany do wyświetlania wewnętrznych komunikatów. Chodzi o komunikaty typu zmiana statusu, czy komunikaty od Kopete (np. o nadchodzącym pliku). Jeśli styl nie zawiera szablonu Action, szablon Status używany jest do wyświetlania komunikatów Action.

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

  Szablon Content to główna część okna wiadomości. Traktuj go jak blok zawierający wiadomości. Upewnij się, że jest w stanie dodawać kolejne wiadomości, nie projektuj go tak, by wyświetlił tylko jedną. Kolejne wiadomości będą umieszczane w elemencie div insert.

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

  Szablon NextContent to element z wiadomością dla kolejnych wiadomości. Zostanie on wstawiony do głównego bloku wiadomości. Szablon HTML powinien zawierać tylko minimum konieczne do wyświetlenia wiadomości.

`Incoming/Action.html`
`Outgoing/Action.html` (Opcjonalne) (Rozszerzenie &kopete;)

  Ten szablon jest rozszerzeniem &kopete; w stosunku do formatu Adium. Jest dostępny dla kierunku przychodzącego i wychodzącego. Wiadomości Action to specjalne wiadomości informujące o tym, że podejmujemy jakieś działanie. Przykład: "/me instaluje &kopete;" będzie wyświetlane jako "DarkShock instaluje &kopete;".

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

  Te szablony nie są stosowane w Kopete. W formacie Adium są używane do wyświetlania historii. Bardzo przypominają szablony Content i NextContent, jedynie kilka elementów odróżnia je od zwykłych wiadomości.

#### Style CSS i warianty

Szablony HTML są używane do opisu utworzonej struktury. Cały styl jest opisany jednak w plikach CSS. `main.css` to główny styl, a warianty to odmiany głównego stylu. Przykładem wariantu są zmienione kolory, czy brak pokazanego zdjęcia użytkownika. Zarówno `main.css`, jak i warianty są dołączane do wynikowej strony XHTML.

##### `main.css`

Jest to główny plik CSS, który jest wspólny dla wszystkich wariantów. W tym pliku powinien być zawarty cały główny opis stylu.

##### Warianty

Warianty to pliki CSS umieszczone w katalogu `Variants/`. Każdy wariant to pojedynczy plik CSS, który dołącza do siebie `main.css` i wprowadza modyfikacje głównego stylu.

#### Usuwanie błędów ze stylów

Oto dwie wskazówki pomagające wypróbować utworzony styl.

##### Zapisz próbną rozmowę

W oknie rozmowy możesz zapisać dyskusję. Jest to kopia wyświetlanej, wewnętrznej strony XHTML. Otwórz ją w przeglądarce Konqueror, aby przetestować Twoje pliki CSS.

##### Wyłącz buforowanie stylu

Parametr konfiguracji &kopete; pozwala wyłączyć buforowanie stylu. Gdy buforowanie jest wyłączone, szablony HTML są wczytywane ponownie za każdym razem, gdy pojawia się prośba o styl. Dodaj poniższe wiersze do Twojego pliku `kopeterc`. Jest to bardzo użyteczne przy testowaniu stylów w &kopete;.

    [KopeteStyleDebug]
    disableStyleCache=true

### Słowa kluczowe

Słowa kluczowe są jak puste miejsca do wypełnienia szczegółami. Z nadejściem nowej wiadomości, są one zastępowane prawidłową wartością, odpowiadającą kontekstowi. Aby możliwa była pełna obsługa funkcji w Kopete, dodane zostało kilka rozszerzeń słów kluczowych do Adium. Również niektóre słowa kluczowe są dostępne tylko w pewnym kontekście.

#### Słowa kluczowe dla szablonów Header i Footer

Te słowa kluczowe są przetwarzane na początku rozmowy.

`%chatName%`

  Jest to nazwa bieżącej sesji rozmowy. W typowej sesji, wyświetlana jest nazwa rozmówcy i jego status. W przypadku IRC pokazywany jest temat kanału.

`%sourceName%`
`%destinationName%`

  Są to nazwy uczestników rozmowy. `%sourceName%` to Twoja nazwa. `%destinationName%` to nazwa osoby z którą rozmawiasz. Zalecamy używanie `%chatName%`, ponieważ dwa pozostałe mogą wprowadzać w błąd w rozmowach grupowych i IRC.

`%incomingIconPath%`
`%outgoingIconPath%`

  Są to obrazy/zdjęcia/awatary uczestników rozmowy. Incoming przedstawia zdjęcie rozmówcy, a Outgoing Twoje własne zdjęcie. Jeśli brak jest dostępnych zdjęć, użyty zostanie obrazek `buddy_icon.png`, znajdujący się w katalogu `Incoming` lub `Outgoing`.

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

  To czas rozpoczęcia rozmowy. `%timeOpened%` używa domyślnego formatu czasu dla bieżącego czasu lokalnego. Jeśli chcesz używać określonego formatu czasu, użyj `%timeOpened{X}%`, gdzie X jest ciągiem zawierającym format czasu. Parametry formatu czasu są te same co w funkcji glibc `strftime`. Wpisz `man:strftime` w oknie &konqueror-dopelniacz; , aby otrzymać listę dostępnych parametrów.

#### Słowa kluczowe dla szablonów Content, NextContent, Context, NextContext, Action

Te słowa kluczowe są przetwarzane dla każdej wiadomości.

`%userIconPath%`

  Jest to obraz/zdjęcie/awatar osoby powiązanej z wiadomością. Jeśli zdjęcie nie jest dostępne, użyty zostanie obrazek `buddy_icon.png`, znajdujący się w katalogu `Incoming` lub `Outgoing`, w zależności od kierunku wiadomości.

`%senderScreenName%`

  To identyfikator osoby powiązany z wiadomością. Przykłady: me@hotmail.com, 45566576, JohnSmith.

`%sender%`

  To nazwa osoby powiązana z wiadomością. Używa wyświetlanej nazwy metakontaktu jako źródła.

`%service%`

  Zawiera nazwę serwisu powiązaną z wiadomością. Przykłady: Jabber, Yahoo, MSN.

`%textbackgroundcolor{X}%`

  To słowo kluczowe jest używane w &kopete; do przedstawienia tła podświetlenia. Zignoruj parametr w nawiasach klamrowych i używaj tylko jako `%textbackgroundcolor{}`.

`%senderStatusIcon%` (Rozszerzenie &kopete;)

  Wyświetla ikonę stanu kontaktu powiązaną z wiadomością. Jest to ścieżka do pliku.

`%senderColor%`
`%senderColor{N}%` (Rozszerzenie &kopete;)

  Tworzy kolor z identyfikatora osoby wysyłającej. Może być używane do wyświetlenia odmiennego koloru dla pseudonimu kontaktu.

  `%senderColor{N}%`, gdzie N jest liczbą dodatnią. Jeśli N jest większe niż 100, wówczas przedstawia kolor jaśniejszy niż kolor czcionki kontaktu. Jeśli N jest równe 150 to jest to kolor, który jest jaśniejszy o 50%. Jeśli N jest mniejsze niż 100, to wówczas kolor jest ciemniejszy. Może służyć w do zróżnicowania tła każdego kontaktu.

  Jeśli chcesz używać tych kolorów w wariantach, a nie w stylu głównym, musisz zastosować sztuczkę.

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

  możesz zastosować kolor dla p.message w Twoim pliku `main.css`, a w wariancie musisz zrobić tak

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

#### Wspólne słowa kluczowe dla wiadomości i Status.html

`%message%`

  To właściwa wiadomość, która jest fragmentem HTML.

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

  Czas otrzymania wiadomości. `%time%` korzysta z domyślnego formatu czasu dla czasu lokalnego. Jeśli chcesz używać określonego formatu czasu, użyj `%time{X}%`, gdzie X jest ciągiem zawierającym format czasu. Parametry czasu są te same co w funkcji glibc `strftime`. Wpisz `man:strftime` w oknie &konqueror-dopelniacz;, aby otrzymać listę dostępnych parametrów.

`%messageDirection%` (Rozszerzenie &kopete;)

  Określa kierunek wiadomości, jeśli wiadomość musi być wyświetlana od prawej do lewej lub od lewej do prawej. Wartością może być "rtl" lub "ltr". Przeczytaj reguły Kierunek wiadomości, aby zobaczyć jak używać tego słowa kluczowego poprawnie.

## Reguły stylów okna rozmowy &kopete;

Reguły stylu okna rozmowy &kopete; określają, co styl ma obsługiwać, aby być zgodnym z Kopete.

### Obsługa podświetlenia

Twój styl musi umożliwiać podświetlenie. W Kopete i Adium `%textbackgroundcolor{}%` jest zastępowany kolorem podświetlenia. Dodaj ten atrybut stylu: `background-color: %textbackgroundcolor{}%` do elementu HTML wyświetlającego wiadomość.

### Wymagane są szablony kolejnych wiadomości

Ta reguła odnosi się do ludzi przekształacających stare style XSL do nowego formatu. Wszystkie style muszą posiadać szablon dla kolejnych wiadomości. Jest to obecnie domyślna funkcja.

### Używaj kodowania UTF-8

Tytuł mówi wszystko. Musisz zapisywać pliki w UTF-8.

### Dodaj `Contents/Info.plist` dla zgodności z Adium

Plik `Contents/Info.plist` nie jest jeszcze używany w Kopete. Ale jeśli chcesz, by Twój styl był zgodny z Adium, musisz zamieścić ten plik. Oto prosty przykład pliku. Ciągi do zastąpienia znajdują się pomiędzy "$".

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

### Dodaj `buddy_icon.png`

Musisz umieścić plik o nazwie `buddy_icon.png` w katalogach `Incoming` i `Outgoing`. Te obrazy zostaną użyte, gdy nie ma zdjęcia rozmówcy.

### Obsługa języków od prawej do lewej za pomocą słowa kluczowego `%messageDirection%`

Dostępne jest słowo kluczowe `%messageDirection%` dla języków pisanych od prawej do lewej. Określa ono kierunek wiadomości: "rtl"(od prawej do lewej) lub "ltr"(od lewej do prawej). Dodaj ten atrybut stylu do elementu HTML wyświetlającego wiadomość: `direction: %messageDirection%`. Podgląd stylu w konfiguracji wyglądu zawiera tekst pisany od prawej do lewej, w celu sprawdzenia, czy styl jest wyświetlany poprawnie. Napis powinien rozpoczynać się od prawej.