죄송합니다. 이 문서는 더 이상 최신 버전이 아닙니다. 가장 최근 업데이트된 문서를 보시려면 영어 버전을 참고로 해주십시오. 불편을 끼쳐드려 죄송합니다.

Google 가젯 API 참조

본 문서는 Google 가젯 API 참조 자료로, 가젯 사양 XML과 JavaScript 코어 및 기능 라이브러리에 대한 참조 정보를 포함합니다.

XML 구조

다음 섹션은 가젯을 지정하는 데 사용되는 XML 파일의 구조 및 콘텐츠에 대해 설명입니다.

가젯 환경설정

XML 파일의 <ModulePrefs> 섹션에서는 제목, 작성자, 기본 크기 등의 가젯 특성을 지정합니다. 다음은 해당 예입니다.

<Module>
  <ModulePrefs title="Developer Forum" 
    title_url="http://groups.google.com/group/Google-Homepage-API" 
    height="200" 
    author="Jane Smith" 
    author_email="xxx@google.com"/> 
  <Content ...>
   ... content ...
  </Content> 
</Module>

가젯 사용자는 해당 속성을 변경할 수 없습니다.

다음 표에는 <ModulePrefs> 속성이 나와 있습니다.

속성	설명
title	가젯 제목을 제공하는 옵션 문자열입니다. 제목은 사용자의 iGoogle 페이지에 있는 가젯 제목 표시줄에 표시됩니다. 해당 문자열에 사용자 환경설정 대체 변수가 있는 경우 Google 홈페이지 콘텐츠 디렉토리에 가젯을 제출하려면 디렉토리 표시에 필요한 `directory_title`도 제공해야 합니다.
directory_title	Google 콘텐츠 디렉토리에서 가젯에 대해 표시되어야 하는 제목을 제공하는 옵션 문자열입니다. 사용자 환경설정 대체 변수를 제외한 텍스트만 포함되어야 합니다. 그 이유는 콘텐츠 디렉토리에는 가젯의 정적 보기가 표시되므로 적절한 제목을 생성하는 데 필요한 대체 작업이 수행되지 않기 때문입니다. 예를 들어, 가젯 제목이 '__UP_name__ 친구'인 경우 디렉토리에서 ' __UP_name__'에 적절한 값을 제공하기 위한 대체 작업을 수행할 수 없습니다. 따라서 `directory_title`을 '친구'로 설정해야 합니다.
title_url	가젯 제목과 연결되는 URL을 제공하는 옵션 문자열입니다. 예를 들어, 제목을 iGoogle로 연결할 수 있습니다.
description	가젯을 설명하는 옵션 문자열입니다.
author	가젯 작성자를 표시하는 옵션 문자열입니다.
author_email	가젯 작성자의 이메일 주소를 제공하는 옵션 문자열입니다. 모든 이메일 시스템을 사용할 수 있지만 스팸 문제가 있으므로 개인 이메일을 사용하지 않는 것이 좋습니다. 문제를 해결할 수 있는 한 가지 방법은 가젯 사양에 helensmith.feedback+coolgadget@gmail.com 형식의 이메일 주소를 사용하는 것입니다. Gmail에서는 더하기 기호(+) 뒤의 모든 내용이 삭제되므로 해당 이메일 주소는 helensmith.feedback@gmail.com으로 해석됩니다. 가젯의 Gmail 주소를 생성하기 위해 Gmail 초대장이 필요한 경우 Google 기술 지원팀에 문의하세요.
author_affiliation	작성자의 소속을 나타내는 'Google' 등의 옵션 문자열입니다. 본 속성은 Google 홈페이지 콘텐츠 디렉토리에 포함된 가젯에 필요합니다.
author_location	'미국 캘리포니아 마운틴뷰'와 같은 작성자의 지리적 위치입니다.
screenshot	가젯 화면캡처의 URL을 제공하는 옵션 문자열입니다. robots.txt에서 차단하지 않은 공용 웹사이트의 이미지여야 합니다. 선호하는 형식은 PNG이지만 GIF 및 JPG도 사용할 수 있습니다. 가젯 화면캡처 너비는 280픽셀이어야 합니다. 화면캡처의 높이는 사용 중인 가젯이 '자연스러워 보이는' 높이여야 합니다. 화면캡처에 대한 자세한 내용은 콘텐츠 디렉토리에 게시를 참조하시기 바랍니다.
thumbnail	가젯 작은 이미지의 URL을 제공하는 옵션 문자열입니다. robots.txt가 차단하지 않는 공용 웹사이트 이미지여야 합니다. 선호하는 형식은 PNG이지만 GIF 및 JPG도 사용할 수 있습니다. 가젯 작은 이미지는 120x60픽셀이어야 합니다. 작은 이미지에 대한 자세한 내용은 콘텐츠 디렉토리에 게시하기를 참조하시기 바랍니다.
height	가젯이 실행되는 영역의 높이를 지정하는 양의 정수 옵션입니다. 기본 높이는 200입니다.
width	가젯이 실행되는 영역의 너비를 지정하는 양의 정수 옵션입니다. 해당 설정은 신디케이션 가젯에만 적용됩니다. 기본 너비는 320입니다.
scaling	브라우저 크기를 조정할 때 가젯의 가로 세로 비율(높이와 너비 비율)이 유지되는지 여부를 지정하는 옵션 부울입니다. 크기가 세로로 자동 조정되는 가젯은 해당 값을 참으로 설정해야 하지만 고정 높이를 사용하는 가젯의 경우에는 해당 값을 거짓으로 설정해야 합니다. 기본값은 참입니다.
scrolling	콘텐츠가 제공된 공간을 초과하는 경우 가로 및/또는 세로 스크롤 막대를 제공하는 옵션 부울입니다. 거짓인 경우 너비 구성이 불가능한 것은 아니지만 콘텐츠는 제공된 높이와 너비에 맞게 잘립니다. 기본값은 거짓입니다.
singleton	사용자가 디렉토리의 가젯을 여러 번 추가할 수 있는지 여부를 지정하는 옵션 부울입니다. 기본값은 참으로, 이 경우 기본적으로 가젯을 한 번만 추가할 수 있습니다. 디렉토리에서는 선택하는 속성 값에 관계없이 해당 속성을 처리할 수 있습니다. 예를 들어, Google 홈페이지 콘텐츠 디렉토리에서는 이미 추가된 가젯에 대해 '추가됨'이라는 텍스트를 회색 처리하여 표시하는 방법으로 `singleton="true"`를 처리합니다. 속성을 변경해도 디렉토리에 즉시 적용되지 않을 수 있습니다. 해당 속성으로 인해 사용자가 개발자 가젯 또는 URL로 추가를 통해 가젯을 여러 번 추가하지 못하는 것은 아닙니다. 따라서 여러 인스턴스를 지원하도록 가젯을 만들어야 합니다.
author_photo	작성자 페이지에서 사진으로 연결되는 URL입니다. 70x100 크기의 PNG 형식을 선호하지만 JPG/GIF도 지원됩니다.
author_aboutme	작성자 페이지에서 작성자에 대한 정보로 최대 500자입니다.
author_link	작성자 페이지에서 작성자 웹페이지, 블로그 등으로 연결되는 링크입니다.
author_quote	작성자 페이지에서 포함하려는 인용구로 최대 300자입니다.

