개발의 기초

이 문서에서는 가젯 개발 프로세스의 기초가 되는 개념과 작업에 대해 설명합니다. 가젯 API 사용에 대한 소개를 보려면 시작하기를 참조하시기 바랍니다.

목차

  1. 콘텐츠 유형 선택
    1. HTML
    2. URL
  2. 기존 웹페이지 또는 응용프로그램을 가젯으로 변환
  3. 사용자 환경설정 데이터 유형 작업
    1. list 데이터 유형 사용
    2. 위치 데이터 유형 사용
  4. 상태 저장
  5. 특수 문자 이스케이프 처리
  6. 로그인 또는 쿠키가 필요한 가젯 작성

콘텐츠 유형 선택

가젯을 개발할 때 가장 먼저 하는 결정 중 하나는 사용할 콘텐츠 유형입니다. 예:

<Content type="html">

콘텐츠 유형으로 다음 사항이 결정됩니다.

  • 가젯 작성자가 사용할 수 있는 API 기능.
  • 가젯 렌더링 방식.
  • 가젯을 배포할 수 있는 위치.

다음 표는 사용 가능한 콘텐츠 유형과 언제 어떤 유형을 사용해야 하는가에 대해 설명합니다.

콘텐츠 유형 설명 사용 시점
html html 콘텐츠 유형을 사용하면 일반적으로 콘텐츠가 모두 가젯 명세에 존재합니다. type="html" 가젯에는 HTML이 포함되며 내장 자바스크립트, 플래시, ActiveX 또는 기타 브라우저 개체도 함께 포함될 수 있습니다. 기본으로 사용되는 유형입니다. 가장 유연하고 기능이 많은 콘텐츠 유형은 html입니다. 확신이 없을 때에는 html 콘텐츠 유형을 선택하시기 바랍니다.
url url 콘텐츠 유형을 사용하면 가젯 콘텐츠가 가젯 명세에 있는 URL이 참조하는 원격 웹페이지에 존재합니다. 원격 웹페이지는 모든 HTML 마크업과 자바스크립트가 존재하는 곳입니다. HTML 마크업 또는 자바스크립트 코드를 가젯 명세에 직접 넣을 수는 없습니다. type="url" 콘텐츠 유형은 현재 gadgets.* 또는 오픈소셜 API에서 완벽하게 지원하지는 않습니다. type="url" 콘텐츠 유형을 가젯 자바스크립트 라이브러리와 함께 사용하려면 레거시 가젯 API를 사용하시기 바랍니다.

HTML

html 콘텐츠 유형을 사용하면 일반적으로 코드가 모두 가젯 명세에 존재합니다. 여기에는 가젯 XML, HTML 마크업, 자바스크립트가 포함됩니다. 이 개발자 가이드에 있는 거의 모든 예에서 html 콘텐츠 유형을 사용합니다. 가장 유연하고 기능이 많은 콘텐츠 유형이며 특정 요구사항이 있는 가젯을 작성하지 않는 한 보통 이 유형을 사용하게 됩니다.

다음 예는 ROT13의 가젯 구현입니다. ROT13은 각 문자를 알파벳의 오른쪽으로 13번 움직인 문자로 대체하여 암호화합니다. 그런 다음 ROT13을 다시 적용하면 각 문자를 다시 회전시켜 원본 텍스트를 복원합니다.

가젯 명세는 다음과 같습니다.

<?xml version="1.0" encoding="UTF-8" ?> 

<Module>
  <ModulePrefs title="Magic Decoder"/> 
  <Content type="html">
  <![CDATA[
     <script type="text/javascript">

       // The gadget version of ROT13.
       // Encodes/decodes text strings by replacing each letter with the letter
       // 13 positions to the right in the alphabet. 
       function decodeMessage (form) {
          var alpha = "abcdefghijklmnopqrstuvwxyz";
          var input = form.inputbox.value; 
          var aChar;
          var message = "";
          for (var i = 0; i <input.length; i++)
          { 
             aChar = input.charAt(i);
             var index = alpha.indexOf(aChar.toLowerCase());

             // if a non-alphabetic character, just append to string
             if (index==-1)
             {
                message += aChar;
             }

             // if you have to wrap around the end of the alphabet
             else if(index > 12) { // compensate for 0-based index
                index = 25 - index; // last item in array is at [25]
                index = 12 - index; // because array starts with 0
                aChar = alpha.charAt(index);
                message += aChar;
             }

             // if you don't have to wrap
             else {
                aChar = alpha.charAt(index+13);
                message += aChar;
             }
          }
          document.getElementById('content_div').innerHTML = "<b>Your message: </b>" + message; 
     }
     </script>

     <FORM NAME="myform" ACTION="" METHOD="GET">Message: <BR>
<INPUT TYPE="text" NAME="inputbox" VALUE=""><P>
<INPUT TYPE="button" NAME="button" Value="Transform" onClick="decodeMessage(this.form)"> </FORM> <div id="content_div"></div> ]]> </Content> </Module>

