تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

أوستن تشاو، برامج المطوّرين في Google
يونيو 2008

مقدمة
استخدام CalVis
تخصيص النمط
عرض توضيحي
المساهمة
المراجع

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

مقدمة

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

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

يمكنك تخصيص أي من السلوك أو المظهر باستخدام JavaScript. يُرجى العِلم أنّه قبل أن تتمكّن من تعديل عنصر في 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('');
}

أخيرًا، يمكنك ضبط العرض التلقائي للتقويم (إما عرض "الشهر" أو عرض "الأسبوع") واستدعاء طريقة render() لعرض واجهة مستخدم التقويم:

// set the default view to be "month"
calendar.setDefaultView('month');

// display the calendar
calendar.render();

تخصيص النمط

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

عرض توضيحي

يوضّح هذا العرض التوضيحي كيفية استخدام CalVis مع التنسيق التلقائي.

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

المساهمة

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

CalVis: إنشاء واجهة مستخدم مخصّصة تعتمد على AJAX لـ "تقويم Google" تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.