# Довідник зі створення стилів вікна балачки &kopete;

## Довідка зі стилів вікна балачки &kopete;.

Починаючи з версії &kopete; 0.12, у програмі для стилів вікон балачки використовується формат Adium. Формат тем засновано на шаблонах HTML і CSS. Їх стало простіше створювати і розробляти, для цього потрібне лише знання HTML і CSS. Крім того, стилі можуть мати варіанти (які визначено у вигляді CSS), що надає додаткові можливості з налаштування :).

### Довідник.

Формат Adium складається з структури каталогів, шаблонів HTML, файлів CSS і ключових слів, які буде замінено кожного разу під час обробки шаблонів. Остаточна розмова є сторінкою XHTML, повідомлення на яку додаються за допомогою дій DOM. Центральним елементом є елемент div з назвою `Chat`. Перед і після цього елемента div розташовуються шаблони Шапки і Підвалу. Повідомлення є дочірніми об’єктами елемента div `Chat`.

#### Структура каталогів

Вам слід дотримуватися цієї структури каталогів. Код &kopete; працює лише за умов дотримання такої структури. Якщо вам потрібно буде створити архів зі стилем, вас слід буде заархівувати каталог `styleName`. Структура каталогу повторює структуру елемента-зв’язки у Mac OS X, якщо ви маєте уявлення про цю операційну систему. Крім того, вам слід дотримуватися регістру символів, оскільки системи UNIX розрізняють назви у верхньому і нижньому регістрах.

    styleName\ (може мати суфікс .adiumMessageStyle, для сумісності з Mac OS X)
            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

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

Це особливий елемент div, який використовується всередині програми. Це заповнювач, який позначає місце, куди слід вставляти наступне повідомлення. Якщо цим повідомленням буде нове повідомлення, заповнювач буде вилучено, розпочнеться елемент нового повідомлення. Але якщо це послідовне повідомлення, елемент div буде заміщено вмістом нового повідомлення. Це особливий елемент div потрібен у шаблонах Content, Context, NextContent, NextContext. Хоча не завадить додати його і до шаблонів Action і Status.

#### Шаблони HTML.

##### Опис шаблона.

`Header.html` (Обов’язково)

  Шаблон Header слід використовувати для показу заголовка розмови. Цей шаблон буде вставлено перед елементом div `Chat`. Якщо ви не використовуєте заголовки, просто вставте порожній файл.

`Footer.html` (Обов’язково)

  Цей шаблон загалом подібний до Header, але його призначено для підвалу сторінки розмови. Цей шаблон додається після елемента div `Chat`. Якщо ви не використовуєте підвали, просто вставте порожній файл.

`Status.html` (Обов’язково)

  Цей шаблон використовується для показу внутрішнього повідомлення. Внутрішні повідомлення, такі як зміна стану, повідомлення від Kopete (наприклад, Передавання вхідного файла). Якщо у стилі немає шаблону Action, цей шаблон використовується для показу повідомлень про дії (Action).

`Incoming/Content.html`
`Outgoing/Content.html` (Обов’язково)

  Вмістом цього шаблона є текст повідомлення. Цей шаблон можна вважати блоком, що містить повідомлення. Переконайтеся, що у цьому шаблоні можна приймати послідовні повідомлення, не робіть його таким, що пристосований лише для одинарних повідомлень. Послідовні повідомлення буде вставлено у елемент div insert.

`Incoming/NextContent.html`
`Outgoing/NextContent.html` (Обов’язково)

  Шаблон NextContent — це фрагмент повідомлення для послідовних повідомлень. Його буде вставлено у головний блок повідомлення. У шаблоні HTML має міститися мінімальна кількість команд для показу повідомлення.

`Incoming/Action.html`
`Outgoing/Action.html` (Необов’язково) (Додаток до &kopete;)

  Цей шаблон є додатком &kopete; до формату Adium. Його можна використовувати для обох напрямків: вхідного і вихідного. Повідомлення про дії — це особливий вид повідомлень, за допомогою яких можна повідомити про дії, які ви виконуєте. Приклад: «/me встановлює &kopete;» буде показано як «DarkShock встановлює &kopete;».

`Incoming/Context.html`
`Incoming/NextContext.html`
`Outgoing/Context.html`
`Outgoing/NextContext.html` (Необов’язково)

  Ці шаблони у Kopete не використовуються. У Adium їх призначено для показу історії повідомлень. Загалом цей шаблон подібний до Content і NextContent, але має деякі відмінності, за допомогою яких його можна відрізнити від звичайних повідомлень.

