Odniesienie do pliku XML gadżetu

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

To jest plik referencyjny dla specyfikacji XML gadżetu.

Odniesienie do JavaScriptu znajdziesz tutaj.

Elementy i atrybuty ModułPrefs

Sekcja <ModulePrefs> w pliku XML określa cechy gadżetu, takie jak tytuł, autor, preferowane rozmiary itd. Na przykład:

<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>

Użytkownicy Twojego atrybutu nie mogą zmienić tych atrybutów.

<ModulePrefs> jest elementem kontenera, w którym znajdują się wszystkie metadane, funkcje i reguły przetwarzania. Zagnieżdżone opisy elementów znajdziesz poniżej. Ta sekcja zawiera podsumowanie elementów i atrybutów atrybutu <ModulePrefs>. W sekcjach poniżej poziom zagnieżdżania jest określany za pomocą ukośników. Na przykład /ModulePrefs/Locale opisuje element <Locale>, który jest zagnieżdżony w elemencie <ModulePrefs>. Może on wyglądać tak: 

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

Moduły modułu

Poniższa tabela zawiera atrybuty <ModulePrefs>, które są obsługiwane we wszystkich kontenerach. W dokumentacji kontenera znajdziesz wszelkie atrybuty <ModulePrefs> związane z kontenerem.

Atrybut Opis
title Opcjonalny ciąg znaków zawierający tytuł gadżetu. Ten tytuł jest wyświetlany na pasku tytułu gadżetu na stronie iGoogle. Jeśli ten ciąg zawiera zmienne zastępowania preferencji użytkowników i zamierzasz przesłać gadżet do katalogu treści iGoogle, musisz też podać wartość directory_title dla wyświetlania katalogu.
title_url Opcjonalny ciąg znaków zawierający adres URL, do którego prowadzi tytuł gadżetu. Możesz na przykład dodać link do strony internetowej powiązanej z gadżetem.
description Opcjonalny ciąg tekstowy zawierający opis gadżetu.
author Opcjonalny ciąg znaków zawierający listę autora gadżetu.
author_email Opcjonalny ciąg znaków zawierający adres e-mail autora gadżetu. Możesz użyć dowolnego systemu poczty e-mail, ale nie możesz używać osobistego adresu e-mail ze względu na spam. Jednym ze sposobów jest użycie adresu e-mail w postaci helensmith.feedback+coolgadget@gmail.com w specyfikacji gadżetu.

screenshot Opcjonalny ciąg znaków zawierający adres URL zrzutu ekranu gadżetu. Musi to być obraz w publicznej witrynie, która nie jest zablokowana przez plik robots.txt. Preferowanym formatem jest PNG, ale akceptowane są też GIF-y i pliki JPG. Zrzuty ekranu gadżetów powinny mieć szerokość 280 pikseli. Wysokość zrzutu ekranu powinna być taka, jaka będzie w tym czasie w użyciu.
thumbnail Opcjonalny ciąg znaków zawierający adres URL miniatury gadżetu. Musi to być obraz w publicznej witrynie, która nie jest zablokowana przez plik robots.txt. Preferowanym formatem jest PNG, ale akceptowane są też GIF-y i pliki JPG. Miniatury gadżetów powinny mieć rozmiar 120 x 60 pikseli.

ModulePrefs/Wymagaj i ModulePrefs/Opcjonalnie

Elementy <Require> i <Optional> deklarują zależności funkcji gadżetu.

Atrybuty:

  • "feature" – nazwa funkcji; Wymagany

Przykłady: 

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

ModulePrefs/Wymagaj/Param i ModulePrefs/Opcjonalnie/Param

Te elementy określają parametry konfiguracji funkcji.

Atrybuty:

  • "name" – nazwa parametru; Wymagany.

ModulePrefs/Preload

