CalVis: tworzenie niestandardowego interfejsu AJAX dla Kalendarza Google

Austin Chau, Google Developer Programs
Czerwiec 2008 r.

Uwaga: jest to projekt open source rozpoczęty przez pracownika Google, a nie oficjalnie obsługiwana biblioteka. Zapraszamy wszystkich zainteresowanych do dołączenia i współtworzenia tej społeczności.

Wprowadzenie

Czy zdarzyło Ci się kiedyś chcieć utworzyć w swojej witrynie spersonalizowany kalendarz na podstawie danych z Kalendarza Google, ale nie wiedzieć, jak wizualnie zaprezentować te dane? Wielu deweloperów ma podobny problem. Interfejs Google Calendar Data API to zaawansowany interfejs API usługi internetowej, który umożliwia korzystanie z bogactwa wszystkich danych Kalendarza Google. Jest to jednak interfejs API do odczytu i zapisu danych, który nie zapewnia wizualizacji danych.

W tym artykule pokażę przykładową bibliotekę, którą napisałem, aby rozwiązać ten problem. Rozpocząłem projekt open source Calendar Visualization (CalVis), którego celem jest zapewnienie łatwego w obsłudze i konfigurowaniu interfejsu użytkownika do prezentowania danych z konta Kalendarza Google. CalVis pobiera dane bezpośrednio z Twojego konta Kalendarza Google za pomocą interfejsu Google Calendar Data API. (Uwaga redakcyjna: od wersji 3 Kalendarz Google nie używa już formatu danych Google). Do komunikacji z Kalendarzem Google używa biblioteki klienta Google Data JavaScript i została zaprojektowana tak, aby zmaksymalizować elastyczność dostosowywania.

CalVis ma na celu ułatwienie deweloperom pracy, ponieważ nie muszą oni ponownie tworzyć rozbudowanego interfejsu kalendarza. Deweloperzy mogą używać go jako kontenera z szablonem, który można dostosować, aby nakładać dane z Kalendarza Google. Deweloperzy mogą używać CalVis do renderowania danych kalendarza i osiągania zaawansowanego poziomu dostosowanej integracji z witrynami. Jak się przekonasz, interfejs oparty na CalVis można w pełni dostosować za pomocą JavaScript, HTML i CSS. Deweloperzy będą mogli szybko i łatwo wdrażać dostosowany interfejs kalendarza z zestawem podstawowych komponentów sterujących kalendarzem do renderowania danych kalendarza.

Korzystanie z CalVis

Poniższe czynności pomogą Ci rozpocząć korzystanie z CalVis w procesie programowania.

Krok 1. Wczytaj bibliotekę wizualizacji kalendarza

Najpierw musisz dodać moduł wczytujący do pliku HTML. Ten moduł wczytuje dynamicznie podstawowe klasy CalVis oraz biblioteki zależne (np. bibliotekę klienta JavaScript Google Data). 

<script src="//gcal.appspot.com/calvis/calvis.js" type="text/javascript"></script>

Krok 2. Użyj arkusza stylów CSS, aby opisać atrybuty stylu.

Domyślny plik CSS zapewnia domyślny wygląd, taki jak w tym przykładzie. Możesz pobrać ten plik CSS i go dostosować, aby uzyskać zupełnie inny wygląd. 

<link rel="stylesheet" type="text/css" href="//gcal.appspot.com/calvis/default.css" />

Krok 3. Określ wizualną strukturę interfejsu kalendarza za pomocą kodu HTML

CalVis ma kilka predefiniowanych komponentów wizualnych, które składają się na interfejs kalendarza. Układ tych komponentów interfejsu jest określony przez układ HTML.

Komponenty interfejsu CalVis to:

  • Kontrola logowania (tylko w przypadku kalendarzy prywatnych)
    To komponent HTML, który zawiera link do logowania i wylogowywania.
  • Status Control
     – komponent HTML, który zawiera informacje o stanie lub błędach.
  • Element sterujący nawigacją
     Jest to komponent HTML, który renderuje nawigację po kalendarzu w odniesieniu do bieżącego widoku.
  • View Control
    To komponent HTML, który renderuje wybór widoku kalendarza. W tej wersji dostępne są tylko widoki miesiąca i tygodnia.
  • Treść kalendarza
     jest to komponent HTML, który renderuje rzeczywisty kalendarz. z siatkami wyznaczającymi poszczególne komórki daty;
  • Wyświetlanie zdarzenia
     – komponent HTML, który renderuje szczegóły zdarzenia po jego wywołaniu. W tej wersji obsługiwane są tylko wyzwalacze zdarzeń „kliknięcie” i „najazd myszą”.