라이브러리 사용

동적 높이 또는 상태 저장과 같은 특정 가젯 API 기능을 사용하려면 태그( 내부)를 사용하여 적절한 JavaScript 라이브러리를 로드해야 합니다. 태그에는 feature라는 필수 속성이 하나 있는데 해당 값은 기능 라이브러리를 지정합니다. 다음은 해당 예입니다.

<ModulePrefs 
  title="Set Userprefs Demo">
  <Require feature="dynamic-height"/>
  <Require feature="setprefs" /> 
</ModulePrefs>

기능 라이브러리에 대한 자세한 내용을 보려면 JavaScript 기능 라이브러리를 참조하시기 바랍니다.

로케일 지정

<ModulePrefs> 아래의 <Locale> 태그를 사용하여 가젯에서 지원하는 로케일을 지정하세요. 또한 Google 가젯 및 i18n에 설명된 대로 메시지 묶음을 지정하는 데에도 사용할 수 있습니다.

한 예로, 다음 스니펫에서는 2개의 로케일을 지정합니다.

<ModulePrefs ...>
  <Locale lang="en" country="us" />
  <Locale lang="ja" country="jp" />
</ModulePrefs>

'lang'(언어) 및 'country' 속성은 모두 옵션이지만 <Locale>마다 최소 하나의 속성을 지정해야 합니다. 두 속성 중 하나라도 지정하지 않으면 값은 '*' 및 'ALL'과 동일합니다. 국가를 지정하고 언어는 지정하지 않으면 가젯에서 해당 국가와 연관된 모든 언어를 지원하는 것으로 간주됩니다. 마찬가지로 언어를 지정하고 국가는 지정하지 않으면 가젯에서 해당 언어와 연관된 모든 국가를 지원하는 것으로 간주됩니다.

여기를 클릭하여 "lang" 및 "country"에 사용할 수 있는 값을 확인하세요.

일반적인 언어 규칙에 대한 몇 가지 예외가 있습니다.

중국어 간체: lang="zh-cn" (일반적으로 국가="cn")
중국어 번체: lang="zh-tw"(일반적으로 국가="tw" 또는 "hk", 각각 대만 또는 홍콩)

다음 표에는 <Locale> 속성이 정리되어 있습니다.

속성	설명
lang	로케일과 연관된 언어를 나타내는 옵션 문자열입니다.
country	로케일과 연관된 국가를 나타내는 옵션 문자열입니다.
messages	메시지 묶음을 가리키는 URL인 옵션 문자열입니다. 메시지 묶음은 지정된 로케일에 맞게 번역된 문자열이 있는 XML 파일입니다. 자세한 내용을 보려면 Google 가젯 및 현지화를 참조하시기 바랍니다.

<Locale>을 지정하지 않으면 기본값은 미국 영어입니다.

호환성 요구사항 지정하기

일부 환경에서는 가젯이 실행되지 않을 수도 있습니다. 가젯을 실행하려면 특정 브라우저 또는 소프트웨어가 필요할 수 있습니다. <MayRequire> 태그를 사용하여 가젯의 특수 요구사항에 대한 정보를 제공하세요. 다음은 해당 예입니다.

<ModulePrefs ...>
  <MayRequire type="plugin" value="quicktime"/>
  <MayRequire type="browser" value="firefox" min_version="1.06"/>
  <MayRequire type="platform" 
    value="windows"> This gadget uses a Windows API.
  </MayRequire>
</ModulePrefs>

다음 표에는 <MayRequire> 속성이 나와 있습니다.

속성	설명
type	요구사항 유형을 나타내는 필수 문자열입니다. 지원되는 유형은 "platform", "browser" 및 "plugin"입니다.
value	유형 값을 제공하는 필수 문자열입니다(예: type="plugin" value="flash").
min_version	필수 항목의 최소 버전 번호를 나타내는 옵션 문자열입니다.
cdata	요구사항에 대한 추가 정보를 제공하는 옵션 문자열입니다.

사용자 환경설정

일부 가젯은 사용자에게 사용자 고유 정보를 제공할 방법을 제시해야 합니다. 예를 들어, 날씨 가젯을 실행하려면 사용자가 우편번호를 입력해야 합니다. XML 파일의 사용자 환경설정(<UserPref>) 섹션에서는 가젯을 실행할 때 사용자 인터페이스 컨트롤로 바뀌는 사용자 입력란에 대한 설명을 볼 수 있습니다.

다음 표에는 <UserPref> 속성이 정리되어 있습니다.