#### Про стилі CSS і Варіанти

У шаблоні HTML буде описано структуру стилю. Але самі стилі описуються за допомогою файлів CSS. У файлі `main.css` описано головний стиль, всі варіанти є лише наслідками зміни головного стилю. Прикладами варіантів є зміна кольорів, вимикання показу фотографій користувачів. Обидва різновиди таблиць стилів, `main.css` і варіанти, буде імпортовано до остаточної сторінки XHTML.

##### -`main.css`

Це головний файл CSS, який є спільним для всіх варіантів. У цьому файлі повинні міститися всі головні описи стилю.

##### -Variants

Варіанти — це файли CSS, розташовані у каталозі `Variants/`. Кожен з варіантів є окремим файлом CSS, у який включено файл `main.css`, а потім описано зміни у головному стилі.

#### Стилі для зневаджування

Ось дві підказки для випробування стилю під час його створення.

##### -Збережіть зразок розмови.

За допомогою функцій вікна балачки ви можете зберегти якусь розмову. Результатом збереження буде копія показаної внутрішньої сторінки XHTML. Скористайтеся цією сторінкою, щоб за допомогою Konqueror перевірити ваші файли CSS.

##### -Вимкніть кеш стилів.

У налаштуваннях існує невеличкий перемикач, за допомогою якого можна вимкнути кешування стилів. Якщо скористатися цим перемикачем, шаблони HTML будуть перезавантажуватися після кожного запиту на стиль. Для того, щоб скористатися можливостями перемикача, вам слід додати наведені нижче рядки для файла `kopeterc`. Цей перемикач дуже корисний під час перевірки стилів у &kopete;

    [KopeteStyleDebug]
    disableStyleCache=true

### Довідка з ключових слів

Ключові слова схожі на отвори у програмі, у які ви можете заповнити власними значеннями. У кожному з нових повідомлень їх буде замінено на значення, які відповідають контексту. Для повноцінної підтримки всіх можливостей Kopete авторами було додано декілька додатків ключових слів до Adium. Крім того, ключові слова доступні лише у певному контексті.

#### Список ключових слів для шаблонів Header і Footer.

Тут наведено ключові слова, які оброблятимуться на початку балачки.

`%chatName%`

  Це назва файла поточного сеансу балачки. Для типового сеансу у цій назві відображено назву контакту і його стан. У випадку IRC за назвою також можна встановити тему каналу.

`%sourceName%`
`%destinationName%`

  Це імена контактів у сеансі балачки. `%sourceName%` — це ваше ім’я. `%destinationName%` — це ім’я контакту, з яким ви спілкуєтеся. Перевагу над використанням зазначених вище ключових слів слід надавати `%chatName%`, оскільки попередні параметри може бути оброблено неправильно у груповій балачці або IRC.

`%incomingIconPath%`
`%outgoingIconPath%`

  Ці ключові слова позначають зображення, фотографію або аватар контактів під час сеансу балачки. У вхідному потоці це буде фотографія контакту, а у вихідному — ваша власна фотографія. Якщо таких фотографій виявлено не буде, буде використано зображення `buddy_icon.png`, розташовані у каталогах `Incoming` або `Outgoing`.

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

  Це час, коли було розпочато балачку. У `%timeOpened%` буде використано типовий формат часу для поточної локалі. Якщо ви бажаєте використовувати особливий формат часу, скористайтеся ключовим словом `%timeOpened{X}%`, де X — це рядок, у якому міститься формат часу. Параметри часу збігаються з параметрами часу функції `strftime` бібліотеки glibc. Щоб отримати список можливих параметрів, виконайте у командній оболонці команду `man strftime`.

#### Список ключових слів для шаблонів Content, NextContent, Context, NextContext, Action

Тут наведено список ключових слів, які обробляються для кожного з повідомлень.

`%userIconPath%`

  Це зображення, фотографія або аватар контакту, пов’язаного з поточним повідомленням. Якщо фотографії не буде знайдено, буде використано зображення `buddy_icon.png`, яке знаходиться у каталозі `Incoming` або `Outgoing`, залежно від напрямку повідомлення.

`%senderScreenName%`

  Це ідентифікатор контакту, пов’язаного з даним повідомленням. Приклади: me@hotmail.com, 45566576, JohnSmith.

`%sender%`

  Це ім’я контакту, пов’язаного з поточним повідомленням. Як джерело буде використано екранне ім’я метаконтакту.

