Встраивание виртуального тура на krpano в сайт

Встраивание виртуального тура на krpano в сайт

Введение

Встраивание плеера krpano в страницу сайта максимально автоматизировано и упрощено до
• добавления в код страницы одного скрипта и
• одной строчки кода с параметрами встраивания.

В функции скрипта входит определение типа движка, который будет использоваться(flash или html5) и обработка ограничений по функциональности (они связаны с ОС, браузером и способами ввода) Как правило, этот скрипт и плеер находятся в одном JS-файле, чаще всего он называется tour.js. В сборке krpano он хранится отдельно в файле embedpano.js.

Функции скрипта embedpano.js

  1. Инициация плеера и встраивание его в веб-страницу;
  2. Автоматическое определение типа движка (flash или html5);
  3. Исправление функциональности колеса мыши, связанное с прокруткой страницы, зуммированием, поддержкой Mac OS, с тачпадом и нормализацией скорости вращения);
  4. Исправление ограничений флеш-плеера при использовании непрозрачности и перекрытия слоёв, если wmode = transparent/opaque;
  5. Подключение возможности перехода в полноэкранный режим для flash;
  6. Встраивание своего кода в код плеера виртуального тура.

Встраивание скрипта

Встраивание осуществляетя в любом месте кода веб-страницы один раз так:

<script src="embedpano.js"></script>

или, когда скрипт совмещён с html5-плеером, так:
<script src="tour.js"></script>

Встраивание плеера

Для встраивания плеера в нужном месте кода веб-страницы добавляется элемент <div>, которому присваиватся уникальный css-идентификатор и определяется размер с помощью стиля css:

<div id="pano" style="width:100%; height:100%;">
...
</div>

Внутри этого элемента нужно прописать вызов метода embedpano(), который создаст плеер:

<div id="pano" style="width:100%;height:100%;">
    <noscript>
        <table style="width:100%;height:100%;"><tr style="valign:middle;"><td><div style="text-align:center;">ERROR:<br/><br/>Javascript not activated<br/><br/></div></td></tr></table>
    </noscript>
    <script>
        embedpano({swf:"tour.swf", xml:"tour.xml", target:"pano", html5:"prefer", passQueryParameters:true});
    </script>
</div>

Функция встраивания в качестве аргумента принимает объект с параметрами встраивания.

Параметры встраивания

Метод embedpano() требует на входе только один объект, через который в произвольном порядке передаются все параметры в виде parametername:value.
Все параметры, кроме target, можно опустить, и тогда вместо них будут подставлены значения по умолчанию:

swf:"krpano.swf"

Имя и путь к файлу плеера flash. Значение по умолчанию "krpano.swf", чаще всего вместо него используется "tour.swf"

js:"krpano.js"

Имя и путь к файлу плеера html5. По умолчанию будет использован параметр swf, в котором расширение будет изменено на .js. Этот параметр игнорируется, когда плеер встроен в скрипт встраивания.

xml:"krpano.xml"

Имя файла с начальной xml-спецификацией и путь к ней. По умолчанию используется то же имя, что и для плееров. Чаще всего вместо него используется "tour.xml".

target:"...pano-div-id..."

Идентификатор элемента разметки, в который будет встроен плеер. Если параметр не установлен, будет вызвана ошибка "alert()".

id:"krpanoSWFObject"

Идентификатор внутреннего объекта плеера, который можно использовать для взаимодействия с плеером через javascript-интерфейс. Значение по умолчанию "krpanoSWFObject". Важно помнить, что для каждого экземпляра плеера используется уникальный id. Если объект с данным id уже существует, скрипт встраивания припишет порядковый номер в конце.

bgcolor:"#000000"