속성	설명
name	사용자 환경설정의 필수 '기호'로, `display_name`이 정의되지 않은 경우 수정하는 동안 사용자에게 표시됩니다. 고유한 글자, 숫자 및 밑줄(즉, 정규식 ^[a-zA-Z0-9_]+$)만 사용할 수 있습니다.
display_name	수정 창에서 사용자 환경설정과 함께 표시할 고유 옵션 문자열입니다.
urlparam	`type="url"` 콘텐츠의 매개변수 이름으로 전달할 옵션 문자열입니다.
datatype	본 속성의 데이터 유형을 나타내는 옵션 문자열입니다. `string`, `bool`, `enum`, `hidden`(사용자가 수정할 수 없는 비공개 문자열), list(사용자 입력을 통해 생성되는 동적 배열) 또는 `location`(Google Maps 기반 가젯)입니다. 기본값은 string입니다.
required	사용자 환경설정이 필요한지 여부를 나타내는 옵션 부울 인수(`true` 또는 `false`)입니다. 기본값은 `false`입니다.
default_value	사용자 환경설정의 기본값을 나타내는 옵션 문자열입니다.

사용자 환경설정은 사용자 환경설정 JavaScript API를 사용하는 가젯에서 액세스할 수 있습니다. 예를 들면 다음과 같습니다.

<script type="text/javascript">
   // Must be constructed using the __MODULE_ID__ token. It gets replaced
   // at runtime with the actual ID of your gadget.
   var prefs = new _IG_Prefs(__MODULE_ID__);
   var someStringPref = prefs.getString("StringPrefName");
   var someIntPref = prefs.getInt("IntPrefName");
   var someBoolPref = prefs.getBool("BoolPrefName");
</script>

Enum 데이터 유형

<UserPref> datatype 속성에 대해 지정할 수 있는 값 중 하나는 enum입니다. enum 데이터 유형은 사용자 인터페이스에서 선택 메뉴로 제공됩니다. <EnumValue>를 사용하여 메뉴 내용을 지정합니다.

예를 들어, 다음 <UserPref>를 사용하면 게임 난이도를 설정할 수 있습니다. 메뉴에 나타나는 각 값(쉬움, 중간 및 어려움)은 <EnumValue> 태그를 사용하여 정의합니다.

<UserPref name="difficulty" 
     display_name="Difficulty"
     datatype="enum"
     default_value="4">
  <EnumValue value="3" display_value="Easy"/>
  <EnumValue value="4" display_value="Medium"/>
  <EnumValue value="5" display_value="Hard"/>
</UserPref>

다음 표에는 <EnumValue> 속성이 나와 있습니다.

속성	설명
value	고유한 값을 제공하는 필수 문자열입니다. display_value를 제공하지 않으면 해당 값이 사용자 환경설정 수정 상자의 메뉴에 표시됩니다.
display_value	사용자 환경설정 수정 상자의 메뉴에 표시되는 옵션 문자열입니다. display_value를 지정하지 않으면 사용자 인터페이스에 value가 표시됩니다.

콘텐츠 섹션

<Content> 섹션에서는 콘텐츠 유형을 정의하는데, 콘텐츠 자체가 포함되어 있거나 외부 콘텐츠에 대한 링크가 있습니다. <Content> 섹션에서 가젯 속성 및 사용자 환경설정은 프로그래밍 로직 및 형식 지정 정보와 통합되어 실행할 가젯이 됩니다. 콘텐츠 유형에 대한 자세한 내용을 보려면 콘텐츠 유형 선택을 참조하십시오.

다음 표에는 <Content> 속성이 나와 있습니다.

속성	설명
type	콘텐츠 유형을 제공하는 옵션 문자열입니다. 사용할 수 있는 값은 html, html-inline 및 url입니다. 기본값은 html입니다.
href	목적 URL을 제공하는 문자열입니다. type="url"에 필요하며 다른 콘텐츠에는 사용할 수 없습니다.
cdata	옵션 문자열입니다. HTML의 경우 iframe에 표시할 원시 HTML이 포함되어 있습니다.

JavaScript 라이브러리

본 섹션은 Google Gadgets API에서 지원하는 JavaScript 함수에 대한 설명입니다. JavaScript 라이브러리 사용을 위한 요구사항에 대한 설명을 보려면 여러 콘텐츠 유형에 JavaScript 라이브러리 사용을 참조하십시오.

Google Gadgets API에는 두 종류의 JavaScript 라이브러리가 있습니다.

JavaScript 코어 라이브러리
JavaScript 기능 라이브러리

JavaScript 코어 라이브러리

JavaScript 코어 라이브러리에는 특정 기능과 관련이 없는 일반 함수가 포함되어 있습니다.

아래 표에는 사용자 환경설정(userprefs) 생성자와, 사용자 환경설정(userprefs) 개체를 인스턴스화한 경우 해당 개체에 대해 호출할 수 있는 함수가 나와 있습니다.

이름	설명
_IG_Prefs()	사용자 환경설정 생성자입니다. 예: `var prefs = new _IG_Prefs();` 본 함수는 선택적으로 가젯 ID(`__MODULE_ID__`)를 매개변수로 사용합니다. 인라인 가젯에만 필요합니다.
getString(userpref)	지정된 userpref를 문자열 값으로 검색합니다. list 데이터 유형을 가진 사용자 환경설정(userpref)의 경우 파이프로 구분된 값으로 이루어진 단일 문자열로 배열 콘텐츠를 검색합니다.
getInt(userpref)	지정된 userpref를 정수 값으로 검색합니다.
getBool(userpref)	지정된 userpref를 부울 값으로 검색합니다.
getArray(userpref)	list 데이터 유형을 가진 userpref 의 경우 콘텐츠를 배열로 검색합니다.
set(userpref, value)	지정된 userpref의 value를 설정합니다. 본 함수를 사용하려면 Setprefs 라이브러리에서 설명한 대로 가젯에 setprefs 라이브러리를 포함시켜야 합니다. 해당 함수와 예에 대한 자세한 내용을 보려면 상태 저장을 참조하십시오.
setArray(userpref, [value...])	list 데이터 유형을 가진 userpref 의 경우 배열에 요소를 추가합니다. 해당 함수를 사용하려면 Setprefs 라이브러리에서 설명한 대로 가젯에 setprefs 라이브러리를 포함시켜야 합니다. 해당 함수에 대한 자세한 설명을 보려면 list 데이터 유형 사용을 참조하세요. 예: prefs.setArray("mylist", ["Apples","Oranges"]);
dump()	디버깅에 필요한 모든 환경설정을 표시하기 위해 document.writeln()을 사용합니다.

