가젯 XML 참조

가젯 사양 XML에 대한 참조입니다.

자바스크립트 참조는 여기에서 확인할 수 있습니다.

ModulePrefs 요소 및 속성

XML 파일의 <ModulePrefs> 섹션은 제목, 저자, 선호하는 크기 등 가젯의 특성을 지정합니다. 예를 들면 다음과 같습니다.

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

가젯 사용자는 이러한 속성을 변경할 수 없습니다.

<ModulePrefs>는 모든 메타데이터, 기능, 처리 규칙의 컨테이너 요소 역할을 합니다. 중첩된 요소 설명은 아래 개별 섹션을 참고하세요. 이 섹션에는 <ModulePrefs>의 요소와 속성이 요약되어 있습니다. 중첩 섹션에서 슬래시로 표시됩니다. 예를 들어, /ModulePrefs/Locale<ModulePrefs> 요소 내에 중첩된 <Locale> 요소를 설명합니다. 다음과 같이 가젯 사양에 표시될 수 있습니다.

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

모듈 사전

다음 표에는 모든 컨테이너에서 지원되는 <ModulePrefs> 속성이 나와 있습니다. 컨테이너별 <ModulePrefs> 속성은 컨테이너 문서를 참조하세요.

속성 설명
title 가젯의 제목을 제공하는 문자열입니다(선택사항). 이 제목은 iGoogle의 가젯 제목 표시줄에 표시됩니다. 이 문자열에 사용자 환경설정 대체 변수가 포함되어 있고 iGoogle 콘텐츠 디렉터리에 가젯이 제출되도록 하려면 디렉터리 표시를 위한 directory_title도 제공해야 합니다.
title_url 선택사항. 가젯 제목이 연결되는 URL을 제공하는 문자열입니다. 예를 들어 제목을 가젯과 관련된 웹페이지에 연결할 수 있습니다.
description 선택사항. 가젯에 대해 설명하는 문자열입니다.
author 선택사항으로, 가젯의 작성자를 나열하는 문자열입니다.
author_email 가젯 작성자의 이메일 주소를 제공하는 문자열입니다(선택사항). 모든 이메일 시스템을 사용할 수 있지만 스팸으로 인해 개인 이메일 주소를 사용해서는 안 됩니다. 한 가지 방법은 가젯 사양에서 helensmith.feedback+coolGadget@gmail.com과 같은 형식의 이메일 주소를 사용하는 것입니다.

더하기 기호(+) 다음에 Gmail이 모두 제외되므로, 이 이메일 주소는 helensmith.feedback@gmail.com으로 해석됩니다.

여기에서 Gmail 계정을 만들 수 있습니다.
screenshot 선택사항. 가젯 스크린샷의 URL을 제공하는 문자열입니다. robots.txt에 의해 차단되지 않은 공개 웹사이트의 이미지여야 합니다. PNG를 사용하는 것이 좋지만 GIF와 JPG도 허용됩니다. 가젯 스크린샷의 너비는 280픽셀이어야 합니다. 스크린샷의 높이는 사용 중일 때 가젯의 자연스러운 높이여야 합니다.
thumbnail 선택사항. 가젯 썸네일의 URL을 제공하는 문자열입니다. robots.txt에 의해 차단되지 않은 공개 웹사이트의 이미지여야 합니다. PNG를 사용하는 것이 좋지만 GIF와 JPG도 허용됩니다. 가젯 썸네일은 120x60픽셀이어야 합니다.

ModulePrefs/Require 및 ModulePrefs/Optional

<Require><Optional> 요소는 가젯의 기능 종속 항목을 선언합니다.

속성:

  • "feature" - 특성의 이름입니다. 필수

예:

<Require feature="dynamic-height"/>
<Optional feature="shareable-prefs"/>

ModulePrefs/Require/Param 및 ModulePrefs/Optional/Param

이러한 요소는 기능의 구성 매개변수를 제공합니다.

속성:

  • "name" - 매개변수의 이름입니다. 필수 항목입니다.

ModulePrefs/미리 로드

<Preload> 요소는 가젯 렌더링 프로세스 동안 원격 소스에서 데이터를 가져오도록 컨테이너에 지시합니다. 이 요소는 원격 서버에서 데이터를 가져오는 makeRequest()와 함께 사용됩니다.