Цвет фона плеера в формате html. По умолчанию чёрный(#000000).

wmode:"..."

Определение параметра Window Mode для флеш-плеера. Возможные параметры:
• window — значение по умолчанию, компромисс между возможностями и скоростью работы. Во многих браузерах и системах элементы разметки не могут перекрывать окно плеера;
• opaque — разрешить перекрытие окна плеера (работает медленнее);
• transparent — в добавление к перекрытию позволяет сделать видимыми элементы разметки позади окна плеера(работает ещё медленнее);
• direct — режим наилучшей производительности, с использованием аппаратного ускорения. Нет возможности перекрытия, ограниченная совместимость со старыми системами и браузерами.

Примечание для html5: Параметр wmode=transparent будет обработан движком плеера, что позволит сделать его полупрозрачным. Перекрытие окна плеера доступно всегда.

html5:"auto"

Определяет приоритет использования для движка html5.
• auto — выбирает html5 только в случае, если не поддерживается flash;
• prefer — по возможности использовать html5, flash будет использован только если html5 не поддерживается;
• fallback — режим предпочтения flash, в котором html5 рассматривается как запасной вариант;
• only — всегда использовать html5. Если он не поддерживается, будет выдана ошибка;
• always — всегда использовать html5 независимо от наличия поддержки. Используется только для отладки и тестирования;
• never — не использовать html5.

Также введены расширительные настройки, необходимые для тестирования:

• webgl;
• css3d,

Они задают технологию рендеринга. Примеры:

html5="auto+css3d"
html5="prefer+webgl"

По умолчанию выбирается технология WebGL, за исключением случаев:
• В iOS не доступна, поэтому по умолчанию используется технология css3d;
• В браузерах для Android, основанных на webview и поддерживающих webgl возможны проблемы с производительностью и рендирингом на разных устройствах, поэтому по умолчанию используется технология css3d;
• В Android Firefox до версии 22 из-за низкой производительности по умолчанию используется css3d. В версиях 22 и выше по умолчанию используется WebGL.

vars:{...}

Передаёт объект с параметрами krpano, позволяет установить начальные параметры krpano. Также можно установить любые параметры плеера. Параметры будут установлены или перезаписаны после загрузки основного xml и его обработки.

basepath:...

Базовый путь к swf-файлу, который затем можно использовать для разрешения относительных путей. Может быть использован как во flash, так и в html5 для разрешения относительных путей в xml.

consolelog:false

Установка определяет, будут ли посылаться сообщения об ошибках плеера в консоль браузера.

mwheel:true

Определяет порядок использования колеса мыши. В случае установки true, события, вызываемые колесом мыши, будут обработаны в плеере, иначе они будут проигнорированы плеером и обработаны браузером(для прокрутки страницы).

onready:...Javascript-Function...

Позволяет установить вызов функции в момент, когда плеер готов к работе. Вызов осуществляется через javascript-интерфейс, например:

embedpano({target:"krpanoDIV", onready:krpanoReady});
function krpanoReady(krpano)
{
    krpano.call("trace(krpano is ready...)");
}

Примечание для флеш-плеера. Эта функция требует открытого внешнего интерфейса флеш-плеера (External Interface). При работе оффлайн вызов onready сработает только после изменения настроек безопасности флеш-плеера. Подробнее.

onerror:...Javascript-Function...

Позволяет использовать произволную функцию-обработчик ошибок. Эта функция будет вызвана с параметром в виде строки с сообщением об ошибке.

passQueryParameters:false

Когда установлено в true, все параметры из ссылки будут переданы в плеер. Так же все установки из ссылки можно будет передать в html5-плеер. Это делает возможным переключаться между движками flash и html5 с помощью разных ссылок.

Параметры запуска

Существует группа параметров, которые определяют встраивание и не передаются в плеер.

xml

Позволяет задать произвольное имя для стартового файла. Если параметр опущен, в качестве значения по умолчанию будет взято имя swf-файла.

simulatedevice

Параметр, позволяющий запустить плеер в режиме отладки для разных устройств. Возможные значения:
• iphone для iPhone, iPod;
• ipad для всех iPad;
• useragent — имитация устройства, зависящего от User-Agent;
• androidmobile — смартфон на Android, только на движке flash;
• android/androidtablet — планшет на Android.

Для отладки на мобильных устройствах существует специальный симулятор, хранящийся в папке krpano/examples/iphone-ipad-simulator

Прекращение работы плеера

Для удаления экземпляра плеера необходимо использовать функцию removepano(). Эта функция удаляет все настройки мыши, элементы DOM и события HTML5. В качестве параметра функция получает id экземпляра плеера.

embedpano({target:"panoDIV", id:"pano1"});

...

removepano("pano1");

Примечания по использованию на мобильных устройствах

Рекомендуются следующие настройки в html:
• всегда использовать тип документа HTML5: <!DOCTYPE html>;
• для корректного pixel-perfect отображения любое автоматическое масштабирование страницы и области просмотра должно быть отключено. Это можно сделать с помощью тега <meta> внутри тега <head>:

<meta name="viewport" content="target-densitydpi=device-dpi, width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no" />

• Не используйте тег <iframe> для встраивания плеера, встраивайте плеер напрямую в страницу. Причина:при использовании iframe невозможно контролировать масштабирование в области вывода, поэтому элементы интерфейса тура отобразятся в неправильном размере.

Примечание: параметр target-densitydpi=device-dpi распознаётся только устройствами на Android, и может вызвать консольные предупреждения в других браузерах(iOS, Chrome(sic!), ...). Это предупреждение можно проигнорировать.

Примеры

1. Простой пример.

    <script> embedpano({target:"pano"}); </script>

Опущены все необязательные параметры, поэтому будут использованы значения по умолчанию: «krpano.swf», «krpano.xml», «krpanoSWFObject» и 100% для размера.

2. Расширенные настройки для первого примера.

    <script>
        embedpano({swf:"pano.swf", xml:"pano.xml", target:"pano"});
    </script>

3. Настройка приоритетности для движка html5.

    <script>
        embedpano({swf:"pano.swf", xml:"pano.xml", target:"pano", html5:"prefer"});
    </script>

4. Настройка перекрытия.

    <script>
        embedpano({swf:"pano.swf", xml:"pano.xml", target:"pano", wmode:"opaque"});
    </script>

5. Выборочное использование html5: предпочитать только на Android и сенсорных устройствах с IE10.

    <script>
        function selecthtml5usage()
        {
            // check for Android:
            if( navigator.userAgent.indexOf("Android") >= 0 )
            return "prefer"

            // check for IE10 with multi-touch display:
            if( (navigator.msMaxTouchPoints|0) > 1 )
            return "prefer"

            // for all other cases use html5=auto:
            return "auto";
        }

        embedpano({xml:"pano.xml", target:"pano", html5:selecthtml5usage()});
    </script>

Источник

Статья основана на переводе руководства для версии krpano 1.17