Element <Preload> instruuje kontener, by pobierał dane ze źródła zdalnego podczas renderowania gadżetu. Ten element jest używany w połączeniu z metodą makeRequest(), która pobiera dane z serwera zdalnego.

Załóżmy na przykład, że masz żądanie podobne do tego: 

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

Możesz wstępnie załadować zawartość strony http://www.example.com, dodając tag <Preload> do swojego gadżetu <ModulePrefs>: 

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

Gdy wywołasz obiekt makeRequest(), zawartość jest natychmiast zwracana bez konieczności ponownego klikania serwera.

Wykorzystujesz <Preload>, aby zmniejszyć opóźnienie w przypadku gadżetów korzystających z makeRequest() do pobierania danych z serwerów zdalnych.

Atrybuty:

  • "href" – adres URL określający lokalizację danych, które mają być pobierane z wyprzedzeniem. Wymagany.
  • "authz" – typ uwierzytelniania używany w przypadku tego żądania; Prawidłowe wartości to "none" (domyślnie), "signed" i "oauth". Opcjonalne.

Te atrybuty odpowiadają parametrom autoryzacji w ciągu zapytania makeRequest():

Atrybut Opis
oauth_service_name Pseudonim używany przez gadżet w odniesieniu do elementu OAuth <Service> ze specyfikacji XML. Jeśli nie podano tego argumentu, ustawieniem domyślnym jest "". Mapy na gadgets.io.RequestParameters.OAUTH_SERVICE_NAME.
oauth_token_name Pseudonim używany przez gadżet w odniesieniu do tokena OAuth przyznającego dostęp do określonych zasobów. Jeśli nie podano tego argumentu, domyślnie jest on ustawiany na &". Na przykład gadżetu z dostępem do listy kontaktów i kalendarza można używać nazwy tokena "kontakty&, aby korzystać z tokena listy kontaktów, oraz listy kontaktów &kalendarza kontaktów. Mapa do: gadgets.io.RequestParameters.OAUTH_TOKEN_NAME.
oauth_request_token Dostawca usług może automatycznie udostępnić widżet za pomocą tokena żądania, który został wstępnie zatwierdzony dla dostępu do zasobu. Gadżet może używać tego tokena z parametrem OAUTH_REQUEST_TOKEN. Ten parametr jest opcjonalny. Mapa do: gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN.
oauth_request_token_secret Tajny klucz odpowiadający wstępnie zatwierdzonemu tokenowi żądania. Ten parametr jest opcjonalny. Mapa do: gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN_SECRET.
sign_owner Wartość logiczna, która określa, czy właściciel musi być uwierzytelniony. Jeśli nie podano tego argumentu, ustawieniem domyślnym jest "true". Mapa do: gadgets.io.RequestParameters.SIGN_OWNER.
sign_viewer Wartość logiczna, która określa, czy należy uwierzytelnić widza. Jeśli nie podano tego argumentu, ustawieniem domyślnym jest "true". Mapa do: gadgets.io.RequestParameters.SIGN_VIEWER.
views Lista rozdzielonych przecinkami nazw widoków danych, które aktywują określone wczytywanie.

Wszystkie atrybuty <Preload> odnoszą się również do treści przesyłanych przez serwer proxy.

Ikony modułu/ikony

Element <Icon> określa obraz o wymiarach 16 x 16 pikseli, który można powiązać z konkretnym gadżetem (np. kontener może wyświetlać ikonę obok nazwy gadżetu na lewym pasku nawigacyjnym).

Znacznikiem <Icon> może być jedna z tych treści:

  • Adres URL HTTP wskazujący plik obrazu w internecie
  • Wbudowane dane obrazu zakodowane w formacie base64.

Atrybuty:

  • "mode" – kodowanie ikony używane podczas umieszczania obrazu. Obecnie obsługiwany jest tylko base64. Opcjonalne.
  • "type" – MIME osadzonego tekstu ikony. Opcjonalne.

Przykłady:

<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