예를 들어 다음과 같은 요청이 있다고 가정해 보겠습니다.

gadgets.io.makeRequest("http://www.example.com", response, params);

<Preload>의 가젯 <ModulePrefs> 섹션에 태그를 추가하여 http://www.example.com에서 콘텐츠를 미리 로드할 수 있습니다.

<ModulePrefs title="Demo Preloads" description="Demo Preloads">
  <Preload href="http://www.example.com" />
</ModulePrefs>

가젯이 makeRequest() 호출을 실행하면 서버를 다시 조회할 필요 없이 이 콘텐츠가 즉시 반환됩니다.

<Preload>를 사용하여 원격 서버에서 데이터를 가져오는 데 makeRequest()를 사용하는 가젯의 지연 시간을 줄일 수 있습니다.

속성:

  • "href": 미리 가져올 데이터의 위치를 지정하는 URL입니다. 필수 항목입니다.
  • "authz": 이 요청에 사용하는 인증 유형입니다. 유효한 값은 "none" (기본값), "signed", "oauth"입니다. 선택사항입니다.

이러한 속성은 makeRequest() 쿼리 문자열의 승인 매개변수에 매핑됩니다.

속성 설명
oauth_service_name 가젯이 XML 사양에서 OAuth <Service> 요소를 참조하는 데 사용하는 닉네임입니다. 지정하지 않으면 기본값은 '"입니다. gadgets.io.RequestParameters.OAUTH_SERVICE_NAME에 매핑됩니다.
oauth_token_name 가젯이 특정 리소스에 대한 액세스 권한을 부여하는 OAuth 토큰을 참조하는 데 사용하는 닉네임입니다. 지정하지 않으면 기본값은 ""입니다. 동일한 서비스 제공업체의 여러 리소스에 액세스할 수 있는 경우 가젯은 여러 토큰 이름을 사용할 수 있습니다. 예를 들어 연락처 목록 및 캘린더에 대한 액세스 권한이 있는 가젯은 토큰 목록 토큰을 사용하려면 '연락처' 토큰 이름을 사용하고 캘린더 토큰을 사용하려면 '캘린더' 연락처 이름을 사용합니다. gadgets.io.RequestParameters.OAUTH_TOKEN_NAME에 매핑합니다.
oauth_request_token 서비스 제공업체가 리소스에 대한 액세스가 사전 승인된 요청 토큰으로 자동으로 프로비저닝을 프로비저닝할 수 있습니다. 가젯은 이 토큰을 OAUTH_REQUEST_TOKEN 매개변수와 함께 사용할 수 있습니다. 이 매개변수는 선택사항입니다. gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN에 매핑됩니다.
oauth_request_token_secret 사전 승인된 요청 토큰에 해당하는 보안 비밀입니다. 이 매개변수는 선택사항입니다. gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN_SECRET에 매핑합니다.
sign_owner 소유자를 인증해야 하는지 여부를 나타내는 부울입니다. 지정하지 않으면 기본값은 "true"입니다. gadgets.io.RequestParameters.SIGN_OWNER에 매핑합니다.
sign_viewer 뷰어의 인증 여부를 나타내는 불리언입니다. 지정하지 않으면 기본값은 "true"입니다. gadgets.io.RequestParameters.SIGN_VIEWER에 매핑합니다.
views 지정된 미리 로드를 트리거하는 뷰 이름의 쉼표로 구분된 목록입니다.

모든 <Preload> 속성은 프록시 콘텐츠에도 적용됩니다.

ModulePrefs/아이콘

<Icon> 요소는 컨테이너가 특정 가젯과 연결할 수 있는 16px x 16px 이미지를 지정합니다. 예를 들어, 컨테이너는 왼쪽 탐색 메뉴에서 가젯 이름 옆에 아이콘을 표시할 수 있습니다.

<Icon> 태그의 콘텐츠는 다음 중 하나일 수 있습니다.

  • 웹의 이미지 파일을 가리키는 HTTP URL
  • 인라인 base64로 인코딩된 이미지 데이터입니다.

