CalVis: إنشاء واجهة مستخدم AJAX مخصصة لتقويم Google

أوستن تشاو، برامج مطوّري برامج Google
حزيران (يونيو) 2008

ملاحظة - هذا المشروع مفتوح المصدر بدأه موظف Google وليس مكتبة مدعومة رسميًا. ندعو جميع المهتمين بالانضمام والمساهمة :)

المقدمة

هل أردت من قبل إنشاء تجربة تقويم مخصصة على موقع الويب باستخدام بيانات تقويم Google ولكنك لست متأكدًا تمامًا من كيفية تقديم بيانات التقويم بشكل مرئي؟ يبدو أن هناك عددًا كبيرًا من مطوّري البرامج الذين يتشاركون هذه المعضلة. على الرغم من أن واجهة برمجة التطبيقات لبيانات تقويم Google عبارة عن واجهة برمجة تطبيقات فعالة لخدمات الويب، حيث تتيح لك إمكانية الاستفادة من جميع بيانات تقويم Google، إلا أنها تظل واجهة برمجة تطبيقات بيانات قراءة/كتابة خالصة بدون شرط لعرض البيانات.

في هذه المقالة، سأوضح نموذجًا للمكتبة التي كتبتها للتخفيف من هذه المشكلة. لقد بدأتُ المشروع المفتوح المصدر، "التمثيل البصري للتقويم" (CalVis)، الذي يهدف إلى توفير واجهة مستخدم سهلة الاستخدام وقابلة للتخصيص لتقديم البيانات من حساب "تقويم Google". تسحب CalVis البيانات مباشرةً من حسابك على "تقويم Google" عبر Google Calendar Data API. (ملاحظة من المحرر: اعتبارًا من الإصدار 3، لن يستخدم تقويم Google تنسيق بيانات Google بعد الآن.) وتستفيد من مكتبة برامج JavaScript لبيانات Google أسفلها للتواصل مع "تقويم Google"، وهي مصمّمة لتحقيق أقصى قدر من المرونة في عملية التخصيص.

تم تصميم CalVis لتجنيب مطوّري البرامج من الحاجة إلى إعادة إنشاء تجربة واجهة مستخدم تقويم غنية. يمكن للمطورين استخدامه كحاوية نموذج قابلة للتخصيص لتراكب بيانات تقويم Google. يمكن لمطوّري البرامج استخدام CalVis لعرض بيانات التقويم وتحقيق مستوى عميق من التكامل المخصص مع مواقعهم. كما تعلم، فإن الواجهة التي تم إنشاؤها فوق CalVis قابلة للتخصيص تمامًا من خلال جافا سكريبت وHTML وCSS. سيكون بإمكان مطوري البرامج نشر واجهة تقويم مخصصة بسرعة وسهولة مع مجموعة من عناصر التحكم في التقويم الأساسية لعرض بيانات التقويم.

استخدام CalVis

تساعدك الخطوات التالية على البدء في استخدام CalVis من أجل التطوير.

الخطوة 1 - تحميل مكتبة "التمثيل البصري للتقويم"

عليك أولاً تضمين أداة التحميل في ملف HTML. يحمّل برنامج التحميل هذا بشكل أساسي الفئات الأساسية من CalVis بالإضافة إلى مكتباته التابعة (مثل مكتبة عميل JavaScript لـ Google Data). 

<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: إعداد CalVis وضبطه باستخدام JavaScript

يمكنك تخصيص أي من السلوك أو المظهر باستخدام جافا سكريبت. ضع في اعتبارك أنه قبل أن تتمكن من تعديل كائن في جافا سكريبت، يجب تحميله أولاً من خلال المتصفح، لذا يلزمك أولاً الانتظار حتى يتم تحميل جميع المكتبات التابعة باستخدام برنامج تحميل CalVis، ويتم ذلك باستخدام طريقة calvis.ready(). وتتّبع هذه الطريقة طريقة رد اتصال سيتم استدعاؤها عند تحميل جميع المكتبات وعندما تكون CalVis جاهزة للاستخدام. 

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

داخل دالة رد الاتصال، سيتم إنشاء مثيل من كائن calvis.Calendar. يتعين عليك الآن تعيين مختلف معرفات CSS (والتي يتم تحديدها من تنسيق HTML في الخطوة 3) للتعيين إلى مكونات واجهة مستخدم التقويم المقابلة. 

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('');
}
أخيرًا، يمكنك ضبط طريقة العرض التلقائية للتقويم (إما طريقة عرض "الشهر" أو "الأسبوع") واستدعاء طريقة العرض() لعرض واجهة مستخدم التقويم. 
// set the default view to be "month"
calendar.setDefaultView('month');

// display the calendar
calendar.render();

تخصيص النمط

لتخصيص حجم خلية تاريخ فردية أو لونها أو نمطها، ما عليك سوى تعديل سمات نمط CSS لبعض فئات CSS المحدّدة مسبقًا. على سبيل المثال، يمكنك تعديل عرض وارتفاع كل خلية تاريخ في طريقة عرض الشهر من خلال إلغاء الفئة الافتراضية لشهر monthViewCell وcontentخلية افتراضية.

تجريبي

يوضح هذا العرض التوضيحي استخدام CalVis مع النمط الافتراضي.

يوضّح هذا العرض التوضيحي استخدام CalVis مع تخصيص عملية إنشاء مزج باستخدام "خرائط Google" وYouTube API.

المساهمة

CalVis مشروع مفتوح المصدر، الذي يتوفر رمزه المصدر للتنزيل عبر Subversion على Google Code Project Hosting.

الموارد