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

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

注意 - 这是一个由 Google 员工发起的开源项目，不是官方支持的库。欢迎所有感兴趣的人加入并贡献力量 :)

简介

您是否曾想过使用 Google 日历数据在网站上打造自定义日历体验，但不太确定如何直观地呈现日历数据？似乎有很多开发者都面临着同样的困境。虽然 Google Calendar Data API 是一款功能强大的 Web 服务 API，可让您充分利用所有 Google 日历数据的丰富性，但它仍然是一款纯粹的读/写数据 API，不提供数据可视化功能。

在本文中，我将演示一个我编写的示例库，以缓解此问题。我启动了开源项目“日历可视化”(CalVis)，旨在提供一个简单且可自定义的用户界面 (UI)，用于呈现 Google 日历账号中的数据。CalVis 通过 Google Calendar Data API 直接从您的 Google 日历账号提取数据。（编者注：自 v3 起，Google 日历不再使用 Google 数据格式。）它在底层使用 Google Data 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 组件用于提供状态信息或错误。
  • 导航控件
    此 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 布局定义的）分配给相应的日历界面组件。 

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

为了显示活动详情，您需要提供一个回调方法，以便在日历上的活动列表被触发（通过“点击”或“鼠标悬停”事件）时，系统会调用该回调来显示活动详情。事件显示回调的示例- 

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 Maps 和 YouTube API 的混搭。

贡献

CalVis 是一个开源项目，其源代码可在 Google Code Project Hosting 上通过 Subversion 下载。

资源