type="html" 가젯에 대한 규칙은 다음과 같습니다.

  • type="html" 가젯에는 CDATA 섹션이 포함되어 있어야 하며 HTML이 해당 섹션 내에 있어야 합니다.
<Content type="html"> 
    <![CDATA[ HTML here... ]]>

CDATA 섹션은 자칫 마크업으로 여겨질 문자가 포함된 텍스트 블록을 이스케이프 처리하는 데 사용됩니다. CDATA 섹션에서 인식되는 유일한 구분 기호는 CDATA 섹션을 종결하는 "]]>" 문자열입니다.

  • <html>, <head>, 또는 <body> 태그는 사용할 수 없습니다. 가젯은 자체 <html>, <head>,<body> 태그와 함께 생성됩니다. 따라서 보통 <body> 태그 내에 있을 콘텐츠를 포함하기만 하면 됩니다.

html 콘텐츠 유형의 가젯은 외부 자바스크립트 파일을 참조할 수도 있습니다.

<Module>
  <ModulePrefs ... /> 
  <Content type="html"><![CDATA[
    <script src="http://www.example.com/gadgets/clock/clock.js" type="text/javascript"></script>

  ]]></Content> 
</Module>

URL

가젯에 type="url" 콘텐츠 유형이 있으면 href= 속성에서 URL을 제공하고, 가젯 명세의 다른 콘텐츠는 무시됩니다. url 콘텐츠 유형을 사용하면 가젯의 사용자 인터페이스 및 프로그램 로직과 관련된 모든 정보는 URL이 참조하는 파일에 있다고 가정합니다. HTML 마크업 또는 자바스크립트는 가젯에 직접 넣을 수 없습니다. 예:

<Module>
  <ModulePrefs ... /> 
  <Content type="url" href="http://www/cgi-bin/example/gadgets/mystats.cgi" /> 
</Module>

기존 웹페이지 또는 응용프로그램을 가젯으로 변환

다음 가이드라인에 따라 기존 웹페이지 또는 응용프로그램을 가젯으로 변환할 수 있습니다.

  • <html>, <head>, <body> 태그를 제거합니다(즉, HTML 콘텐츠 자체를 제공). 이 가이드라인은 type="html" 가젯에만 적용되며 type="url" 가젯에는 적용되지 않습니다.
  • onload 이벤트의 경우 gadgets.util.registerOnLoadHandler()를 사용합니다.
  • 가젯에 로그인이 필요하면 URL 콘텐츠 유형을 사용합니다. 가능한 문제에 대해서는 로그인 또는 쿠키가 필요한 가젯 작성을 참조하시기 바랍니다. HTTPS 가젯은 Internet Explorer에서 "혼합 콘텐츠" 경고를 표시하여 사용자를 번거롭게 할 수 있습니다.
  • 페이지나 응용프로그램을 작은 가젯 공간에 맞추는 데 필요한 사용자 인터페이스 변경을 수행합니다. 프로토타입을 취미로 만드는 분이나 전문가가 만드는 경우 프록시를 사용하여 콘텐츠를 가져오는 데 makeRequest()를 사용할 수 있습니다. 상업적으로 개발된 가젯의 경우 새로운 작은 페이지를 만들고 type="url"을 사용하여 이것을 가리키도록 하는 것이 좋습니다.

사용자 환경설정 데이터 유형 작업

가젯 명세에서 모든 사용자 환경설정에는 데이터 유형이 있습니다. datatype은 속성의 데이터 유형을 지정하는 선택적 문자열입니다. datatype의 가능한 값은 string, bool, enum, hidden(사용자가 편집할 수 없는 표시되지 않는 문자열), list, location(Google 지도를 기반으로 한 가젯의 경우)입니다. 기본 데이터 유형은 string입니다.

