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

Austin Chau，Google Developers 計畫
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 來轉譯日曆資料，並且與網站進行深度的自訂整合。如您所知，以 CalVis 為基礎打造的介面可完全透過 JavaScript、HTML 和 CSS 進行自訂。開發人員可以快速輕鬆地部署自訂日曆介面，並搭配一組重要的日曆控制項元件來呈現日曆資料。

使用 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 (在步驟 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');

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

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

如要顯示活動詳細資訊，您必須提供回呼方法，讓日曆上的活動清單 (透過「按一下」或「滑鼠懸停」事件) 被觸發時，系統會叫用回呼以顯示活動詳細資訊。事件顯示回呼的範例：

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('');
}
最後，您可以設定日曆的預設檢視模式 (「月」或「週」)，並叫用轉譯()方法，藉此顯示日曆 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 下載。

資源