Документация

Создание обложки для HTML-скина

Общая информация
Подстановочные параметры
Настройка окна
Специальные элементы
Функции
Перевод на другие языки
Инструкции по доработке существующих обложек
Примеры обложек

Общая информация

Используемые в обложке формулировки ни коим образом не должны вводить пользователя в заблуждение. При обнаружении подобных нарушений, к партнёру будут применены санкции, вплоть до блокировки аккаунта без выплаты средств.

Внешний вид архива с HTML-скином полностью настраивается при помощи соответствующего HTML-документа.

Для отображения страниц обложки используется движок той версии Internet Explorer, которая установлена на компьютере конечного пользователя. Соответственно, при создании обложки следует позаботиться о том, чтобы она одинаково хорошо выглядела как минимум под IE 6, 7 и 8.

Обложка должна представлять собой папку с html-файлами и необходимыми ресурсами (изображениями, скриптами, таблицами стилей, и т.п.), возможно использовать вложенные папки для удобства организации хранения. В этом случае все пути к файлам ресурсов должны указываться относительно основной папки обложки.

Одна из страниц обложки считается "главной", она отображается при запуске. Архив при запуске ищет "главную" страницу, проверяя наличие в папке с обложкой файлов в следующем порядке:
index.html
index.htm
page.html
page.htm

Подстановочные параметры

Архив может автоматически заменять имена специальных подстановочных параметров в html-коде обложки на их значения. Пока список таких параметров невелик:

Имя параметра Значение
%%zm_archivename%% Заданное при упаковке имя архива, или название файла

Настройка окна

Параметры окна отображения задаются при помощи HTML-тэгов input с установленным значением hidden атрибута type следующим образом:
<input type="hidden" id="имя параметра" value="значение параметра" />
Для настройки доступны следующие параметры:

Имя параметра Значение по умолчанию Назначение
zm_title Заданное при упаковке имя архива, или название файла Заголовок окна
zm_width 600 Ширина окна в пикселях
zm_height 500 Высота окна в пикселях
zm_autosize 0 Автоматический подбор ширины/высоты окна по размерам html
zm_vscroll 0 Отображение вертикальной полосы прокрутки
zm_hscroll 0 Отображение горизонтальной полосы прокрутки
zm_border 1 Отображение рамки и заголовка окна
zm_pgtime 20 Время установки в секундах, от 0 до 600 секунд.

Если на какой-то странице параметры не указаны, используются последние заданные значения. Если параметры для какой-то из страниц обложки отличаются от всех остальных, желательно указывать их отдельно для каждой страницы.

Специальные элементы

Часть элементов со специальными ID используются для обмена информацией между обложкой и архивом.

Имя элемента Тип элемента Назначение
Необязательные элементы
zm_caption - Элемент, за который можно "перетаскивать" окно. Полезен при отключении рамки (zm_border=0)
zm_close - Кнопка закрытия окна
zm_path span, input Отображение пути распаковки файлов
zm_browse - Вызов диалога выбора пути распаковки ("Обзор")
zm_files div, table Контейнер для списка файлов (подробности см. ниже)
zm_progress - ID элемента, содержащего прогресс-бар
zm_options div Контейнер для отображения доп. опций (подробности см. ниже)
Обязательные элементы
zm_payform div Контейнер для формы оплаты (подробности см. ниже)
zm_smsinfo a Ссылка на информацию для абонентов
zm_password <input type="text" /> Поле для ввода пароля
zm_unpack - Кнопка запуска распаковки

Элемент zm_caption не должен содержать в себе каких-либо элементов управления, иначе они не будут корректно реагировать на нажатия.

К любой обложке предъявляются следующие требования:
Контейнером для списка файлов может выступать один из двух элементов - DIV и TABLE.
В случае с DIV контейнер заполняется следующими элементами для каждого файла:
<div class='fileitem'><div class='filename'>имя файла</div></div>

В случае с TABLE возможности по форматированию списка гораздо шире. Для каждого файла добавляется следующие элементы:
<tr class='zm_fileitem'>
  <td class='zm_filename'>Имя файла</th>
  <td class='zm_ucsize'>Полный размер</th>
  <td class='zm_csize'>Размер в архиве</th>
  <td class='zm_typename'>Тип файла</th>
  <td class='zm_filetime'>Дата изменения</th>
  <td class='zm_filecrc'>Контрольная сумма CRC32</th>