사용자 환경설정 데이터 유형에 대한 자세한 내용은 참조를 참조하시기 바랍니다.

이 섹션에서는 좀 더 전문화된 데이터 유형인 listlocation에 대해 설명합니다. 문서에서 나머지 데이터 유형을 사용하는 방법에 대한 예를 찾을 수 있습니다(예: enum, hidden, bool).

list 데이터 유형 사용

list 데이터 유형이 있는 사용자 환경설정은 런타임 시 사용자가 동적으로 제공하는 일련의 값입니다. 사용자가 사용자 환경설정 수정 창에 값을 입력함에 따라 값이 목록에 추가됩니다. 목록은 다른 사용자 환경설정과 마찬가지로 런타임 시 가젯이 프로그램에서 액세스할 수 있습니다. 원하는 때에 list 데이터 유형을 사용하여 사용자가 임의의 값 목록을 동적으로 제공하도록 허용할 수 있습니다. 예를 들어 날씨 가젯은 사용자가 우편번호 목록을 입력하는 것을 허용할 수도 있습니다.

datatype="list"을 사용하여 사용자 환경설정에 list 데이터 유형이 있음을 선언합니다. 예:

<UserPref name="mylist" display_name="Add Search Terms" datatype="list" required="true"/> 

가젯은 다음 예와 같이 Prefs 함수인 getArray(),를 사용하여 목록에 있는 값에 액세스합니다.

var search_terms = prefs.getArray("mylist");

배열에서 항목은 세로선으로 구분된(pipe-delimited) 목록으로 저장됩니다. 다음 예와 같이 Prefs 함수 getString()을 사용하여 이 목록을 세로선(|) 문자로 값이 구분된 단일 문자열로 반환할 수 있습니다.

prefs.getString("mylist");

세로선(|) 문자로 값이 구분된 문자열을 사용하여 목록 유형의 기본값을 설정할 수도 있습니다.

<UserPref name="mylist" display_name="Add Search Terms" datatype="list" default_value="zdnet|pc|Apple Insider"/>

Prefs 함수 setArray(name, val)를 사용하여 값을 프로그램에서 목록에 추가할 수 있습니다. 이 함수를 사용하려면 가젯의 <ModulePrefs><Require feature="setprefs"/>를 포함해야 합니다. 예를 들어 다음 예제는 "Nokia" 및 "CNET" 값을 목록에 추가합니다.

...

<ModulePrefs title="Feed Searcher" scrolling="true">
   <Require feature="setprefs" />
</ModulePrefs> ... prefs.setArray("mylist", ["Nokia","CNET"]);

다음은 사용자가 수정 창에 입력한 목록 항목을 출력하는 간단한 예입니다.

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs 
    title="List Data Type Example" 
    scrolling="true"/> 
  <UserPref name="mylist" 
    display_name="Add Terms" 
    datatype="list" />
  <Content type="html">
  <![CDATA[ 
  <div id=content_div></div>

  <script type="text/javascript"> 
    // Get userprefs
    var prefs = new gadgets.Prefs();

    // Get the array of search terms entered by the user
    var terms = prefs.getArray("mylist");  
    var html = "";

    // If the user has not added any terms yet, display message.
    if (terms.length == 0)
    {
      html += "Edit the userprefs to add terms.";
    }
    else {
      html += "Your terms are:<br /><br />";
      for (var i = 0; i < terms.length ; i++) {
        var term = (terms[i]);
        html += term + "<br />";
      }
    }
    document.getElementById("content_div").innerHTML = html; 
  </script>

  ]]> 
  </Content>
</Module>

위치 데이터 유형 사용

Google 지도를 기반으로 하는 가젯은 location 데이터 유형을 사용할 수 있습니다. 다음 예의 가젯은 location 데이터 유형을 사용하는 방법을 보여줍니다. 가젯의 location 데이터 유형에 제공되는 값은 미국, 캐나다 또는 영국에서는 주요 도시 또는 우편 번호여야 합니다. 우편 번호를 사용하면 더 적절한 결과가 나옵니다.