Przykład wizualnego rozmieszczenia tych komponentów przy użyciu podstawowej struktury tabeli HTML: 

  <table style="width: 800px;">
    <tr>
      <td colspan="2" valign="top">
        <div style="float: left;" id="loginControlDiv"></div>
        <div style="float: right;" id="statusControlDiv"></div>
      </td>
    </tr>      
    <tr>
      <td valign="top">
        <div id="navControlDiv"></div>
      </td>
      <td valign="top" align="right">
        <div id="viewControlDiv"></div>
      </td>
    </tr>
    <tr>
      <td colspan="2" valign="top">
        <div id="calendarBodyDiv"></div>
      </td>
    </tr>
    <tr>
      <td colspan="2" valign="top">
        <div id="eventDisplayDiv"></div>
      </td>
    </tr>
  </table>

Krok 4. Zainicjuj i skonfiguruj CalVis za pomocą JavaScriptu

Za pomocą JavaScriptu możesz dostosować dowolne działanie lub wygląd. Pamiętaj, że zanim zmodyfikujesz obiekt w JavaScript, musi on zostać najpierw załadowany przez przeglądarkę. Musisz więc poczekać, aż wszystkie biblioteki zależne zostaną załadowane za pomocą narzędzia do ładowania CalVis. Możesz to zrobić za pomocą metody calvis.ready(). Ta metoda przyjmuje funkcję wywołania zwrotnego, która zostanie wywołana, gdy wszystkie biblioteki zostaną wczytane, a CalVis będzie gotowy do użycia. 

window.onload = function() {
  calvis.ready(callback);
}

W funkcji wywołania zwrotnego utworzysz instancję obiektu calvis.Calendar. Teraz musisz przypisać różne identyfikatory CSS (zdefiniowane w układzie HTML w kroku 3) do odpowiednich komponentów interfejsu kalendarza. 

var calId = 'developer-calendar@google.com';

var calendar = new calvis.Calendar();

// set the CSS IDs for various visual components for the calendar container
calendar.setCalendarBody('calendarBodyDiv');
calendar.setStatusControl('statusControlDiv');
calendar.setNavControl('navControlDiv');
calendar.setViewControl('viewControlDiv');

Możesz teraz określić, z którego konta Kalendarza Google ma pobierać dane CalVis. Aby określić kalendarz publiczny: 

// set the calenar to pull data from this Google Calendar account
calendar.setPublicCalendar(calId);

Aby określić kalendarz prywatny, musisz też podać komponent HTML odpowiadający przyciskowi logowania: 

// set the calenar to pull data from this Google Calendar account
calendar.setPrivateCalendar(calId);
calendar.setLoginControl('loginControlDiv');

Aby wyświetlić szczegóły wydarzenia, musisz podać metodę wywołania zwrotnego, tak aby po wywołaniu listy wydarzeń w kalendarzu (zdarzeniem „click” lub „mouseover”) wywoływane było wywołanie zwrotne w celu wyświetlenia szczegółów wydarzenia. Przykład wywołania zwrotnego wyświetlania zdarzenia: 

calendar.setEventCallback('click', displayEvent);

function displayEvent(event) {    
  var title = event.getTitle().getText();  
  var date = event.getTimes()[0].getStartTime().getDate();
  var content = event.getContent().getText();  
  
  var eventHtml = [;
  eventHtml.push(date.toString());
  eventHtml.push('<br><br>');
  eventHtml.push('<b>Event title:</b> ');
  eventHtml.push(title);
  eventHtml.push('<br>');
  eventHtml.push('<br>');
  eventHtml.push('<b>Description:</b>');
  eventHtml.push('<p style="font-size: 11px;">');
  eventHtml.push(content); 
  eventHtml.push('</p>');
  eventHtml.push('<br>');

  document.getElementById('eventDisplayDiv').innerHTML = eventHtml.join('');
}
Na koniec możesz ustawić domyślny widok kalendarza (widok „miesiąc” lub „tydzień”) i wywołać metodę render(), aby wyświetlić interfejs kalendarza: 
// set the default view to be "month"
calendar.setDefaultView('month');

// display the calendar
calendar.render();

Dostosowywanie stylu

Aby dostosować rozmiar, kolor lub styl poszczególnych komórek daty, wystarczy zmodyfikować atrybuty stylów CSS kilku predefiniowanych klas CSS. Możesz na przykład zmienić szerokość i wysokość każdej komórki daty w widoku miesiąca, zastępując domyślne klasy CSS monthViewCell i contentCell.

Prezentacja

Ten film demonstracyjny pokazuje, jak używać CalVis ze stylem domyślnym.

Ten przykład pokazuje, jak używać CalVis z dostosowaniem do tworzenia mash-upów z interfejsami Google Maps i YouTube API.

Publikuj

CalVis to projekt open source, którego kod źródłowy można pobrać za pomocą Subversion na stronie Google Code Project Hosting.

Zasoby