Element <Locale> określa języki obsługiwane przez Twój gadżet. Możesz też za jej pomocą określać pakiety wiadomości, tak jak to opisano w sekcji Gadżety i internacjonalizacja.

Atrybuty:

  • "lang" – język powiązany z lokalizacją, Opcjonalne.
  • "country" – kraj powiązany z regionem; Opcjonalne.
  • "messages" – adres URL wskazujący grupę wiadomości. Pakiety wiadomości to pliki XML zawierające przetłumaczone ciągi tekstowe dla danego języka. Więcej informacji znajdziesz w artykule Gadżety i internacjonalizacja. Opcjonalne.
  • "language_direction" – kierunek gadżetu. Opcjonalne. Jego wartością może być "rtl" (od prawej do lewej) lub "ltr" (od lewej do prawej). Wartość domyślna to "ltr". Ten atrybut umożliwia tworzenie gadżetów obsługujących język „od lewej do prawej” i „od prawej do lewej”. Więcej informacji na ten temat znajdziesz w artykule Tworzenie gadżetów dwukierunkowych. W połączeniu z atrybutem language_direction możesz użyć tych zmiennych zastępczych:
    • __BIDI_START_EDGE__: wartość to „"left"”, gdy gadżet jest w trybie LTR i "right" w trybie RTL.
    • __BIDI_END_EDGE__: wartość to „"right"”, gdy widżet jest w trybie LTR i "left" w trybie RTL.
    • __BIDI_DIR__: wartość tej zmiennej to "ltr" gdy gadżet jest w trybie LTR i &rtt;rtl" w trybie RTL.
    • __BIDI_REVERSE_DIR__: wartość tej zmiennej to "rtl" gdy gadżet jest w trybie LTR i "ltr" w trybie RTL.

Ten fragment zawiera na przykład 2 różne języki: 

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

Atrybuty "lang" (language) oraz "country" są opcjonalne, ale musisz mieć co najmniej jeden z nich dla każdego elementu <Locale>. Jeśli pominiesz jeden z tych atrybutów, wartość będzie odpowiadać odpowiednikowi "*" i "ALL". Jeśli nie podasz języka, zakładamy, że Twój widżet obsługuje wszystkie języki powiązane z danym krajem. Podobnie jeśli określisz język, nie będzie on zakładał, że Twój gadżet obsługuje wszystkie kraje powiązane z tym językiem.

Prawidłowe wartości języka to dwucyfrowe kody języka ISO639-1, a kraje to kody ISO 3166-1 alfa-2.

Istnieje kilka wyjątków od standardowych reguł językowych:

  • chiński uproszczony: lang="zh-cn" (zazwyczaj w przypadku country="cn").
  • Chiński tradycyjny: lang="zh-tw" (zazwyczaj w przypadku country="tw" lub "hk" Tajwan lub Hongkong).

ModulePrefs/OAuth

Element <OAuth> definiuje gadżety przez serwer proxy OAuth. Więcej informacji o wdrażaniu protokołu OAuth w gadżetu znajdziesz w artykule Gadżety OAuth.

ModulePrefs/OAuth/Service

Ten element określa pojedynczą konfigurację usługi OAuth.

Atrybuty:

  • "name" – nazwa usługi (np. "google") używana w odniesieniu do usług OAuth w czasie działania. Ten parametr jest opcjonalny. Jeśli nie określono tego argumentu, domyślnie przyjmuje się wartość "". Określa on, której usługi OAuth ma używać, przekazując jej nazwę jako parametr do makeRequest().

ModulePrefs/OAuth/Service/Request oraz ModulePrefs/OAuth/Service/Access

Reprezentuje token żądania OAuth i adresy URL tokenów dostępu. Więcej informacji znajdziesz w specyfikacji OAuth i pisaniu gadżetów OAuth.