속성:

  • "mode" -- 이미지를 삽입할 때 아이콘에 사용되는 인코딩입니다. 현재 base64만 지원됩니다. 선택사항입니다.
  • "type": 삽입된 아이콘 텍스트의 MIME입니다. 선택사항입니다.

예:

<ModulePrefs title="My gadget">
  <Icon>http://remote/favicon.ico</Icon>
</ModulePrefs>

<ModulePrefs title="My gadget">
  <Icon mode="base64" type="image/png">base64 encoded data</Icon>
</ModulePrefs>

ModulePrefs/언어

<Locale> 요소는 가젯에서 지원하는 언어를 지정합니다. 또한 가젯 및 국제화에 설명된 대로 이를 사용하여 메시지 번들을 지정할 수 있습니다.

속성:

  • "lang" -- 언어와 연결된 언어입니다. 선택사항입니다.
  • "country" -- 언어와 연결된 국가입니다. 선택사항입니다.
  • "messages": 메시지 번들로 연결되는 URL입니다. 메시지 번들은 특정 언어의 번역된 문자열이 포함된 XML 파일입니다. 자세한 내용은 가젯 및 국제화를 참고하세요. 선택사항입니다.
  • "language_direction" -- 가젯의 방향입니다. 선택사항입니다. 값은 'rtl'(오른쪽에서 왼쪽) 또는 'ltr'(왼쪽에서 오른쪽)일 수 있습니다. 기본값은 &ltt입니다. 이 속성을 사용하면 왼쪽에서 오른쪽 언어와 오른쪽에서 왼쪽 언어를 모두 지원하는 가젯이 생성됩니다. 이 주제에 대한 자세한 내용은 양방향 가젯 만들기를 참조하세요. 다음 대체 변수를 language_direction과 함께 사용할 수 있습니다.
    • __BIDI_START_EDGE__: 가젯이 LTR 모드일 때는 값이 '왼쪽'이고 가젯이 RTL 모드일 때는 값이 '오른쪽'입니다.
    • __BIDI_END_EDGE__: 가젯이 LTR 모드일 때 값이 '오른쪽'이고 가젯이 RTL 모드일 때 값은 '왼쪽'입니다.
    • __BIDI_DIR__: 이 변수의 값은 가젯이 LTR 모드일 때 "rtl"입니다.
    • __BIDI_REVERSE_DIR__: 이 변수의 값은 가젯이 LTR 모드일 때 'rtl'입니다.

예를 들어, 이 스니펫은 서로 다른 두 가지 언어를 지정합니다.

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

'lang'(언어) 및 'country' 속성은 모두 선택사항이지만 각 <Locale>에 속성이 하나 이상 있어야 합니다. 둘 중 하나의 속성을 생략하는 경우 값은 "*" 및 "ALL'과 동일합니다. 국가를 지정하지 않고 언어를 지정하지 않으면 가젯이 해당 국가와 연결된 모든 언어를 지원한다고 가정합니다. 마찬가지로 언어를 지정하고 국가는 지정하지 않으면 가젯이 해당 언어와 관련된 모든 국가를 지원한다고 가정합니다.

유효한 언어 값은 ISO639-1 두 자리 언어 코드이며, 국가의 경우 ISO 3166-1 alpha-2 코드입니다.

일반적인 언어 규칙에는 다음과 같은 몇 가지 예외가 있습니다.

  • 중국어 간체: lang="zh-cn"(일반적으로 country="cn"용)
  • 중국어 번체: lang="zh-tw" (대개 국가 샘플, 일반적으로 타이완 또는 홍콩의 경우)

ModulePrefs/OAuth

<OAuth> 요소는 OAuth 프록시의 가젯 사용을 정의합니다. 가젯에서 OAuth를 구현하는 방법에 대한 자세한 내용은 OAuth 가젯 작성을 참조하세요.

ModulePrefs/OAuth/서비스

이 요소는 단일 OAuth 서비스 구성을 식별합니다.

속성:

  • "name" - 런타임 시 OAuth 서비스를 참조할 때 사용되는 서비스의 이름입니다 (예: "google"). 이 매개변수는 선택사항이며 지정되지 않은 경우 기본값은 ""입니다. 가젯 개발자는 서비스 이름을 makeRequest()에 매개변수로 전달하여 사용할 OAuth 서비스를 지정합니다.