아래 표에는 사용자 환경설정(userpref)과 특별히 관련이 없는 일반적인 목적의 JavaScript 방식이 정리되어 있습니다.

이름	설명
_IG_FetchContent(url, func)	url의 콘텐츠를 가져옵니다. func를 호출합니다. _IG_FetchContent()는 비동기식입니다. 즉, 즉시 반환되고 가져오기가 완료되면 나중에 내부 함수를 호출합니다. 따라서 호출 함수 또는 호출 함수에 의해 호출되는 함수 내부에 종속 코드를 삽입해야 합니다. 해당 함수에 대한 자세한 내용을 보려면 텍스트 사용을 참조하십시오.
_IG_FetchXmlContent(url, func)	url의 XML 콘텐츠를 가져옵니다. func를 호출합니다. _IG_FetchContent()와 마찬가지로 비동기식입니다. 해당 함수에 대한 자세한 내용을 보려면 XML 사용을 참조하십시오.
_IG_FetchFeedAsJSON(url, func, num_entries, get_summaries)	url의 RSS/Atom 피드 콘텐츠를 가져와 JSON 개체로 반환합니다. func를 호출합니다. num_entries에 지정된 피드 항목 수(기본값 3, 사용 가능한 범위 1-100)를 가져오고 선택적으로 get_summaries의 값(기본값 거짓)에 따라 항목 요약을 가져옵니다. _IG_FetchContent()와 마찬가지로 비동기식입니다. 본 함수에 대한 자세한 내용을 보려면 피드 사용을 참조하십시오.
_IG_RegisterOnloadHandler(func)	로드 시 호출되는 이벤트 처리기입니다. 페이지가 로드된 후 호출되는 함수인 단일 인수를 사용합니다. 전달된 함수는 인수를 사용하지 않습니다. iframe 가젯에서는 document.body.onload = ... 함수를 사용하여 온로드(onload)를 간단히 등록할 수 있으므로 해당 메서드는 인라인 가젯에 대해서만 유용합니다. 다음은 몇 가지 예입니다. _IG_RegisterOnloadHandler(function() { alert("page loaded"); }); function onLoadFunc__MODULE_ID__() { alert("page loaded"); }); _IG_RegisterOnloadHandler(onLoadFunc__MODULE_ID__);
_gel(id)	JavaScript document.getElementById() 함수에 대한 래퍼입니다.
_esc(str)	JavaScript escape() 및 encodeURIComponent() 함수에 대한 래퍼입니다.
_unesc(str)	JavaScript unescape() 및 decodeURIComponent() 함수에 대한 래퍼입니다.
_trim(str)	str의 시작 및 끝 부분에서 공백을 제거합니다.
_gelstn(tagname)	JavaScript document.getElementsByTagName() 함수에 대한 래퍼입니다.
_uc(str)	대문자로 된 str을 반환합니다.
_min(val1, val2)	val1과 val2 중 값이 적은 쪽을 반환하거나 두 값이 동일한 경우에는 val2를 반환합니다.
_max(val1, val2)	val1과 val2 중 값이 큰 쪽을 반환하거나 두 값이 동일한 경우에는 val2를 반환합니다.
_hesc(str)	<>&'" 같은 문자를 이스케이프한 상태로 HTML 문자열 str을 반환합니다.
_args()	document.location에서 URL 매개변수 키-값 쌍을 조합 배열로 반환합니다. 예를 들어, "&foo=bar&up_cats=meow"는 {"foo":"bar", "up_cats":"meow"}로 반환됩니다. 다음은 언어 또는 국가를 가져올 때 해당 방식을 사용할 수 있는 방법에 대한 예입니다. var lang = _args()["lang"]; if (typeof lang == "undefined") { lang = "en"; }
_toggle()	HTML 요소의 표시/숨기기를 전환합니다.

JavaScript 기능 라이브러리

Google Gadgets API에는 다음과 같은 기능 라이브러리가 포함되어 있습니다.

setprefs
dynamic-height
tabs
drag
grid
minimessage
analytics

특정 기능 라이브러리를 사용하려면 태그( 내)를 사용하여 가젯 사양 안에 해당 라이브러리를 포함시켜야 합니다. 다음은 해당 예입니다.

<ModulePrefs 
  title="My Tabbed Gadget">
  <Require feature="tabs"/>
</ModulePrefs>

아래에 기능 라이브러리가 자세히 설명되어 있습니다.

setprefs 라이브러리

setprefs 라이브러리 및 예를 활용하는 방법에 대한 자세한 내용을 보려면 상태 저장을 참조하십시오.

setprefs 라이브러리를 사용하려면 가젯의 아래에 다음 줄이 포함되어야 합니다.

setprefs 라이브러리에는 다음 함수가 포함되어 있습니다.

set(userpref, value)

해당 함수는 일반적으로 숨겨진 사용자 환경설정(userprefs) 개체로 인해 호출됩니다. userpref 매개변수는 사용자 환경설정의 이름을 지정하고 value 매개변수는 사용자 환경설정에 할당되는 값을 지정합니다. 다음은 해당 예입니다.

var prefs = new _IG_Prefs(__MODULE_ID__);
prefs.set("score", 5000);

dynamic-height 라이브러리

dynamic-height 라이브러리 및 예를 활용하는 방법에 대한 자세한 내용을 보려면 가젯 높이 조정을 참조하십시오.

dynamic-height 라이브러리를 사용하려면 가젯의 <ModulePrefs> 아래에 다음 줄이 포함되어야 합니다.

<Require feature="dynamic-height" />

dynamic-height 라이브러리에는 가젯에 자체 크기를 조정하도록 지시하는 하나의 함수가 포함되어 있습니다.

_IG_AdjustIFrameHeight()

tabs 라이브러리

tabs 라이브러리 및 예를 활용하는 방법에 대한 자세한 내용을 보려면 탭을 참조하십시오.

tabs 라이브러리를 사용하려면 가젯의 <ModulePrefs> 아래에 다음 줄이 포함되어야 합니다.

<Require feature="tabs" />

아래 표에는 tabs 생성자와, tabs 개체를 인스턴스화한 경우 해당 개체에 대해 호출할 수 있는 함수가 나와 있습니다.

