Piszemy gadżet do Bloggera - część 2

W poprzedniej części (Piszemy gadżet do Bloggera - część 1) poznaliśmy podstawy pisania gadżetu oraz jego strukturę. Dzisiaj poznamy sposoby jego konfigurowania przez użytkownika. Pozwolimy użytkownikowi na podanie dodatkowych informacji podczas dodawania gadżetu do bloga. Dzięki temu użytkownik będzie mógł zdecydować np. o kolorach, napisach czy innych opcjach związanych z konkretnym gadżetem. Sekcją odpowiedzialną za preferencje jest <UserPref>. Opisuje ona pola, które będzie mógł modyfikować użytkownik podczas konfiguracji gadżetu. Pola mogą mieć następujące atrybuty:

• name - nazwa którą będziemy się posługiwać w gadżecie,
• display_name - nazwa wyświetlana użytkownikowi (jej brak powoduje wyświetlenie atrybutu name),
• datatype - typ danych (string - łańcuch tekstowy, bool - wartość logiczna, enum - typ wyliczeniowy, hidden - pole ukyte, list - dynamiczna lista), domyślnym typem jest string,
• required - atrybut logiczny określający czy dane pole jest wymagane,
• default_value - domyślna wartość dla pola

Przykładowe pole preferencji pobierające od użytkownika łańcuch tekstowy (jego imię):

<UserPref name="imie" display_name="Podaj swoje imię:" />

W przypadku wybrania jako atrybutu pola preferencji typu enum, musimy określić dodatkowo opcje, z których może wybierać użytkownik. Opcje te podajemy za pomocą znacznika <EnumValue>. Posiada on dwa parametry:

• value - wartość opcji,
• display_value - nazwa wyświetlana użytkownikowi (jej brak powoduje wyświetlenie atrybutu value).

Przykładowe pole preferencji pobierające od użytkownika kierunek geograficzny (domyślnie południe):

<UserPref name="kierunek" display_name="Kierunek geogr." default_value="south" datatype="enum" >
 <EnumValue value="south" display_value="Południe" />
 <EnumValue value="north" display_value="Północ" />
 <EnumValue value="west" display_value="Zachód" />
 <EnumValue value="east" display_value="Wschód" />
</UserPref>

Dostęp do preferencji z poziomu kodu gadżetu odbywa się z wykorzystaniem JavaScript'u. Poniższy przykład pobierze podane przez użytkownika imię:

var preferencje = new gadgets.Prefs();
var imieUzytkownika = preferencje.getString("imie");

Wykorzystajmy naszą wiedzę do stworzenia prostego gadżetu umożliwiającego użytkownikowi podanie napisu, ustawienie koloru tła oraz określenie czy wyświetlać dzisiejszą datę czy też nie.

Wszystkie operacje związane z wyświetlaniem danych przeprowadzimy z wykorzystaniem JavaScript'u. Nasz przykładowy gadżet uruchamia się od funkcji init() (wywołanie gadgets.util.registerOnLoadHandler(init());) To co ma się pojawić w gadżecie zostało ujęte w sekcję HTML:

<div id="zawartosc"></div> 

Korzystając z możliwości JavaScript'u jesteśmy w stanie zmienić kolor tła tego elementu (element.style.backgroundColor) jak i również wstawić do niego inne elementy czy to teksty czy też znaczniki HTML'a (element.innerHTML). Kod naszego gadżetu:

<?xml version="1.0" encoding="UTF-8" ?> 
<Module>
 <ModulePrefs 
  title="Przykładowy gadżet" 
  author="Devon"> 
  <Require feature="dynamic-height" />
 </ModulePrefs>
 <UserPref name="napis" display_name="Napis" default_value="Nasz drugi gadżet!" />
 <UserPref name="data" display_name="Pokazać datę?" default_value="true" datatype="bool" />
 <UserPref name="kolor" display_name="Kolor tła" default_value="green" datatype="enum" >
  <EnumValue value="red" display_value="Czerwony" />
  <EnumValue value="yellow" display_value="Żółty" />
  <EnumValue value="green" display_value="Zielony" />
 </UserPref>
 <Content type="html">
  <![CDATA[ 
   <div id="zawartosc"></div>

   <script type="text/javascript">
    // pobieramy preferencje
    var preferencje = new gadgets.Prefs();

    // funkcja startowa (nazwa może być dowolna)
    function init() {
     // bierzemy obiekt daty
     var data = new Date();
     // i wyciągamy z niego potrzebne informacje (dzień, miesiąc, rok)
     var dzisiaj = "< br />Dzisiaj jest: " + data.getDate() + "." + (data.getMonth()+1) + "." + data.getFullYear();
     // w tej zmiennej przechowujemy to co później dodamy do gadżetu
     var html = "";
    
     // pobieramy element zawartosc
     var element = document.getElementById('zawartosc');  
     // ustawiamy kolor tła elementu na taki jak podał użytkownik   
     element.style.backgroundColor = preferencje.getString("kolor"); 

     // dodajemy pobrany napis do zmiennej html
     html += preferencje.getString("napis");
   
     // jeżeli użytkownik chce wyświetlać datę
     if (preferencje.getBool("data") == true) {
      // to dodajemy ją do zmiennej html
      html += dzisiaj;
     }

     // wklejamy do "elementu" zawartość zmiennej html
     element.innerHTML = html;
    
     // zmieniamy wysokość gadżetu
     gadgets.window.adjustHeight(); 
    }

    // za pomocą tej metody podajemy funkcję, która
    // ma zostać uruchomiona podczas startu gadżetu (tutaj init())
    gadgets.util.registerOnLoadHandler(init()); 
   </script> 

  ]]>
 </Content> 
</Module>

Dodatkowo wykorzystaliśmy dynamiczną zmianę wysokości gadżetu (gadgets.window.adjustHeight()). Jest to możliwe po załadowaniu odpowiedniej biblioteki (<Require feature="dynamic-height" />) w sekcji <ModulePrefs>.
Po dodaniu gadżet prezentuje się następująco:

Gotowy gadżet jest dostępny do dodania do bloga pod adresem: http://sites.google.com/site/kodatnikfiles/xml/DrugiGadzet.xml