ModulePrefs/OAuth/Service/Request 및 ModulePrefs/OAuth/Service/Access

OAuth 요청 토큰 및 액세스 토큰 URL을 나타냅니다. 자세한 내용은 OAuth 사양OAuth 가젯 작성을 참조하세요.

속성:

  • "url" - 엔드포인트의 URL입니다.
  • "method" - 요청에 사용할 HTTP 동사입니다. 이 매개변수는 선택사항입니다. 지정하지 않으면 기본값은 POST입니다.
  • "param_location" -- OAuth 매개변수가 전달될 수 있는 서비스에 대한 3가지 위치 중 하나입니다. 이 값을 사용하여 OAuth 관련 매개변수의 위치를 지정할 수 있습니다. 가능한 값은 다음과 같습니다.
    • "uri-query" -- 쿼리 매개변수에 OAuth 매개변수가 전달됩니다.
    • "auth-header" - 승인 헤더에 OAuth 매개변수가 전달됩니다.
    • "post-body" -- OAuth 매개변수가 POST 요청의 본문에 전달됩니다.

이 값은 OAuth 사양에 설명된 옵션에 해당합니다. 기본값은 "auth-header"입니다.

ModulePrefs/OAuth/서비스/승인

OAuth 승인 URL입니다.

사용자 환경설정

일부 가젯은 사용자에게 사용자별 정보를 제공하는 방법을 제공해야 합니다. 예를 들어 날씨 가젯의 경우 사용자가 우편번호를 입력해야 할 수 있습니다. XML 파일의 사용자 환경설정(<UserPref>) 섹션은 가젯이 실행될 때 사용자 인터페이스 컨트롤로 전환되는 사용자 입력 필드를 설명합니다.

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

속성 설명
name 사용자 환경설정의 필수 '기호 이름'으로, display_name이 정의되지 않은 경우 수정 중에 사용자에게 표시됩니다. 문자, 숫자, 밑줄만 포함해야 합니다(즉, 정규 표현식 ^[a-zA-Z0-9_]+$). 고유해야 합니다.
display_name 편집창에서 사용자 환경설정과 함께 표시할 문자열입니다(선택사항). 고유한 이름이어야 합니다.
urlparam type="url" 콘텐츠의 매개변수 이름으로 전달할 선택적 문자열입니다.
datatype 이 속성의 데이터 유형을 나타내는 문자열입니다(선택사항). string, bool, enum, hidden (표시되지 않거나 사용자가 수정할 수 있는 문자열) 또는 list (사용자 입력에서 생성된 동적 배열)일 수 있습니다. 기본값은 string입니다.
required 이 사용자 환경설정이 필요한지 여부를 나타내는 불리언 인수(true 또는 false)(선택사항)입니다. 기본값은 false입니다.
default_value 선택사항. 사용자 환경설정을 나타내는 문자열입니다.

사용자 환경설정은 사용자 환경설정 자바스크립트 API를 사용해 가젯에서 액세스할 수 있습니다. 예를 들면 다음과 같습니다.

<script type="text/javascript">
   var prefs = new _IG_Prefs();
   var someStringPref = prefs.getString("StringPrefName");
   var someIntPref = prefs.getInt("IntPrefName");
   var someBoolPref = prefs.getBool("BoolPrefName");
</script>

열거형 데이터 유형

<UserPref> datatype 속성에 지정할 수 있는 값 중 하나는 enum입니다. enum 데이터 유형은 사용자 인터페이스에 선택 메뉴로 표시됩니다. <EnumValue>를 사용하여 메뉴의 콘텐츠를 지정합니다.