함수	설명
_IG_Tabs(module_id, opt_selected_tab)	`tabs` 개체의 새 인스턴스를 인스턴스화하는 생성자입니다. 첫 번째 매개변수는 가젯의 __MODULE_ID__입니다. 옵션 매개변수 opt_selected_tab은 가젯을 처음 로드할 때 기본적으로 선택되는 탭의 이름입니다. 해당 매개변수를 생략하면 기본적으로 첫 번째 탭이 선택됩니다.
addTab(tabName, opt_domId, opt_callback)	탭을 `tabs` 개체에 추가하고 탭의 DOM ID와 연관된 <div>를 반환합니다. <div>가 없으면 `tabs` 라이브러리에 의해 생성됩니다. tabName 매개변수는 탭의 표시 이름을 제공합니다. 옵션 매개변수 opt_domId는 해당 탭의 콘텐츠를 보관하는 <div>의 DOM ID를 제공합니다. 옵션 매개변수 opt_callback은 해당 탭을 선택할 때마다 실행되는 콜백 함수를 지정합니다.
addDynamicTab(tabName, callback)	callback 함수에서 동적 콘텐츠를 제공하는 `tabs` 개체에 탭을 추가합니다. 빈 <div>를 만들고 해당 DOM ID를 반환합니다. <div>의 콘텐츠는 callback 함수에서 동적으로 생성되어야 합니다. tabName 매개변수는 탭의 표시 이름을 지정합니다. callback 매개변수는 해당 탭을 선택할 때마다 호출되는 callback 함수를 지정합니다.
setSelectedTab(tabIndex)	tabIndex에 지정된 탭을 선택하고 탭의 콜백 함수가 있는 경우에는 해당 함수를 실행합니다. 탭이 선택되어 있는 경우에는 콜백이 무시됩니다. 탭은 0부터 인덱싱됩니다. 인덱스는 위치에 따라 바뀝니다. 다른 탭을 기준으로 탭의 위치를 변경하면 인덱스도 그에 따라 변경됩니다.
moveTab(tabIndex1, tabIndex2)	tabIndex1 및 tabIndex2의 탭 위치를 바꿉니다. 선택한 탭은 변경되지 않으며 콜백 함수는 호출되지 않습니다.

drag 라이브러리

drag 라이브러리 및 예를 활용하는 방법에 대한 자세한 내용을 보려면 끌기를 참조하십시오.

drag 라이브러리를 사용하려면 가젯의 <ModulePrefs> 아래에 다음 줄이 포함되어야 합니다.

<Require feature="drag" />

drag 라이브러리에는 다음 콜백 함수가 포함되어 있습니다.

콜백 함수	설명
onDragStart = function(newSource) {}	끌기를 시작할 때 호출됩니다.
onDragTargetHit = function(newTarget, lastTarget) {}	끌기를 진행 중이고 대상에 도달한 경우에 호출됩니다.
onDragTargetLost = function(lastTarget) {}	끌기를 진행 중이고 사용자가 대상을 벗어난 경우에 호출됩니다.
onDragEnd = function(source, target) {}	끌기를 종료하여 사용자가 마우스 버튼에서 손가락을 띤 경우에 호출됩니다.
onDragClick = function(source) {}	사용자가 마우스를 움직이지 않지만 마우스가 소스 위/아래로 이동하는 경우에 호출됩니다.

아래 표에는 drag 생성자와, drag 개체를 인스턴스화한 경우 해당 개체에 대해 호출할 수 있는 함수가 나와 있습니다. 소스 및 대상은 DOM ID와 연관된 HTML 요소입니다. 소스 및 대상도 끌기 ID를 갖습니다. 끌기 ID를 지정하지 않으면 끌기 라이브러리에서 끌기 ID로 DOM ID를 사용합니다.

함수	설명
_IG_Drag()	`drag` 생성자입니다. 소스 및 대상을 추가할 수 있는 `drag` 개체를 인스턴스화합니다.
addSource(DOM_id)	소스를 `drag` 개체에 추가합니다. 여기서 DOM_id는 소스로 추가되는 HTML element의 고유한 ID입니다. 끌기 ID를 지정하지 않으면 끌기 라이브러리에서 끌기 ID로 HTML 요소의 DOM ID를 사용합니다. 예: drag_obj.addSource("dom_id1");
addSource(drag_id, HTML_element)	HTML_element를 `drag` 개체에 소스로 추가합니다. 소스에 drag_id를 지정합니다. 예: drag_obj.addSource("first", _gel("dom_id1"));
addSource(drag_id, HTML_element, surrogate)	HTML_element를 `drag` 개체에 소스로 추가합니다. 소스에 drag_id를 지정합니다. 해당 함수에는 대리자에 사용할 HTML 마크업을 지정하는 `surrogate` 매개변수도 포함되어 있습니다. `surrogate`는 사용자가 끌기 작업을 하고 있는 경우 소스를 가장하는 빈 개체입니다. 기본적으로 `surrogate`는 소스의 복제본입니다. 예: drag_obj.addSource("first", _gel("dom_id1"), "This is my surrogate");
removeSource(drag_id)	drag_id에 지정된 소스를 제거합니다.
removeAllSources()	`drag` 개체에서 모든 소스를 제거합니다.
addTarget(DOM_id)	대상을 `drag` 개체에 추가합니다. 여기서 DOM_id는 대상으로 추가되는 HTML 요소의 고유한 ID입니다. 끌기 ID를 지정하지 않으면 끌기 라이브러리에서 끌기 ID로 HTML 요소의 DOM ID를 사용합니다.
addTarget(drag_id, HTML_element)	HTML_element를 `drag` 개체에 대상으로 추가합니다. 대상에 drag_id를 지정합니다.
addTarget(drag_id, HTML_element, priority)	HTML_element를 `drag` 개체에 대상으로 추가합니다. 대상에 drag_id를 지정합니다. priority 매개변수는 중복 대상이 있는 경우 우선순위를 지정하는 숫자 값입니다. 충돌할 경우 우선순위가 높은 대상이 선택됩니다. 기본적으로 대상의 우선순위 값은 0으로 지정됩니다. 2개의 대상이 '충돌할 수 있는 경우' 숫자상 우선순위가 높은 대상이 선택됩니다. 예를 들어, 우선순위가 4인 대상이 우선순위가 2인 대상보다 우선합니다.
removeTarget(drag_id)	drag_id에 지정된 대상을 제거합니다.
removeAllTargets()	`drag` 개체에서 모든 대상을 제거합니다.

