CalVis：为 Google 日历创建自定义 AJAX 用户界面

Austin Chau，Google 开发者计划
2008 年 6 月

注意 - 这是一个由 Google 员工（而不是官方支持的库）启动的开源项目。我们诚邀所有有兴趣参加并做出贡献的人 :)

简介

您是否曾希望使用 Google 日历数据在网站上创建自定义日历体验，但又不确定如何直观呈现日历数据？似乎有很多开发者在遇到这种困境。虽然 Google Calendar Data API 是一个功能强大的网络服务 API，可让您充分利用所有 Google 日历数据，但它仍然是一个纯读/写数据 API，不进行数据可视化预配。

在本文中，我将展示为减轻这个问题而编写的一个示例库。我创立了开源项目“日历可视化”(CalVis)，旨在提供简单且可自定义的界面 (UI)，用以展示来自 Google 日历帐号的数据。CalVis 通过 Google Calendar Data API 直接从您的 Google 日历帐号中提取数据。（编者注：从 v3 开始，Google 日历不再使用 Google 数据格式。）它利用下方的 Google 数据 JavaScript 客户端库与 Google 日历进行通信，旨在最大限度地提高自定义的灵活性。

CalVis 旨在让开发者不必重新创建丰富的日历界面体验。开发者可以将其用作可自定义的模板容器，以叠加 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 的界面组件如下：

  • 登录控件（仅适用于私密日历）
    此 HTML 组件用于提供登录/退出登录链接。
  • 状态控制
    这是提供状态信息或错误的 HTML 组件。
  • Navigation Control
    这是一个 HTML 组件，用于呈现相对于当前视图的日历导航。
  • 视图控件
    这是用于呈现日历视图选择的 HTML 组件，只有此版本中的月视图或周视图可用。
  • 日历正文
    这是用于呈现实际日历的 HTML 组件。使用网格指定单个日期单元格。
  • 事件显示
    这是在事件触发器时呈现事件详情的 HTML 组件。此版本仅支持“click”和“mouseover”事件触发器。

以下示例展示了如何使用基本 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 布局中定义），以映射到相应的日历界面组件。 

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()方法以显示日历界面 - 
// 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 代码项目托管上通过 Subversion 下载。

资源