예를 들어 이 <UserPref>를 사용하면 사용자가 게임의 난이도를 설정할 수 있습니다. 메뉴 (Easy, Medium, Hard)에 표시될 각 값은 <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 콘텐츠 유형을 제공하는 문자열입니다(선택사항). 가능한 값은 htmlurl입니다. 기본값은 html입니다.
href 도착 URL을 제공하는 문자열입니다. 이는 type="url" 가젯 또는 프록시 콘텐츠에 적용될 수 있습니다.
view 선택적 문자열입니다. 콘텐츠를 표시할 컨테이너의 뷰를 나타냅니다. 가젯은 콘텐츠 섹션을 여러 개 정의할 수 있으며, 각 섹션을 서로 다른 뷰 또는 뷰에 적용할 수 있습니다.
preferred_height 가젯의 초기 높이입니다(픽셀 단위).
preferred_width 가젯의 초기 너비(픽셀)입니다.

ModulePrefs/Content@href (프록시 콘텐츠)

프록시 콘텐츠는 특정 보기에 URL로 HTML 콘텐츠를 지정할 수 있는 기능입니다.

이 기능에 지정하는 타겟 URL은 유효한 HTML 4.01, XHTML 1.1 등이어야 합니다. 이미지 또는 플래시 URL을 지정해서는 안 되지만, HTML로 래핑한 다음 HTML에 링크할 수는 있습니다. 타겟 HTML 콘텐츠에는 <html>, <head><body> 태그가 포함되어야 합니다.

예를 들어 이 가젯은 canvas 뷰에는 프록시 콘텐츠를, home 뷰에는 인라인 콘텐츠를 사용합니다.

<?xml version="1.0" encoding="UTF-8"?>
<Module>
  <ModulePrefs title="Proxied Content Example">
</ModulePrefs>
  <Content view="canvas" 
    href="http://gadget-doc-examples.googlecode.com/svn/trunk/opensocial-09/mycontent.html">
  </Content>
  <Content view="home">
    <![CDATA[
      Hello, home view!
    ]]>
  </Content>
</Module>

프록시 콘텐츠에는 <Preload> 요소에 적용되는 것과 동일한 속성이 사용됩니다. 자세한 내용은 ModulePrefs/Preload를 참고하세요.

자바스크립트 참조

자바스크립트 참조는 여기에서 확인할 수 있습니다.

기능별 자바스크립트 라이브러리 포함

탭 또는 플래시 영화와 같은 특정 기능을 사용하는 가젯의 경우 <ModulePrefs> 내에서 <Require> 태그를 사용하여 가젯 사양에 기능 라이브러리를 포함해야 합니다. 예를 들면 다음과 같습니다.

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

gadgets.* API는 다음과 같은 기능 라이브러리를 제공합니다.

특성 라이브러리 설명 구문
setprefs 프로그래매틱 방식으로 사용자 환경설정의 값을 설정합니다. 자세한 내용은 상태 저장을 참조하세요. <Require feature="setprefs"/>
dynamic-height 가젯이 자동으로 크기를 조절할 수 있도록 합니다. 자세한 내용은 가젯 높이 관리를 참고하세요. <Require feature="dynamic-height"/>
settitle 가젯의 제목을 프로그래매틱 방식으로 설정합니다. 자세한 내용은 가젯 제목 설정을 참조하세요. <Require feature="settitle"/>
tabs 탭 형식의 인터페이스를 가젯에 추가합니다. 자세한 내용은 을 참고하세요. <Require feature="tabs"/>
minimessage 가젯에 닫을 수 있는 임시 메시지를 표시합니다. 자세한 내용은 MiniMessage를 참고하세요. <Require feature="minimessage"/>
flash 플래시 동영상 (특히 .swf 파일)을 가젯에 삽입합니다. 자세한 내용은 플래시를 참고하세요. <Require feature="flash"/>
locked-domain locked-domain 라이브러리는 동일한 페이지에서 실행되는 다른 가젯과 가젯이 격리됩니다. type="html" 가젯에서만 이 기능을 사용할 수 있습니다. 가젯이 민감한 개인 사용자 데이터를 저장하는 경우 가젯에 이 기능 요구사항을 추가하는 것이 좋습니다. 이 기능은 iGoogle 및 Google Calendar에서만 지원됩니다. 다른 가젯 컨테이너는 이 기능을 지원하지 않을 수 있고 가젯이 거부됩니다. <Require feature="locked-domain"/>

특정 기능에서 지원되는 모든 메서드를 확인하려면 자바스크립트 참조를 확인하세요.

 

맨 위로