Atrybuty:

  • "url" – URL punktu końcowego
  • "method" – czas trwania HTTP używany do wysyłania żądania. Ten parametr jest opcjonalny. Jeśli nie podano tego argumentu, ustawieniem domyślnym jest POST.
  • "param_location" – jedna z 3 możliwych lokalizacji w żądaniu do usługi, w której można przekazywać parametry OAuth. Za pomocą tej wartości możesz określić lokalizację parametrów związanych z OAuth. Możliwe wartości:
    • "uri-query" – parametry OAuth są przekazywane w ciągu zapytania.
    • "auth-header" – parametry OAuth są przekazywane w nagłówku autoryzacji.
    • "post-body" – parametry OAuth są przekazywane w treści żądania POST.

Te wartości odpowiadają opcjiom opisanym w specyfikacji OAuth. Wartość domyślna to "auth-header".

ModulePrefs/OAuth/Service/Authorization

Adres URL autoryzacji OAuth.

Preferencje użytkownika

Niektóre gadżety muszą umożliwiać użytkownikom przekazywanie informacji dotyczących konkretnego użytkownika. Na przykład gadżet pogodowy może wymagać od użytkowników podania kodów pocztowych. Sekcja Ustawienia użytkownika (<UserPref>) w pliku XML opisuje pola do wprowadzania danych, które po uruchomieniu gadżetu stają się elementami sterującymi interfejsu.

Poniższa tabela zawiera listę atrybutów <UserPref>:

Atrybut Opis
name Wymagana jest nazwa &preferencja użytkownika, wyświetlana podczas edycji, jeśli nie określono żadnego elementu display_name. Może zawierać tylko litery, cyfry i podkreślenia, tj. wyrażenie regularne ^[a-zA-Z0-9_]+$. Musi być unikalne.
display_name Opcjonalny ciąg znaków, który wyświetla się obok ustawień użytkownika w oknie edycji. Nie może się powtarzać.
urlparam Opcjonalny ciąg znaków, który będzie używany jako nazwa parametru w przypadku treści type="url".
datatype Opcjonalny ciąg znaków wskazujący typ danych tego atrybutu. Może to być string, bool, enum, hidden (ciąg niewidoczny lub nie do edycji przez użytkownika) albo list (tablica dynamiczna wygenerowana na podstawie danych wejściowych użytkownika). Domyślnym ustawieniem jest string.
required Opcjonalny argument logiczny (true lub false), który wskazuje, czy preferencje użytkownika są wymagane. Wartość domyślna to false.
default_value Opcjonalny ciąg określający wartość domyślną użytkownika.

Ustawienia użytkownika można wyświetlić w gadżecie, korzystając z takiego interfejsu: JavaScript API, np.:

<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>

Typy danych Enum

Jedna z wartości atrybutu <UserPref> datatype to enum. Typ danych enum jest wyświetlany w interfejsie jako menu wyboru. Możesz określić zawartość menu za pomocą atrybutu <EnumValue>.

Na przykład ta właściwość <UserPref> umożliwia użytkownikom określanie poziomu trudności gry. Każda wartość, która pojawi się w menu (Prosta, Średnia i Twarda), jest zdefiniowana za pomocą tagu <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>

Poniższa tabela zawiera listę atrybutów <EnumValue>:

Atrybut Opis
value Wymagany ciąg tekstowy z unikalną wartością. Ta wartość jest wyświetlana w menu w polu edycji preferencji użytkownika, chyba że podano display_value.
display_value Opcjonalny ciąg znaków wyświetlany w menu w polu edycji preferencji użytkownika. Jeśli nie określisz właściwości display_value, w interfejsie wyświetli się właściwość value.

Sekcja Treść

Sekcja <Content> określa typ treści i sam zawiera lub odnosi się do treści zewnętrznych. Sekcja <Content> to miejsce, w którym atrybuty gadżetu i preferencje użytkownika są łączone z logiką programowania i informacjami o formatowaniu, aby zostać uruchomionym gadżetem. Więcej informacji o typach treści znajdziesz w artykule Wybieranie typu treści.