끌기 특성

drag 라이브러리에는 아래에 나와 있는 특성이 포함되어 있습니다. 해당 특성은 drag 개체를 통해 액세스합니다. 다음은 해당 예입니다.

if (drag_obj.isDragging == true) {
     // do something
}

아래 표에는 읽기 전용 특성이 나와 있습니다.

읽기 전용 특성	설명
isDragging	사용자가 끌고 있을 경우 참입니다.
hasDragged	isDragging이 참이고 마지막 mouseDown 이후로 사용자가 마우스를 이동한 경우에 참입니다.
surrogate	현재 대리자를 가리킵니다.
surrogateInitialX, surrogateInitialY	끌기를 시작할 때 대리자가 시작되는 위치
curSource	현재 소스를 가리킵니다. 사용자가 끌기 작업을 하지 않을 때는 Null입니다.
curTargetId	현재 대상의 ID를 포함합니다. 사용자가 끌기 작업을 하지 않을 때는 Null입니다.

아래 표에는 읽기-쓰기 특성이 나와 있습니다. 해당 특성을 변경하면 끌기 작동 방식에 영향을 줍니다. 끄는 도중에는 특성을 변경하지 마십시오.

읽기-쓰기 특성	설명
leftMargin, rightMargin, topMargin, bottomMargin	각 대상의 주위에는 여백이 있습니다. 해당 값을 변경하면 대상의 민감도를 변경할 수 있습니다. 기본적으로 여백은 2픽셀입니다.
surrogateOffsetX, surrogateOffsetY	해당 값을 변경하여 끌기를 시작할 때 대리자가 몇 픽셀 오프셋되도록 할 수 있습니다. 기본값은 1픽셀입니다. 0이 아닌 이유는 값이 1이어야 끌기를 시작할 때 사용자에게 피드백이 제공되기 때문입니다.

grid 라이브러리

grid 라이브러리 및 예를 활용하는 방법에 대한 자세한 내용을 보려면 그리드를 참조하십시오.

grid 라이브러리를 사용하려면 가젯의 <ModulePrefs> 아래에 다음 줄이 포함되어야 합니다.

<Require feature="grid" />

다음은 grid 라이브러리의 함수에 관한 요약입니다.

그리드에 필요한 백엔드 함수

그리드 라이브러리를 사용하려면 다음 백엔드 함수를 구현해야 합니다.

함수	설명
`_IGG_getNormalView(index)`	사용자가 끌기 작업을 하지 않을 때 표시되도록 `index`의 셀에 있는 기본 HTML 콘텐츠를 반환합니다.
`_IGG_isDragSource(index)`	`index`의 요소가 끌기 소스인지 여부를 나타내기 위한 부울 값을 반환합니다.
`_IGG_isDragTarget(index, sourceIndex)`	`sourceIndex`가 끌기 소스인 경우 `index`의 요소가 끌기 대상인지 여부를 나타내기 위한 부울 값을 반환합니다.

그리드 백엔드 표시 함수

기본적으로 그리드 라이브러리는 셀 콘텐츠를 표시하려고 할 때마다 getNormalView()를 호출합니다. 하지만 사용자의 끌기 방식에 따라 셀 콘텐츠가 다르게 반응하여 표시되게 할 수 있습니다. 이런 경우 백엔드 개체에 대해 다음 옵션 함수를 구현할 수 있습니다.

함수	설명
`_IGG_getSurrogateView(index)`	`index`의 콘텐츠를 끌 때 대리자 보기(마우스 커서 아래에 표시)의 HTML 콘텐츠를 반환합니다.
`_IGG_getSourceView(source, target)`	사용자가 끌 때 `source`가 되는 셀의 HTML 콘텐츠를 반환합니다. 마우스 커서가 대상 위에 있는 경우 `target`은 대상의 인덱스를 포함합니다. 그렇지 않으면 -1을 포함합니다.
`_IGG_getTargetView(target, source)`	`target`인 경우 사용자가 끌 때 셀의 HTML 콘텐츠를 반환합니다. `source`는 소스의 인덱스입니다.
`_IGG_getPossibleTargetView(potential_target, source)`	`potential_target`인 경우(대상이 아님) 사용자가 끌 때 셀의 HTML 콘텐츠를 반환합니다. `source`는 소스의 인덱스입니다.
`_IGG_getDragView(index, source)`	잠재적인 대상 또는 소스가 아닌 경우 사용자가 끌 때 `index`의 셀 HTML 콘텐츠를 반환합니다. `source`는 소스의 인덱스입니다.

그리드 백엔드 반응 함수

그리드 라이브러리는 가젯이 마우스 클릭 및 끌기에 응답할 수 있도록 다음과 같은 함수를 제공합니다.

함수	설명
`_IGG_handleClick(source)`	사용자가 `source`를 클릭하면(즉, 마우스를 끌지 않고 mouseDown 및 mouseUp을 수행하는 경우) 호출됩니다.
`_IGG_handleDragStart(source)`	사용자가 `source`에 대해 mouseDown을 수행한 다음 끌기 과정을 시작한 경우에 호출됩니다.
`_IGG_handleDrag(source, target)`	끌기를 종료한 경우에 호출됩니다. 사용자가 유효한 대상에서 종료한 경우 `target`은 대상 인덱스를 포함합니다. 그렇지 않으면 -1 값을 갖습니다. `_IGG_handleClick()`을 호출하면 `_IGG_handleDrag()`도 호출됩니다. 그러므로 응용 프로그램에 따라 `_IGG_handleDrag()`만 사용하는 것이 좋습니다.

그리드 백엔드 콜백

