krpano 뷰어를 HTML 문서에 삽입하려면 반드시 swfkrpano.js 를 반드시 사용해야 한다. 이 자바스크립트를 사용하면 자체적으로 여러가지 사항을 점검하고, 필요시 자동적으로 설정하게 된다.. 예를 들면 장비/시스템(HTML5 or Flash)을 한다거나, 여러가지 시스템상의 한계(마우스 휠 사용제한 등)를 자동적으로 해결해 주는 등의 역할을 수행한다. 즉, 이 플러그인을 사용하면 파노라마를 쉽고 빠르게 삽입할 수 있다.
swfkrpano.js 의 역할
- Javascript를 사용가능한지 체크
- 적절한 버전의 플래시플레이어가 설치되어 있는지 체크
- HTML5 를 만족하는 브라우저/시스템인지 자동 체크하고, 필요시 자동적으로 HTML5 뷰어를 불러옴.
- 다른 모든 krpano Javascript를 모두 삽입한 하나의 Javascript를 생성할 수 있음. (MAKE PANO, MAKE VTOUR 드롭릿을 사용할때 embedlicenses=true로 설정하면(default) 자동적으로 해결됨)
- Mac OSX에서 마우스 휠을 사용하여 확대/축소 가능
- 페이지 내에서 휠을 사용하여 확대/축소할 때 페이지가 스크롤되지 않도록 막아줌
- wmode=transparent/opaque 로 설정할 때 발생하는 여러가지 제한 사항을 수정해줌
- 플래시플레이어에서 Fullscreen 사용을 활성화시켜줌
- 삽입 코드가 간단함
- 파라미터를 통해 추가적인 기능을 구현할 수 있음
스크립트 삽입
이 삽입 스크립트(swfkrpano.js)는 삽입하려는 페이지 어딘가는 반드시 포함시켜야 한다. <head> 섹션에 넣는 것이 바람직. 다음 코드를 입력하면 됨.
<script src="swfkrpano.js"></script>
단 하나의 모든 것을 포함한 .js 파일로 만들었을 경우에는 바로 그 파일을 삽입하면 된다.
<script src="tour.js"></script>
뷰어 삽입
먼저 <div> 요소를 아래와 같이 생성한다. 반드시 id를 지정해야 하고, css 스타일로 크기를 지정해야함.
<div id="pano" style="width=100%;height=100%;"></div>
그 다음 삽입코드가 들어 있는 <script> 요소를 생성한다. swfkrpano에는 두가지 삽입코드가 있는데, 형식만 다를 뿐 기능은 동일
1. createPanoViewer()
<script>
var viewer = createPanoViewer({swf:"krpano.swf", target:"pano"});
viewer.addVariable("xml", "pano.xml");
viewer.embed();
</script>
createPanoViewer는 객체를 매개변수로 받아서 또다른 객체를 반환하는데, 이 객체는 매개변수를 추가/변경할 수 있다. 최종적으로 반환된 객체의 embed() 함수를 호출하면 삽입된다.
2. embedpano()
<script>
embedpano({swf:"krpano.swf", xml:"pano.xml", target:"pano"});
</script>
기본적으로 동일함. embedpano는 아무것도 반환하지 않고 직접 삽입. 짧은 버전이라고 할 수 있음.
삽입 매개변수
이 두가지 함수의 매개변수는 단하나의 JavaScript Object. 이 객체를 통해 parametername:value 형태로 매개변수를 전달함. target을 제외한 모든 변수는 옵션. 생략되면 default 값이 사용됨
- swf:"krpano.swf" viewer swf 파일의 경로. html의 위치를 기준으로 한 상대경로
- xml:"krpano.xml" pano xml 파일의 경로. 상대경로. default 는 swf 파일명.
- target:"---pano div id---" viewer가 삽입될 <div> 요소의 id. 없으면 에러 발생
- id:"krpanoSWFObject" viewer 객체의 id. Javascript:Interface 를 통해 viewer와 interface하는 객체임.
- width="100%";height="100%" viewer 객체의 크기. 부모 html 요소를 100% 사용한다는 뜻
- bgcolor:"#000000" 뷰어의 배경색
- wmode:"window" Flashplayer wmode 설정. window:시스템지원/성능이 적당. opaque:html 객체가 Flashplayer를 overlap 할 수 있음. (속도느림) transparent:Flashplayer뒷쪽에 있는 html 요소가 보일 수 있고, overlap 도 될 수 있음 (더 느림) direct:최고성능. 하드웨어가속 사용. 호환성떨어짐. 오래된시스템/브라우저에서는 아주 느려짐. HTML5에서 wmode=transparent는 동일한 효과. overlap은 항상가능함.
- html5:"auto" auto/prefer(whenpossible)/always/never
- vars:{} krpano에 variable:value 매개변수 전달함. krpano 초기변수(startup variable) 설정. 여기에서 설정하면 xml에 지정된 변수를 덮어쓰는 효과
- passQueryParameters:"false" html url의 모든 query parameter를 뷰어로 전달함. 아울러 html url에서 html5 설정을 뷰어로 전달. 즉, 링크만 바꿔도 html5 버전과 Flash 버전을 바꿔가며 실행시킬 수 있다는 뜻.
- html5licenseload:"true" 라이선스파일이 내장되어 있지 않으면 자동적으로 불러옴. page-reload 발생하지 않음
createPanoViewer 의 함수
embedpano()와 매개변수가 동일함. 단, Java 객체를 반환하는데, 이를 통해서 또다른 변수를 설정/추가할 수 있음. H/W 체크를 하는 데 유용함. 맨 마지막으로 embed()함수을 호출해야 최종 삽입됨
- viewer.addVariable(variable, value) krpano 초기변수 설정. 여기에서 설정하면 xml에 지정된 변수를 덮어쓰는 효과
- viewer.addParam(parameter, value) Flash parameter(wmode 등) 설정
- viewer.paaQueryParameter(); html의 모든 query parameter를 뷰어로 전달함.
- viewer.useHTML5
- var ret=viewer.isHTML5possible();
- var ret=viewer.isFLASHpossible();
- var ret=viewer.isDevice(devices); devices=iPhone,iPod,iPad,Android. |을 사용하면 여러기기를 한꺼번에 체크가능 if(viewer.isDevice(iPhone|iPad)) ....;
- viewer.embed(target);
초기/삽입 변수(Startup/embed variable)
뷰어를 삽입할 때 사용하는 특별한 변수. 이 변수들은 뷰어에게 직접 전달되는 변수가 아님. 삽입 그 자체때 특별한 의미가 있는 것임.
- xml : 시작 xml 파일의 이름과 경로. xml 변수가 없으면 기본값이 사용됨. 기본값이란, swf와 동일한 이름의 xml 파일을 말함.
- license : 라이선스 파일이 포함되지 않았을 때, 기본적으로 swf 파일과 동일한 이름의 라이선스파일을 로드하려고 시도함. 라이선스 파일이 있다면 그 파일에 대한 경로를 지정
- simulatedevice : 데스크탑에서 아이폰/안드로이드 테스트가능
모바일 기기 사용시 주의사항
아이폰, 아이패드, 안드로이드에서 최적의 결과를 얻으려면 다음사항을 준수할 것
- 항상 HTML5 도큐먼트로 선언할 것 : <!DOCTYPE htmlL>
- 1:1 픽셀 매칭이 되도록 자동 페이지/뷰포트 스케일링을 꺼야 함. <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>은 절대 사용금지. 비율이 어긋나게 됨.
예제
- 가장 간단하게 : <script>embed({target:"pano"});</embed>, krpano.swf, krpano.xml 을 사용함.
- 약간 더 : <script>embed({swf:"pano.swf", xml:"pano.xml", target:"pano"});</embed>
- html5을 우선하여 : <script>embed({swf:"pano.swf", xml:"pano.xml", target:"pano", html5:"prefer"});</embed>