</tr>
Нечётные строки выделяются дополнительным классом элемента TR:
<tr class='zm_fileitem zm_fileitem_even'>
  <td class='zm_filename'>Имя файла</th>
  <td class='zm_ucsize'>Полный размер</th>
  <td class='zm_csize'>Размер в архиве</th>
  <td class='zm_typename'>Тип файла</th>
  <td class='zm_filetime'>Дата изменения</th>
  <td class='zm_filecrc'>Контрольная сумма CRC32</th>
</tr>

Применить это всё можно, например, вот так:
<style type='text/css'>
  /* скрываем лишние элементы */
  .zm_csize, .zm_filetime { display: none; }

  /* раскрашиваем чётные записи */
  tr.zm_fileitem_even { background-color: #3d3d3d; }
</style>
<div style='height: 200px; width: 90%; overflow: auto;'>
  <table id='zm_files'>

    <!-- Заголовок таблицы -->
    <thead><tr>
      <th class='zm_filename'>Имя файла</th>
      <th class='zm_ucsize'>Полный размер</th>
      <th class='zm_csize'>Размер в архиве</th>
      <th class='zm_typename'>Тип файла</th>
      <th class='zm_filetime'>Дата изменения</th>
      <th class='zm_filecrc'>Контрольная сумма CRC32</th>
    </tr></thead>
    <!-- Заголовок таблицы -->

    <tbody></tbody>
  </table>
</div>
Для использования в Ваших архивах оплаты за открытия, требуется добавить на одну из обязательных страниц контейнер для дополнительных опций (zm_options).
Минимальные размеры контейнера составляют 400 пикселей в ширину и 80 в высоту. Реальный размер может быть и больше, поэтому требуется разрешать для него прокрутку. Например, так:
<div id='zm_options' style='height: 100px; overflow-y: auto;'></div>
Также в обложке на одной из следующих страниц (после контейнера с опциями, но до активации) должен испольоваться наш прогресс, т.е. элемент zm_progress и соответствующие функции (см. ниже).

Пример правильно сделанной обложки можно скачать по ссылке в самом конце страницы.

Функции

Помимо специальных элементов, обмен информацией между архивом и обложкой ведётся также через вызов функции при помощи JavaScript.

При вводе некорректного кода, архив вызывает js-функцию "zm_onbadpassword". Если Вы хотите отобразить какое-то своё сообщение, или как-то ещё отреагировать на это событие, Вам нужно добавить такую функцию на страницу с кнопкой запуска распаковки. У архива есть и стандартная реакция на это событие - отображение сообщения о вводе неверного кода. При использовании своей функции, Вы можете отменить эту реакцию, вернув из функции false.

Пример:
<script type="text/javascript">
  function zm_onbadpassword() {
    alert("Вы ввели неверный код активации");
    return false;
  }
</script>
Для использования прогресса требуется реализовать две js-функции: "zm_onprogress(p)" и "zm_next".

Первая вызывается в процессе работы, в качестве параметра ей передаётся текущее значение прогресса в процентах (0 - 100). Вторая вызывается после окончания работы, и должна переключить страницу на следующую.

Пример:
<script type="text/javascript">
    function zm_onprogress(p) {
        document.getElementById('zm_progress').innerHTML = p + '%';
    }

    function zm_next() {
        window.location='nextpage.html';
    }
</script>

Также, теперь появилась возможность "перехватить" закрытие окна, чтобы показать свой нестандартный диалог закрытия. При попытке закрыть окно вызывается функция "zm_onclose". Если Вы хотите показать свой диалог закрытия, нужно добавить такую функцию на каждую страницу, на которой Вы хотите изменить диалог.
Если требуется при этом отменить стандартную реакцию (стандартный диалог закрытия), из функции нужно вернуть false.

Если требуется принудительно закрыть программу из этого диалога, нужно вызвать метод "window.external.closewindow" с параметром 1.

Пример:
<script type="text/javascript">
    function zm_onclose() {
        document.getElementById('close_box').style.display = '';
        return false;
    }
</script>

<div id="close_box" style="position: absolute; z-index: 20; top: 97px; left: 100px; padding-top: 153px; padding-left: 57px; display: none;">
    <a href="#" onclick="window.external.closewindow(1);">Закрыть</a>
    <a href="#" onclick="document.getElementById('close_box').style.display = 'hidden'; return false;">Отмена</a>
</div>

Перевод на другие языки

HTML-cкин предусматривает возможность перевода обложки на несколько языков. При запуске, архив определяет язык интерфейса ОС, и устанавливает его как свой текущий язык. Если при создании архива Вы отключили автоопределение языка, и выбрали какой-то конкретный язык из списка, то текущим языком станет он. Для обозначения языков используется стандарт ISO 639-1. Обложка может получить эту информацию, прочитав значение свойства lang объекта window.external следующим образом:
var curlang = window.external.lang;
Вы можете установить текущий язык архива, вызвав метод setlang того же объекта, и передав ему в параметрах двухбуквенный идентификатор выбранного языка:
window.external.setlang('en');
Текущий язык влияет только на отображение стандартных сообщений архива, а также на язык формы оплаты. Перевести саму обложку - уже Ваша задача.

Все сообщения, выдаваемые пользователю архивом, можно заменить на свои собственные. При необходимости выдать какое-то сообщение, архив вызывает функцию zm_getstring(str_id, lang), передавая ей ID нужного сообщения и текущий язык. В ответ, Вы должны вернуть архиву либо запрошенное сообщение на нужном языке, либо false, если хотите, чтобы архив использовал стандартный вариант:
<script type="text/javascript">
  var langs = {
    'ru': {
      '2':'Ошибка',
      '3':'Код указан неверно.',
      '4':'Выберите папку для распаковки:',
      ...
    },
    'en': {
      '2':'Error',
      '3':'Wrong code.',
      '4':'Choose destination folder:',
      ...
    }
  };

  function zm_getstring(str_id, lang) {
    var l = langs[lang];
    if ( l != undefined ) {
      var s = l[str_id];
      if ( s != undefined ) {
        return s;
      }
    }
    return false;
  }
</script>

Идентификаторы строк и сами строки перечислены в следующей таблице:

ID строки Строка
1Пакет повреждён, запуск невозможен.
2Ошибка
3Код указан неверно.
4Выберите папку для распаковки:
5Отмена
6Закрыть
7Извлечение файлов...
8Извлечение файлов завершено!
10Сейчас распаковывается (%d/%d): %s
11Файл %s уже существует.\n\nПерезаписать?
12Не совпадает контрольная сумма для файла %s.\n\nРаспаковать файл?
13Распаковка отменена пользователем.
14Неизвестная ошибка %d
15Вы действительно хотите выйти из программы?
16Завершение работы
1001%s ГБ
1002%s МБ
1003%s КБ
1004%s байт
10504Ошибка доступа к папке.\n\nПроверьте права доступа или попробуйте выбрать другую папку.
11670Ошибка при создании файла.\n\nПроверьте возможность записи в папку и свободное место на диске.
11675Ошибка при создании файла.\n\nПроверьте возможность записи в папку и свободное место на диске.

Строки, используемые в форме оплаты, недоступны для подобного "лёгкого" перевода. На данный момент строки для формы оплаты (и все вышеуказанные строки) существуют на русском и английском языках, возможность перевода формы оплаты будет добавлена позже, пока же желающие могут выяснить подробности через тикет-систему.

Инструкции по доработке существующих обложек

Если у Вас уже есть html-обложка, но она изготовлена для работы с другими архивами, Вам не нужно заказывать изготовление ещё одной обложки для работы с нами. Следующие инструкции помогут Вам подготовить её к использованию с нашими архивами без дополнительных затрат.

Всё, что Вам нужно сделать, это сменить в обложке форму оплаты. Для этого нужно найти страницу обложки, которая отвечает за отображение формы оплаты, и заменить форму оплаты на нашу.

Форма оплаты может выглядеть примерно так:
<div id=cm_payform style="height:128px"></div>
<script>
t='';
document.write('<scr'+t+'ipt src="js/def.js"></scr'+t+'ipt>');
document.write('<scr'+t+'ipt src="http://<имя сайта пп>/client_api/payform.php?aid='+archive_id+'"></sc'+t+'ript>');
</script>

Соответственно, всю её нужно заменить нашей формой оплаты:
<div id="zm_payform"></div>
После этого архив сможет полноценно работать с такой обложкой.

Примеры обложек и просмотрщик

Для облегчения процесса создания HTML-обложки, было создано небольшое приложение, позволяющее просматривать Вашу обложку без создания архива.
Скачать его можно здесь: HtmlViewer v0.5.

Также в этот раздел будут постепенно выкладываться общие примеры реализации разных типов обложек для архивов.

Пример установщика на двух языках (русский/английский).
Пример классического установщика с использованием новых возможностей.
Набор обложек из последней версии архиватора с иконками к ним.