백엔드 콜백 함수는 백엔드 개체에서 자동으로 생성됩니다. 그리드 라이브러리에서는 필요에 따라 콜백 함수를 호출하지만 사용자 끌기 이외의 프로세스를 통해 데이터를 변경하는 경우와 같이 사용자가 직접 해당 함수를 호출할 수도 있습니다. 그리드 라이브러리에는 다음과 같은 백엔드 콜백이 포함되어 있습니다.

함수	설명
`_IGG_refreshCell(index)`	`index`의 셀 표시를 새로 고칩니다.
`_IGG_refreshAll()`	모든 셀의 표시를 새로 고칩니다. 해당 작업은 특히 그리드가 복잡하고 크기가 큰 경우에 시간이 오래 걸릴 수 있습니다.

그리드 개체 특성

그리드 라이브러리에는 아래 나와 있는 그리드 개체 필드와 함수가 포함되어 있습니다. 해당 필드와 함수는 그리드 개체를 통해 액세스할 수 있습니다. 다음은 해당 예입니다.

document.getElementById("summary").innerHTML = "In the grid " + mygrid.name + 
   " the HTML content of the source is " + mygrid.getCellValue(mygrid.source);

그리드 개체를 통해 액세스할 수 있는 필드와 함수는 다음과 같습니다.

함수	설명
`initDragging()`	그리드에서 끌기를 감지할 수 있게 해줍니다.
`dataObject`	백엔드 개체입니다.
`name`	그리드에서 만든 모든 DOM ID에 추가된 접두사 문자열입니다.
`height, width`	그리드의 높이 및 너비 매개변수입니다.
`maxIndex`	셀의 최대 인덱스 값입니다. 해당 값은 일반적으로 높이*너비-1이지만 `getCell()`을 사용하여 추가 셀을 만드는 경우에는 더 큰 숫자가 될 수 있습니다.
`source`	현재 소스의 인덱스입니다. 사용자가 끌기 작업을 하지 않을 때는 값이 -1입니다.
`target`	현재 대상의 인덱스입니다. 사용자가 끌기 작업을 하지 않거나 대상을 벗어난 경우 값은 -1입니다.
`getCellName(index)`	`index`의 셀 콘텐츠를 포함하는 SPAN 요소의 DOM ID를 반환합니다.
`getCellTDID(index)`	`index`의 셀 콘텐츠를 포함된 SPAN 요소가 들어 있는 TD 요소의 DOM ID를 반환합니다.
`getCellValue(index)`	`index`의 HTML 콘텐츠를 반환합니다.
`getTable()`	셀이 들어 있는 DOM 테이블을 반환합니다.
`getCell(index)`	`index`의 셀을 반환합니다. 인덱스가 0보다 작은 경우에는 Null을 반환합니다. 인덱스가 maxIndex보다 큰 경우에는 해당 인덱스를 사용하는 새로운 셀이 만들어지고, 테이블에 없는 셀이 생성됩니다.
`makeNewTable()`	DOM HTML 테이블을 완전히 새로 생성합니다. DOM 트리에 새 테이블을 다시 연결해야 할 수 있습니다. 이 경우 이전 테이블을 제거해야 하므로 페이지 속도가 느려질 수 있습니다.
`table`	DOM HTML 테이블에 대한 직접 액세스입니다. 해당 함수를 변경하지 않고 getTable()을 사용하는 것이 좋습니다.
`cells`	DOM 셀이 포함된 배열에 대한 직접 액세스입니다. 해당 함수를 변경하지 않고 `getCell()`을 사용하는 것이 좋습니다.
`dragHandler`	그리드의 끌기를 관리하기 위한 `_IG_Drag` 개체입니다(끌기 라이브러리 참조).
`setXMapper, setYMapper`	내부 `_IG_Drag` 개체의 매퍼를 변경합니다.
`isRightButton`	사용자가 마지막 끌기에서 오른쪽 버튼을 사용한 경우 `true`를 반환합니다.
`refreshCell(index)`	`index`의 셀을 새로 고칩니다. `_IGG_refreshCell()` 콜백을 사용하는 것과 동일합니다.
`refreshAll()`	모든 셀을 새로 고칩니다. `_IGG_refreshAll()` 콜백을 사용하는 것과 동일합니다.
`refreshDragSources()`	소스를 확인하기 위해 모든 셀을 다시 계산하고 해당 소스를 기본 Drag 개체에 등록합니다.
`refreshDragTargets(sourceIndex)`	`sourceIndex`에서 소스 대상이 되는 모든 셀을 새로 고칩니다. 하지만 대상이 기본 Drag 개체에 등록되지는 않습니다.
`refreshDragNonTargets(sourceIndex)`	`sourceIndex`에서 소스 대상이 아닌 모든 셀을 새로 고칩니다.
`addDragSource(index)`	`isDragSource`에서 `false`를 반환해도 유효한 소스가 되는 셀을 추가합니다.
`removeDragSource(index)`	`isDragSource`에서 `true`를 반환해도 유효한 소스가 되는 셀을 제거합니다.
`removeDragSource(index)`	`isDragSource`에서 `true`를 반환해도 유효한 소스가 되는 셀을 제거합니다.
`calculateDragTargets(sourceIndex)`	`sourceIndex`의 모든 소스 대상을 기본 Drag 개체에 등록합니다.

고급 백엔드 함수

Grid 개체의 dragHandler를 재정의하는 경우 사용자가 Grid에서 처리할 수 없는 항목을 끄는 경우가 있습니다. 이런 경우 백엔드 개체에 백엔드 함수가 있으면 해당 함수를 호출하려고 합니다. 백엔드 함수의 작동 방법에 대한 자세한 내용을 보려면 끌기 라이브러리를 참조하십시오.

_IGG_handleOnDragStart(object)
_IGG_handleOnDragTargetHit(object)
_IGG_handleOnDragTargetLost()
_IGG_handleOnDragEnd(object, object)
_IGG_handleOnDragClick(object)

MiniMessage 라이브러리

MiniMessage 라이브러리 및 예를 활용하는 방법에 대한 자세한 내용을 보려면 MiniMessages를 참조하십시오.

MiniMessage 라이브러리를 사용하려면 가젯의 <ModulePrefs> 아래에 다음 줄이 포함되어야 합니다.

<Require feature="minimessage" />

