CalVis：為 Google 日曆建立自訂 AJAX UI

Google 開發人員計畫 Austin Chau
2008 年 6 月

注意 - 這是由 Google 員工發起的開放原始碼專案，並非官方支援的程式庫。歡迎有興趣的人加入並貢獻心力 :)

簡介

您是否曾想在網站上使用 Google 日曆資料建立自訂日曆體驗，但不知道如何以視覺化方式呈現日曆資料？似乎有許多開發人員面臨這個兩難局面。Google Calendar Data API 是一項功能強大的網路服務 API，可讓您存取所有 Google 日曆資料，但這項 API 僅供讀取/寫入資料，無法用於資料視覺化。

在本文中，我將示範我編寫的範例程式庫，以解決這個問題。我啟動了名為「日曆視覺化」(CalVis) 的開放原始碼專案，目標是提供簡單易用的自訂使用者介面 (UI)，呈現 Google 日曆帳戶的資料。CalVis 會透過 Google Calendar Data API，直接從 Google 日曆帳戶提取資料。(編輯者附註：自第 3 版起，Google 日曆不再使用 Google 資料格式。) 這個範例會使用底下的 Google Data JavaScript 用戶端程式庫與 Google 日曆通訊，並盡可能提供彈性，方便您自訂。

CalVis 的設計宗旨是讓開發人員不必重新建立豐富的日曆 UI 體驗。開發人員可將其做為可自訂的範本容器，用來疊加 Google 日曆資料。開發人員可以使用 CalVis 顯示日曆資料，並與網站進行深層自訂整合。您會發現，透過 JavaScript、HTML 和 CSS，完全可以自訂建構在 CalVis 上的介面。開發人員可以透過一組基本的日曆控制項元件，快速輕鬆地部署自訂日曆介面，以便算繪日曆資料。

使用 CalVis

請按照下列步驟開始使用 CalVis 進行開發。

步驟 1 - 載入日曆視覺化程式庫

首先，您需要在 HTML 檔案中加入載入器。這個載入器會動態載入 CalVis 的核心類別，以及其依附元件程式庫 (例如 Google Data JavaScript 用戶端程式庫)。

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

步驟 2 - 使用 CSS 樣式表說明樣式屬性。

預設 CSS 檔案會產生預設的外觀和風格，就像這個範例一樣。您可以下載這個 CSS 檔案並自訂，打造完全不同的外觀。 

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

步驟 3 - 使用 HTML 規劃日曆介面的視覺結構

CalVis 具有多個預先定義的視覺化元件，可組成日曆介面。這些介面元件的結構排列方式是由 HTML 版面配置定義。

CalVis 的 UI 元件如下：

  • 登入控制項 (僅適用於私人日曆)
    ：這是提供登入/登出連結的 HTML 元件。
  • 狀態控制項
    ：這個 HTML 元件會提供狀態資訊或錯誤。
  • 導覽控制項
    ：這是 HTML 元件，會根據目前檢視畫面算繪日曆導覽。
  • 檢視控制項
    這是用於算繪日曆檢視畫面選取範圍的 HTML 元件，這個版本僅提供月或週檢視畫面。
  • 日曆主體
    這是用來算繪實際日曆的 HTML 元件。使用格線指定個別日期儲存格。
  • 活動顯示
    ：這是 HTML 元件，會在觸發活動時算繪活動詳細資料。這個版本僅支援「點擊」和「滑鼠懸停」事件觸發條件。

以下範例說明如何使用基本 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>

步驟 4 - 使用 JavaScript 初始化及設定 CalVis

你可以使用 JavaScript 自訂任何行為或外觀。請注意，您必須先讓瀏覽器載入物件，才能在 JavaScript 中修改物件，因此您必須先等待 CalVis 載入器載入所有相依程式庫，這項作業可透過 calvis.ready() 方法完成。這個方法會採用回呼方法，在載入所有程式庫且 CalVis 準備就緒時叫用。

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

在回呼函式中，您會例項化 calvis.Calendar 物件的例項。 現在您必須將各種 CSS ID (這些 ID 是在步驟 3 的 HTML 版面配置中定義) 指派給對應的日曆 UI 元件。 

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');

現在你可以指定 CalVis 應從哪個 Google 日曆帳戶提取資料。如要指定公開日曆：

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

如要指定私人日曆，您也需要指定與登入按鈕對應的 HTML 元件 - 

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

如要顯示活動詳細資料，您必須提供回呼方法，以便在日曆上的活動清單觸發時 (透過「click」或「mouseover」事件)，系統會叫用回呼來顯示活動詳細資料。事件顯示回呼範例：

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('');
}
最後，您可以設定日曆的預設檢視畫面 (「月」或「週」檢視畫面)，並叫用 render() 方法來顯示日曆 UI - 
// set the default view to be "month"
calendar.setDefaultView('month');

// display the calendar
calendar.render();

自訂樣式

如要自訂個別日期儲存格的大小、顏色或樣式，只要修改幾個預先定義的 CSS 類別的 CSS 樣式屬性即可。舉例來說，您可以覆寫預設的 CSS 類別 monthViewCell 和 contentCell，修改月檢視畫面中每個日期儲存格的寬度和高度。

示範

這個示範會說明如何使用 CalVis 搭配預設樣式。

這項示範會說明如何使用 CalVis 搭配自訂功能，與 Google 地圖和 YouTube API 建立混搭內容。

提供圖像

CalVis 是開放原始碼專案，您可以在 Google Code Project Hosting 上透過 Subversion 下載原始碼。

資源