`%service%`

  Показує назву служби, пов’язаної з поточним повідомленням. Приклади: Jabber, Yahoo, MSN.

`%textbackgroundcolor{X}%`

  У &kopete; це ключове слово відповідає кольору тла підсвічування. Не використовуйте параметр у фігурних дужках, користуйтеся лише формою `%textbackgroundcolor{}`.

`%senderStatusIcon%` (Додаток до &kopete;)

  Відповідає піктограмі стану контакту, пов’язаного з поточним повідомленням. Значенням є адреса файла.

`%senderColor%`
`%senderColor{N}%` (Додаток до &kopete;)

  Створює колір за ідентифікатором контакту відправника. Можна використовувати для показу прізвиська контакту іншим кольором.

  `%senderColor{N}%`, де N — додатне число. Якщо N більше за 100, колір буде світлішим за колір контакту. Якщо N рівне 150, колір буде на 50% світлішим. Якщо N менше за 100, колір буде темнішим. Корисно для зміни кольору тла для кожного з контактів.

  Якщо ви бажаєте скористатися цими кольорами у одному з варіантів, а не у головному стилі, існує один обхідний шлях:

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

  ви можете застосувати колір до елемента p.message у вашому файлі `main.css`, а у файл варіанта вставити такий код:

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

#### Список ключових слів, спільних для повідомлень і Status.html

`%message%`

  Саме повідомлення. Значенням є фрагмент коду HTML.

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

  Час, коли було отримано повідомлення. У `%time%` буде використано типовий формат часу поточної локалі. Якщо ви бажаєте використовувати особливий формат часу, скористайтеся ключовим словом `%time{X}%`, де X — це рядок, у якому міститься формат часу. Параметри часу збігаються з параметрами часу функції `strftime` бібліотеки glibc. Щоб отримати список можливих параметрів, виконайте у командній оболонці команду `man strftime`.

`%messageDirection%` (Додаток до &kopete;)

  Відповідає напрямку тексту у повідомленні: чи слід показувати текст повідомлення у напрямку справа-ліворуч, чи у напрямку зліва-праворуч. Значеннями можуть бути: «rtl» (справа-ліворуч) або «ltr» (зліва-праворуч). Щоб побачити як працює це ключове слово, прочитайте розділ Настанови щодо напрямку тексту у повідомленні.

## Настанови зі створення стилів вікна балачки &kopete;

Настанови зі створення стилю вікна балачки &kopete; — це набір інструкцій, які слід виконати для того, щоб ваш стиль вікна балачки був сумісний з Kopete.

### Підтримуйте підсвічування

У вашому стилі має бути показано підсвічування. У Kopete і Adium `%textbackgroundcolor{}%` буде замінено кольором підсвічування. Додавайте атрибут стилю `background-color: %textbackgroundcolor{}%` до елемента HTML, який відповідає за показ повідомлення.

### Слід використовувати шаблони послідовних повідомлень.

Ці настанови призначено для людей, які наново переписують старі стилі XSL у новому форматі. Всі стилі мають підтримувати шаблон для послідовних повідомлень. Тепер ця можливість є типовою.

### Використовуйте кодування UTF-8.

У заголовку все сказано. Вам слід зберігати свої файли у UTF-8.

### Додавайте файл `Contents/Info.plist` для сумісності з Adium

Файл `Contents/Info.plist` ще не використовується у Kopete. Але якщо ви бажаєте, щоб ваш стиль був сумісним з Adium, вам слід додати і цей файл. Нижче наведено вміст базового файла-прикладу. Рядки, які слід замінити, розташовано між символами «$».

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

### Додавайте `buddy_icon.png`

Вам слід додати файл з назвою `buddy_icon.png` у теки `Incoming` і `Outgoing`. Ці зображення буде використано, якщо контакт не надав фотографії.

### Додавайте підтримку мов з записом справа-ліворуч за допомогою ключового слова `%messageDirection%`.

Ключове слово `%messageDirection%` призначено для використання у системах лівописних системах запису мов. Воно визначає напрямок запису повідомлення: «rtl» (справа-ліворуч) або «ltr» (зліва праворуч). Додавайте цей атрибут стилю до елемента HTML, який відповідає за показ повідомлення, ось так: `direction: %messageDirection%`. Попередній перегляд стилю, у налаштуваннях вигляду, має перевірку правильності показу лівописної системи запису. Відповідний рядок має бути показано у напрямку справа-ліворуч.