아래 표에는 MiniMessage 생성자와, MiniMessage 개체를 인스턴스화한 경우 해당 개체에 대해 호출할 수 있는 함수가 나와 있습니다.

함수	설명
_IG_MiniMessage(moduleId, opt_container)	MiniMessage 생성자로, 새로운 MiniMessage 개체를 인스턴스화합니다. 가젯의 __MODULE_ID__를 매개변수로 사용합니다. 생성자는 선택적으로 opt_container 매개변수를 사용합니다. 해당 매개변수는 메시지가 추가되는 HTML 요소(일반적으로 <div>)를 지정합니다. opt_container를 생략하면 기본 메시지 컨테이너가 자동으로 생성되고 가젯 맨 위에 위치합니다. 예: var mini = new _IG_MiniMessage(__MODULE_ID__, _gel("messageContainer"));
createDismissibleMessage(msg, opt_callback)	취소가 가능한 메시지를 생성합니다. msg 매개변수는 HTML 문자열 또는 요소입니다. 사용자가 메시지를 취소할 수 있도록 하는 클릭 가능한 [x] 링크를 사용하여 메시지를 표시합니다. 메시지를 취소하면 DOM에서 해당 메시지가 제거되고 옵션 콜백 함수 opt_callback이 호출됩니다. 콜백에서 거짓이 반환되면 작업이 무효화 됩니다. 예: mini.createDismissibleMessage("Loading message"); mini.createDismissibleMessage(_gel("loading"));
createTimerMessage(msg, seconds, opt_callback)	지정된 수의 seconds 동안 표시되는 시간 제한 메시지를 생성합니다. msg 매개변수는 HTML 문자열 또는 요소입니다. 타이머가 만료되면 메시지에서 옵션 콜백 함수 opt_callback가 실행되는 취소 프로시저를 시작합니다. 콜백에서 거짓이 반환되면 취소 작업이 무효로 됩니다. 예: mini.createTimerMessage("Your account has been updated.", 5);
createStaticMessage(msg)	dismissMessage(msg)에 의해 프로그래밍 방식으로 취소될 때까지 표시되는 정적 메시지를 생성합니다. msg 매개변수는 HTML 문자열 또는 요소입니다. 예: var loadMsg = mini.createStaticMessage("Loading content...");
dismissMessage(msg)	지정된 메시지 msg를 취소합니다. 해당 함수는 정적 메시지를 취소하는 유일한 방법입니다. 예: var loadMsg = mini.createStaticMessage("Loading content..."); mini.dismissMessage(loadMsg);

analytics 라이브러리

analytics 라이브러리 및 예를 활용하는 방법에 대한 자세한 내용을 보려면 Analytics 사용을 참조하십시오.

analytics 라이브러리를 사용하려면 가젯의 <ModulePrefs> 아래에 다음 줄이 포함되어야 합니다.

<Require feature="analytics" />

analytics 라이브러리에는 다음 함수가 포함되어 있습니다.

함수	설명
_IG_Analytics(id, path)	하나의 Google Analytics 계정에 단일 페이지뷰를 기록합니다. 하나의 가젯 내에서 여러 개의 호출을 지원합니다. id 매개변수는 Google Analytics 계정 ID입니다. path 매개변수는 각 호출에 대해 Google Analytics로 다시 기록되는 가상 페이지뷰 경로입니다. 해당 값은 광고주의 Analytics 리포트 내에서 여러 가젯에 대한 페이지뷰 조회수를 확인할 수 있도록 고유한 이름으로 설정합니다. 예: _IG_Analytics("UA_000000-0", "/weathergadget");

함수

설명

_IG_Analytics(id, path)

하나의 Google Analytics 계정에 단일 페이지뷰를 기록합니다. 하나의 가젯 내에서 여러 개의 호출을 지원합니다.

id 매개변수는 Google Analytics 계정 ID입니다.

path 매개변수는 각 호출에 대해 Google Analytics로 다시 기록되는 가상 페이지뷰 경로입니다. 해당 값은 광고주의 Analytics 리포트 내에서 여러 가젯에 대한 페이지뷰 조회수를 확인할 수 있도록 고유한 이름으로 설정합니다.

예:

_IG_Analytics("UA_000000-0", "/weathergadget");

요청 매개변수

iGoogle에서 가젯 URL을 요청하면 매개변수는 GET 방식인 요청에 추가됩니다. 이는 콘텐츠 유형이 'url'로 설정된 경우에만 적용됩니다. 자세한 내용을 보려면 URL을 참조하십시오. 해당 매개변수는 JavaScript를 사용하는 가젯 또는 서버측 웹 응용 프로그램에서 읽을 수 있습니다. 예를 보려면 URL을 참조하십시오.

전달되는 매개변수는 다음 표에 나와 있습니다.

이름	설명
up_<name>	사용자 환경설정 및 해당 값입니다. 각 사용자 환경설정의 경우 다음 형식을 사용하여 이름-값 쌍이 매개변수로 전달됩니다. `&up_=` 예를 들어, `zp`라는 우편번호 매개변수에 해당 값으로 94306을 지정했다고 가정하는 경우, 해당 매개변수는 URL에서 다음과 같이 전달됩니다. `&up_zp=94306`
lang	브라우저에서 설정되는 사용자의 언어 환경설정입니다.
country	사용자의 Google 게정에서 정의되는 사용자 국가입니다.

위로 이동

Google 가젯 API 개발자 가이드

리소스

Google 가젯 API 참조

목차

XML 구조

가젯 환경설정

라이브러리 사용

로케일 지정

호환성 요구사항 지정하기

사용자 환경설정

Enum 데이터 유형

콘텐츠 섹션

JavaScript 라이브러리

JavaScript 코어 라이브러리

JavaScript 기능 라이브러리

setprefs 라이브러리

dynamic-height 라이브러리

tabs 라이브러리

drag 라이브러리

끌기 특성

grid 라이브러리

그리드에 필요한 백엔드 함수

그리드 백엔드 표시 함수

그리드 백엔드 반응 함수

그리드 백엔드 콜백

그리드 개체 특성

고급 백엔드 함수

MiniMessage 라이브러리

analytics 라이브러리

요청 매개변수