Poniższa tabela zawiera listę atrybutów <Content>:

Atrybut Opis
type Opcjonalny ciąg znaków określający typ treści. Możliwe wartości to html i url. Wartość domyślna to html.
href Ciąg znaków z docelowym adresem URL. Może to dotyczyć gadżetu type="url" lub treści przesyłanych przez serwer proxy.
view Opcjonalny ciąg znaków. Wskazuje, w którym widoku kontenera powinna się wyświetlać treść. Gadżet może definiować wiele sekcji treści, z których każda może mieć zastosowanie do innego widoku danych lub widoków.
preferred_height Początkowa wysokość gadżetu w pikselach.
preferred_width Początkowa szerokość gadżetu (w pikselach).

ModulePrefs/Content@href (Treści proxy)

Treść chroniona przez serwer proxy to funkcja, która umożliwia określanie treści HTML dla adresu URL określonego widoku danych.

Docelowy adres URL podany dla tej funkcji powinien być prawidłowym kodem HTML 4.01, XHTML 1.1 itd. Nie określaj obrazu ani adresu URL Flasha, ale możesz umieścić te elementy w kodzie HTML, a potem dodać link do HTML. Docelowa treść HTML musi zawierać tagi <html>, <head> i <body>.

Na przykład ten widok korzysta z treści proxy w widoku canvas i treści wbudowanej w widoku 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>

Serwery proxy korzystają z tych samych atrybutów, które są stosowane do elementu <Preload>. Szczegółowe informacje znajdziesz w sekcji ModulePrefs/Preload.

Dokumentacja JavaScript

Odniesienie do kodu JavaScript znajdziesz tutaj.

W tym biblioteki JavaScript specyficzne dla funkcji

Aby utworzyć gadżet korzystający z określonej funkcji, takiej jak karty lub film Flash, musisz uwzględnić bibliotekę funkcji w specyfikacji gadżetu za pomocą tagu <Require> (w środku <ModulePrefs>). Na przykład: 

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

Interfejs API gadgets.* udostępnia te biblioteki funkcji:

Biblioteka funkcji Opis Składnia
setprefs Służy do automatycznego określania wartości preferencji użytkownika. Więcej informacji znajdziesz w sekcji Zapisywanie stanu. <Require feature="setprefs"/>
dynamic-height Umożliwia usłudze zmianę rozmiaru. Więcej informacji znajdziesz w artykule Zarządzanie wysokością gadżetu. <Require feature="dynamic-height"/>
settitle Automatycznie określa tytuł gadżetu. Więcej informacji znajdziesz w artykule Ustawianie tytułu gadżetu. <Require feature="settitle"/>
tabs Dodaje do interfejsu interfejs z kartami. Więcej informacji znajdziesz w artykule Karty. <Require feature="tabs"/>
minimessage Wyświetla możliwy do zamknięcia tymczasowy komunikat w gadżecie. Więcej informacji znajdziesz w sekcji MiniMessages. <Require feature="minimessage"/>
flash Umieszcza film Flash (zwłaszcza plik .swf) w gadżecie. Więcej informacji znajdziesz w artykule Lampa błyskowa. <Require feature="flash"/>
locked-domain Biblioteka locked-domain izoluje gadżety od innych gadżetów działających na tej samej stronie. Tej funkcji możesz używać tylko w przypadku type="html" gadżetów. Zalecamy dodanie tego wymogu do gadżetu, jeśli zawiera on poufne dane użytkowników. Ta funkcja jest obsługiwana tylko w iGoogle i Kalendarzu Google. Inne kontenery gadżetów mogą nie obsługiwać tej funkcji i zostaną odrzucone. <Require feature="locked-domain"/>

Wszystkie metody obsługiwane przez daną funkcję znajdziesz w dokumentacji JavaScript.

 

Powrót do góry