CalVis: יצירת ממשק משתמש AJAX מותאם אישית עבור יומן Google

אוסטין צ'או, תוכניות למפתחים של Google
יוני 2008

הערה - זהו פרויקט בקוד פתוח שהתחיל צוות גוגלרים ולא ספרייה שנתמכת באופן לא רשמי. אנו מזמינים את כל מי שמעוניין להצטרף ולתרום :)

מבוא

האם רצית אי פעם ליצור חוויית יומן מותאמת אישית באתר שלך באמצעות נתוני יומן Google, אבל אתה לא בטוח כיצד להציג את נתוני היומן באופן ויזואלי? נראה שיש לא מעט מפתחים שחולקים את הדילמה הזו. אמנם ממשק ה-API לשילוב נתונים ביומן Google הוא ממשק API עוצמתי לשירות אינטרנט, שכן הוא מאפשר לך להתעמק בשפע של כל נתוני יומן Google שלך, אך הוא נשאר ממשק API לקריאה/כתיבה טהור ללא צורך בהצגה חזותית של נתונים.

במאמר הזה אני אדגים ספרייה לדוגמה שכתבתי כדי לפתור את הבעיה הזו. יצרתי את פרויקט הקוד הפתוח 'תצוגה חזותית של יומן' (CalVis), שמטרתו לספק ממשק משתמש (UI) קל שניתן להתאים אישית, כדי להציג נתונים מחשבון יומן Google. נתוני CalVis שליפת נתונים ישירות מחשבון יומן Google שלך באמצעות ממשק API של יומן Google. (הערה של העורך: החל מגרסה 3, יומן Google כבר לא משתמש בפורמט הנתונים של Google.) האפליקציה משתמשת בספריית הלקוחות של JavaScript מסוג Google Data כדי ליצור קשר עם יומן Google, ומיועדת לאפשר גמישות מקסימלית בהתאמה אישית.

המטרה של CalVis היא למנוע ממפתחים ליצור מחדש את ממשק המשתמש העשיר של היומן. המפתחים יכולים להשתמש בו כמאגר תגים שניתן להתאים אישית כדי להציג נתונים של יומן Google. מפתחים יכולים להשתמש ב-CalVis כדי לעבד נתוני יומן ולהגיע לרמה עמוקה של שילוב מותאם אישית עם האתרים שלהם. כפי שתלמד, ממשק שמבוסס על CalVis ניתן להתאמה אישית מלאה באמצעות JavaScript, 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

ניתן להתאים אישית כל התנהגות או מראה באמצעות JavaScript. חשוב לזכור שכדי לשנות אובייקט ב-JavaScript, צריך לטעון אותו תחילה באמצעות הדפדפן. לכן, צריך לחכות עד שכל הספריות התלויות ייטענו בעזרת ה-CalVis, זה מתבצע בשיטת calvis.ready() . השיטה הזו משתמשת בשיטת קריאה חוזרת (callback) שיופעלו בכל טעינה של כל הספריות ו-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');

כדי להציג את פרטי האירוע, עליכם להגדיר שיטת התקשרות חזרה. כך, כשיתבצע רישום של אירוע ביומן (פעולה של קליק או אירוע של 'עכברה'), הקריאה החוזרת תוצג כדי להציג את פרטי האירוע. דוגמה לקריאה חוזרת (callback) של אירוע: 

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 שהוגדרו מראש. למשל, אפשר לשנות את הרוחב והגובה של כל תא תאריכים בתצוגת חודש על ידי ביטול ברירת המחדל של ה- וה-contentCell של מחלקת CSS.

הדגמה

ההדגמה הזו מדגימה את השימוש ב-CalVis עם סגנון ברירת המחדל.

הדגמה זו עם CalVis בהתאמה אישית כדי ליצור 'מיזוג' עם מפות Google ו-YouTube API.

הוספת תוכן

CalVis פרויקט קוד פתוח, שקוד המקור שלו זמין להורדה דרך Subversion ב-Google Code Project Hosting.

משאבים