location 데이터 유형을 사용할 때 getString()을 사용하여 사용자가 지정한 위치의 위도와 경도를 찾을 수 있습니다.

<Module>
<ModulePrefs title="Map of __UP_loc__" height="300" author="Jane Smith" author_email="xxx@google.com" />
<UserPref name="loc" display_name="Location" datatype="location" required="true" />
<Content type="html">
<![CDATA[
<script src="http://maps.google.com/maps?file=js" type="text/javascript"></script>
<div id="map" style="width: 100%; height: 100%;"></div>
<script type="text/javascript">
var prefs = new gadgets.Prefs();
var map = new GMap(document.getElementById("map"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.centerAndZoom(new GPoint(prefs.getString("loc.long"), prefs.getString("loc.lat")), 6);
</script> ]]>
</Content> </Module>

location 환경설정 x를 읽을 때:

  • x가 빈 문자열인 경우(빈 위치임을 나타냄), x.latx.long은 빈 문자열입니다.
  • x의 지리정보를 코딩할 수 없으면(잘못된 위치임을 나타냄), x.latx.long이 0.0입니다.

이전 가젯 API 버전에서는 위치 유형에 대해 default_value를 지정하는 것이 허용되지 않았습니다. 이제는 달라졌습니다.

상태 저장

사용자가 수정 창을 사용하여 자신의 사용자 환경설정을 명시적으로 설정할 수 있도록 하는 것이 일반적입니다. 하지만 때로 사용자의 직접적인 관여 없이 프로그램을 사용하여 사용자 환경설정 값을 설정하는 것도 유용합니다. 예를 들어 게임 가젯의 경우 사용자의 최고 점수를 항상 저장하고 싶을 수 있습니다. 이 때 "high_score" 사용자 환경설정 값을 프로그램으로 설정하면 됩니다.

setprefs 기능을 사용하려면 가젯에 다음 항목이 포함되어야 합니다.

  • 가젯에 setprefs 라이브러리를 로드하도록 지시하는 <Require feature="setprefs"/> 태그(<ModulePrefs> 아래).
  • 프로그램으로 값을 설정하여 계속 저장할 사용자 환경설정. 보통 이 사용자 환경설정에 hidden 데이터 유형을 지정합니다.
  • 저장하려는 값이 있는 사용자 환경설정을 위한 자바스크립트 함수 set() 호출.

환경설정 크기는 현재 2K URL 제한사항의 적용을 받습니다.

다음 예제 가젯은 카운터 값을 증가시키는 버튼과 카운터 값을 0으로 재설정하는 버튼으로 구성됩니다. 이 예에서 "카운터"는 사용자 환경설정입니다. 여기에는 hidden 데이터 유형이 있으며 이는 사용자에게 값을 직접 수정할 권한이 없음을 의미합니다.

가젯 명세는 다음과 같습니다.

<?xml version="1.0" encoding="UTF-8" ?> 
<Module>
  <ModulePrefs 
    title="Setprefs New">
    <Require feature="opensocial-0.8"/>
    <Require feature="setprefs" /> 
    </ModulePrefs>
  <UserPref 
    name="counter" 
    default_value="0" 
    datatype="hidden"/>
  <Content type="html">
  <![CDATA[ 
    <div id="content_div" style="height: 100px;"></div>
    <script type="text/javascript">

    // Get user preferences
    var prefs = new gadgets.Prefs();
    var html = "";
    var div = document.getElementById('content_div');
    // Increment value of "counter" user preference
    function incrementCounter() {  
      var count = prefs.getInt("counter");
      div.innerHTML = "The count is " + count + ".";
      // Increment "counter" userpref          
      prefs.set("counter", count + 1);
    }

    // Reset value of "counter" userpref to 0
    function resetCounter(){
      prefs.set("counter", 0);
      div.innerHTML = "Count reset to " + prefs.getInt("counter") + ".";
    }

    </script>
    <input type=button value="Count" name="count" onClick="incrementCounter()">
    <input type=button value="Reset" name="reset" onClick="resetCounter()">
  ]]> 
  </Content>
</Module>

참고: 여러 값을 저장해야 하는 경우에는 값을 JSON 문자열로 저장하는 것이 좋습니다.

특수 문자 이스케이프 처리

가젯 명세의 XML 속성에서 특정 특수 문자를 이스케이프 처리해야 합니다. ASCII 엔티티만 가젯 명세에 사용할 수 있습니다. 예를 들어 ISO 8859-1 기호 엔티티는 사용할 수 없습니다. 다음은 지원되는 특수 문자 목록입니다.

문자 이스케이프 코드
& &amp;
< &lt;
> &gt;
" &quot;
' &apos;

예:

  • BAD: href="http://www.foo.com/bar?x=a&y=b"
  • GOOD: href="http://www.foo.com/bar?x=a&amp;y=b"
  • BAD: description="this is a "sexy" gadget"
  • GOOD: description="this is a &quot;sexy&quot; gadget"

이러한 유형의 이스케이프 처리는 CDATA 블록에서 필수 요건은 아니지만 이러한 처리가 권장됩니다.

자바스크립트 코드에서 _hesc(str) 함수를 사용하여 <>'".가 이스케이프 처리된 HTML 문자열 str을 반환할 수 있습니다.

로그인 또는 쿠키가 필요한 가젯 작성

Microsoft Internet Explorer 및 Apple Safari의 기본 개인정보 보호정책은 제3자 사이트가 쿠키를 설정하는 것을 허용하지 않습니다. 따라서 일부 가젯이 제대로 작동하지 않을 수 있습니다. 특히 로그인에 쿠키를 사용하는 사이트의 경우 iGoogle 페이지의 iframe에서 제대로 작동하지 않을 수 있습니다. 가능한 해결 방법은 다음과 같습니다.

  • 쿠키 대신 URL 매개변수를 사용합니다. 예를 들어 orkut 생일 가젯은 URL을 통해 인증 자격증명을 통과합니다. 단, 이 접근 방식을 선택할 경우 이러한 URL 매개변수를 HTTP 리퍼럴 필드에 있는 다른 웹사이트로 노출하지 않도록 주의하시기 바랍니다.
  • OAuth를 사용합니다. 가젯 API는 가젯이 사용자의 계정과 연결된 개인정보를 저장하는 다른 웹사이트에 다시 안전하게 연결되는 것을 허용하는 OAuth 프록시라는 기능을 지원합니다. OAuth는 개인정보의 계정 소유자가 다른 응용프로그램이 해당 개인정보를 액세스하는 것을 허용하도록 웹사이트에 지시하는 것을 허용하는 표준입니다. OAuth 프록시는 가젯의 OAuth 표준 사용을 쉽도록 하기 위해 설계되었습니다.
  • P3P 헤더를 작성합니다. 사이트의 개인정보 보호정책에 따라 Internet Explorer(Safari는 아님)가 해당 사이트에서 제3자의 쿠키를 읽는 것을 허용하는 P3P 헤더를 작성할 수도 있습니다. PHP를 사용 중이고 헤더를 설정하려는 경우 PHP 페이지의 상단에서 다음의 짧은 코드를 사용할 수 있습니다.
<?php
  header("P3P: CP=\"CAO PSA OUR\"");
?> 

이것은 결과가 페이지에 표시되기 전에 호출되어야 합니다.

사이트에 사용될 수 있는 헤더를 확인하려면 개인정보 보호정책을 주의 깊게 확인해야 합니다. 변호사와 상의해 보시기 바랍니다.

  • 사용자에게 지시합니다. 이것은 이 예제 가젯(사용해 보세요)에서처럼 자바스크립트로 가능합니다. 지시사항을 인증 로직과 통합할 수도 있습니다. 쿠키가 차단되어 있을 경우에는 사용자에게 개인정보 설정 수준을 낮추거나 다른 웹 브라우저를 사용해 보도록 지시합니다. 예를 들어 다음과 같은 메시지를 표시할 수 있습니다.

브라우저가 이 사이트와 호환되도록 구성되어 있지 않습니다. Microsoft Internet Explorer를 사용하는 경우 도구 > 인터넷 옵션을 선택하여 보안 설정을 변경할 수 있습니다. 개인 정보 탭을 열고 고급을 클릭한 다음 자동 쿠키 처리 덮어쓰기를 선택합니다. 제 3 사 쿠키에서 적용을 클릭합니다. 또는 Firefox와 같은 다른 웹 브라우저를 사용해 볼 수도 있습니다.

 

맨 위로 돌아가기